API Reference
import requests # 1. Authenticate res = requests.post("https://neer.co.ke/api/v1/auth/login/", json={ "email": "owner@myshop.co.ke", "password": "your_password", }) token = res.json()["data"]["access"] # 2. Fetch products headers = {"Authorization": f"Bearer {token}"} products = requests.get( "https://neer.co.ke/api/v1/products/", headers=headers, params={"in_stock": True, "page_size": 25} ) print(products.json()["data"]) # [{name, price, qty, ...}]
API Status: All systems operational. Base URL: https://neer.co.ke/api/v1/ — View API reference ↗
Quick Start Guide
Make your first API call in under 5 minutes. No SDK required — plain HTTP works everywhere.
- 1
Get your credentials
Log in to NEER POS → Settings → Developers → Create API Key. Or use your shop owner email and password for JWT auth.
- 2
Authenticate and get your token
POST your credentials to the login endpoint. You'll get an
accesstoken and arefreshtoken. The access token expires in 60 minutes. - 3
Include the token in every request
Add
Authorization: Bearer <your_token>to every request header. That's it. - 4
Start building
Browse the endpoint reference, copy the code examples, and build your integration. All responses follow the same JSON format.
Your first request
import requests # Step 1 — Login and get JWT token response = requests.post( "https://neer.co.ke/api/v1/auth/login/", json={ "email": "owner@myshop.co.ke", "password": "your_password" } ) data = response.json() token = data["data"]["access"] shop = data["data"]["shop"] print(f"Logged in as {shop['name']}") # Step 2 — Use the token in all requests headers = {"Authorization": f"Bearer {token}"} # Step 3 — Fetch products products = requests.get( "https://neer.co.ke/api/v1/products/", headers=headers, params={"in_stock": True, "page_size": 25} ) print(products.json()["data"])
Response format
Every endpoint returns the same JSON envelope — success or error:
{
"success": true,
"message": "Products retrieved.",
"data": [ ... ], // array or object
"errors": {}, // field errors on validation failure
"meta": {
"count": 100,
"total_pages": 4,
"current_page": 1,
"next": "/api/v1/products/?page=2",
"previous": null
}
}
Authentication
NEER POS API supports two authentication methods — JWT for user-facing apps and API Keys for server-to-server integrations.
JWT Bearer Tokens
JWT tokens are the default authentication method. Login with your email and password to get an access token (valid 60 minutes) and a refresh token (valid 30 days).
API Keys
For server-to-server integrations, generate an API key in your account settings and pass it as a header:
# JWT token Authorization: Bearer eyJhbGciOiJIUzI1NiIs... # API key (alternative) X-API-Key: neer_abc123xyz...
Best practice: Use JWT for interactive apps (Flutter, React). Use API Keys for automated scripts and server integrations. API Keys support scopes to limit what each key can access.
API Key Scopes
| Scope | Access |
|---|---|
read | GET requests — products, customers, sales, inventory |
write | Create and update records |
sales | Create and view sales transactions |
inventory | Stock adjustments and inventory management |
reports | Dashboard and analytics data |
admin | Full access — treat like a master key |
Products & Inventory
Manage your product catalog, categories, stock levels, and adjustments.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| search | string | Search by name or code |
| category | integer | Filter by category ID |
| in_stock | boolean | Only products with quantity > 0 |
| min_price | number | Minimum selling price |
| max_price | number | Maximum selling price |
| page | integer | Page number (default: 1) |
| page_size | integer | Results per page (default: 25, max: 100) |
| ordering | string | Sort by name, price, quantity (prefix - to reverse) |
Sales & POS
Access sales history, line items, payment records, and daily summaries.
Note: Sales are created via the POS terminal app or the web interface. The API provides read access to all sales records with full filtering and pagination.
AI APIs Beta
AI powers automated business insights, receipt parsing, and stock recommendations — all via simple REST endpoints.
Rate limited: AI endpoints are limited to 20 requests per hour per user. Plan requests accordingly. Insights are auto-generated nightly — you only need to trigger manually for real-time updates.
Offline Sync
APIs designed for mobile apps that need to work offline — download the catalog, queue sales locally, and sync when connected.
Recommended sync strategy
- 1
On app launch
Call
GET /sync/status/to get entity counts. If counts differ from local SQLite, pull new data. - 2
Download catalog
Call
GET /sync/products/?page_size=500in pages. Store in local SQLite for offline use. - 3
Process sales offline
When offline, queue sales in local storage (SQLite or SharedPreferences). Record timestamp and all line items.
- 4
Sync on reconnect
When connectivity is restored,
POST /sync/sales/upload/with the queued array. Max 50 per request.
Error Codes
All errors follow the same JSON format. Check the errors field for field-level validation details.
{
"success": false,
"message": "Validation failed.",
"data": {},
"errors": {
"price": ["Price must be greater than 0."],
"name": ["This field is required."]
},
"meta": {}
}Bad Request
Validation failed. Check the errors object for field-specific messages.
Unauthorized
Token is missing, expired, or invalid. Refresh your access token or log in again.
Forbidden
Your role or API key scope doesn't permit this action.
Not Found
The resource doesn't exist or doesn't belong to your shop.
Rate Limited
Too many requests. Check Retry-After header. Default: 1,000 req/hour.
Server Error
Unexpected error on our side. Retry with exponential backoff. Contact support if persistent.
Rate Limits
| Client Type | Limit | Window |
|---|---|---|
| Unauthenticated | 60 requests | Per hour |
| JWT authenticated user | 1,000 requests | Per hour |
| API Key | 5,000 requests | Per hour |
| Login endpoint | 10 attempts | Per minute |
| AI endpoints | 20 requests | Per hour |
When rate limited you'll receive HTTP 429. Check the Retry-After response header for how long to wait before retrying.
SDKs & Tools
pip install neer-pos — Pythonic wrapper for all endpoints.npm install @neer/sdk — Works in Node.js and the browser.neer_pos_sdk: ^1.0.0 — Built-in offline sync support.composer require neer/api — For Shopify/WooCommerce bridges.Official SDKs are currently in development. In the meantime, use the API Reference or download the OpenAPI schema to generate a client in any language.
API Playground
Test any endpoint directly in your browser without writing code. The interactive Swagger UI has every endpoint documented with examples.
Status & Uptime
FAQ
How long do access tokens last?
Access tokens expire after 60 minutes. Use the refresh token to get a new one — refresh tokens last 30 days. On logout, the refresh token is blacklisted.
Can I use the API without creating an account?
No — every API call is scoped to an authenticated shop. You need a NEER POS account and at least one approved shop to generate tokens or API keys.
Are API calls available on all plans?
Core endpoints (products, sales, customers) are available on all plans. AI endpoints require Standard or Pro. Higher plan = higher rate limits.
How do I handle pagination?
Use ?page=N&page_size=25. Check meta.next — it's null when you've reached the last page. Max page_size is 100.
Is there a sandbox environment?
Not yet — but the 30-day free trial gives you a production account with demo data to build against. All data can be wiped when ready to go live.
I'm getting 403 on some endpoints. Why?
Your user role doesn't have permission for that action. Owners and admins have full access. Cashiers can only access POS, sales, and customers. Check the permissions table above.