NEER POS NEER POS Developers
Changelog API Docs Get API Key →

API Reference

quickstart.py
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. 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. 2

    Authenticate and get your token

    POST your credentials to the login endpoint. You'll get an access token and a refresh token. The access token expires in 60 minutes.

  3. 3

    Include the token in every request

    Add Authorization: Bearer <your_token> to every request header. That's it.

  4. 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).

POST/api/v1/auth/login/Get access + refresh tokens
POST/api/v1/auth/refresh/Get a new access token
POST/api/v1/auth/logout/Blacklist the refresh token
GET/api/v1/auth/me/Current user + shop profile

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

ScopeAccess
readGET requests — products, customers, sales, inventory
writeCreate and update records
salesCreate and view sales transactions
inventoryStock adjustments and inventory management
reportsDashboard and analytics data
adminFull access — treat like a master key

Products & Inventory

Manage your product catalog, categories, stock levels, and adjustments.

GET/api/v1/products/List all products with filtering
POST/api/v1/products/Create a new product
GET/api/v1/products/{id}/Get product detail
PATCH/api/v1/products/{id}/Update product
POST/api/v1/products/{id}/adjust-stock/Add, subtract, or set stock
GET/api/v1/products/barcode/{code}/Find product by barcode
GET/api/v1/products/low-stock/Products below stock threshold
GET/api/v1/inventory/summary/Stock valuation and health

Query Parameters

ParameterTypeDescription
searchstringSearch by name or code
categoryintegerFilter by category ID
in_stockbooleanOnly products with quantity > 0
min_pricenumberMinimum selling price
max_pricenumberMaximum selling price
pageintegerPage number (default: 1)
page_sizeintegerResults per page (default: 25, max: 100)
orderingstringSort 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.

GET/api/v1/sales/List sales with date and payment filters
GET/api/v1/sales/{id}/Full sale detail with line items
GET/api/v1/sales/summary/Today's aggregated sales stats

AI APIs Beta

AI powers automated business insights, receipt parsing, and stock recommendations — all via simple REST endpoints.

Business Insights
Nightly analysis of revenue, inventory, purchasing, and cash flow.
Receipt Parsing
Upload a supplier receipt photo — AI extracts all items and prices.
Recommendations
AI-generated purchasing and stock level recommendations.
GET/api/v1/ai/insights/Latest AI business insights snapshot
POST/api/v1/ai/insights/Trigger a new AI analysis (runs immediately)
POST/api/v1/ai/receipt/Parse supplier receipt image with multipart/form-data
GET/api/v1/ai/recommendations/Purchasing and inventory recommendations

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.

GET/api/v1/sync/status/Server time + entity counts to check what needs syncing
GET/api/v1/sync/products/Download full product catalog (paginated, up to 1000)
GET/api/v1/sync/customers/Download customer list for offline lookup
POST/api/v1/sync/sales/upload/Upload queued offline sales in bulk (max 50)

Recommended sync strategy

  1. 1

    On app launch

    Call GET /sync/status/ to get entity counts. If counts differ from local SQLite, pull new data.

  2. 2

    Download catalog

    Call GET /sync/products/?page_size=500 in pages. Store in local SQLite for offline use.

  3. 3

    Process sales offline

    When offline, queue sales in local storage (SQLite or SharedPreferences). Record timestamp and all line items.

  4. 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": {}
}
400

Bad Request

Validation failed. Check the errors object for field-specific messages.

401

Unauthorized

Token is missing, expired, or invalid. Refresh your access token or log in again.

403

Forbidden

Your role or API key scope doesn't permit this action.

404

Not Found

The resource doesn't exist or doesn't belong to your shop.

429

Rate Limited

Too many requests. Check Retry-After header. Default: 1,000 req/hour.

500

Server Error

Unexpected error on our side. Retry with exponential backoff. Contact support if persistent.


Rate Limits

Client TypeLimitWindow
Unauthenticated60 requestsPer hour
JWT authenticated user1,000 requestsPer hour
API Key5,000 requestsPer hour
Login endpoint10 attemptsPer minute
AI endpoints20 requestsPer hour

When rate limited you'll receive HTTP 429. Check the Retry-After response header for how long to wait before retrying.


SDKs & Tools

Python SDK
pip install neer-pos — Pythonic wrapper for all endpoints.
JavaScript SDK
npm install @neer/sdk — Works in Node.js and the browser.
Flutter SDK
neer_pos_sdk: ^1.0.0 — Built-in offline sync support.
PHP SDK
composer require neer/api — For Shopify/WooCommerce bridges.
Postman Collection
Ready-to-use collection with all 45 endpoints and examples.
OpenAPI Spec
Download at /api/schema/ — Import into any API tool.

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.

Interactive API Explorer

Full Swagger UI with try-it-out enabled. Auth, run requests, inspect responses.

Open Playground ↗
● Live https://neer.co.ke/api/v1/ — 45 endpoints

Status & Uptime

API
99.9% uptime
~120ms
Auth
99.9% uptime
~80ms
AI Services
99.5% uptime
~2.1s
Database
99.99% uptime
~12ms

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.

Need help?

Our team responds within 24 hours on business days.