Introduction
The POS API gives other systems (accounting, e-commerce, mobile apps, reporting tools) secure access to the POS, CRM, HR, finance and project data in this installation. It is a JSON REST API.
- Base URL
https://your-store.example.com/api/v1- Version
v1(the version is part of the URL; breaking changes will get a new version, v1 keeps working)- Machine-readable
- OpenAPI 3 description for Postman, Insomnia or code generators
- Format
- JSON in and out, UTF-8, dates in ISO 8601 (UTC)
This page is generated from the code that runs the API, so it always matches it.
Authentication
Every endpoint except POST /auth/token needs a credential. A credential always acts as a user account and can never do more than that user is allowed to do in the app.
Access token (for apps where a person signs in)
Exchange a username and password for a token, then send it as a bearer token. Tokens last 12 hours and can be revoked with DELETE /auth/tokens/current. Accounts with two-factor sign-in must also send the 6-digit otp. Five wrong passwords in a row disable the account, as on the sign-in page.
curl -X POST "https://your-store.example.com/api/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{"username":"jane","password":"••••••••","otp":"123456","name":"Warehouse scanner"}'
curl "https://your-store.example.com/api/v1/products" -H "Authorization: Bearer mtk_3f9c…"
API key (for server-to-server integrations)
Create a key in Online store > API & Webhooks > Add API Key. The key acts as the person who created it, limited to Read only or Read and write, and can expire. It is shown once; only a hash is stored. Send it as X-API-Key: sk_live_… or Authorization: Bearer sk_live_…. Keys created before the API existed must be replaced.
Signed-in browser session
Pages of this application can call the API with the normal sign-in cookie when they send X-Requested-With: XMLHttpRequest from the same site. Cross-site requests are refused.
Headers
| Header | Direction | Meaning |
|---|---|---|
Authorization: Bearer … | request | Access token or API key. |
X-API-Key | request | API key (alternative to Authorization). |
Content-Type: application/json | request | Required when sending a body. |
X-Request-Id | response | Unique id of the request; also in error bodies. Quote it when asking for help. |
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | response | Your request allowance (see rate limits). |
Retry-After | response | Seconds to wait after a 429. |
Requests and responses
Successful responses:
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e5f6",
"name": "Rice 5kg"
},
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
Errors:
{
"success": false,
"message": "Some fields are missing or invalid",
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "sku",
"message": "is required"
}
],
"requestId": "106212402338339"
}
}
- Unknown fields in a body are ignored. Field names starting with
$or containing a dot are refused. - Passwords, password hashes, secrets, API keys and tokens are never returned.
- Money is returned as
{ "amount": 2200, "currency": "NGN" }or as plain numbers in reports.
Pagination, filtering, sorting
List endpoints accept:
| Parameter | Meaning |
|---|---|
page | Page number, from 1. |
limit | Items per page, default 25, maximum 100. |
sort | Comma-separated fields, - for descending, e.g. -createdAt,name. An unknown field returns 400 with the list of sortable fields. |
fields | Only return these fields, e.g. id,name,status. |
q | Search text (where offered). |
from, to | Date range YYYY-MM-DD; to includes the whole day (where offered). |
Each endpoint lists its own filters (status, category, store…) under Query parameters. The meta object gives page, limit, total, pages, hasNext and hasPrev.
GET https://your-store.example.com/api/v1/products?q=rice&category=Food&stock=low&sort=-updatedAt&page=2&limit=50&fields=id,name,sku,totalQuantityPermissions and scopes
Each endpoint names the app permission it needs (the same permissions as in Admin > Permissions, e.g. pos.products); any one of those listed is enough. Super admins can use everything. API permissions are always enforced.
API keys also have a scope. read allows GET requests, write allows everything; keys can be limited to modules (pos, crm, hr, finance, projects, reports, admin, notifications, auth), e.g. crm:write. Each endpoint shows the scope it needs. Store data is limited to the user's store unless the user can see all stores (pos.stores).
GET /admin/permissions lists every permission key.
Rate limits
- 120 requests per minute per token, API key or signed-in user.
- 10 sign-in attempts (
POST /auth/token) per IP address per 15 minutes, and a limit on failed credentials per IP. - When exceeded: status 429, code
RATE_LIMITEDand aRetry-Afterheader.
Errors and status codes
| Status | Code | Meaning |
|---|---|---|
| 200 | OK | The request worked. |
| 201 | Created | Something was created (token, product, order, customer, webhook…). |
| 400 | BAD_REQUEST | The request is malformed: invalid JSON, a bad id, or an unknown sort field. |
| 401 | UNAUTHORIZED | No credential, or it is wrong, expired or revoked. Also OTP_REQUIRED when a two-factor code is needed. |
| 403 | FORBIDDEN / INSUFFICIENT_SCOPE | The user lacks the permission (details.required names it), or the API key is not allowed this module or writes. ACCOUNT_DISABLED for disabled accounts. |
| 404 | NOT_FOUND | No such record, or it belongs to a store you cannot see. Also returned for unknown endpoints. |
| 405 | METHOD_NOT_ALLOWED | The path exists but not with this method; the Allow header lists the methods. |
| 409 | CONFLICT / ACTION_FAILED | Duplicate (e.g. username), not enough stock, or the action is not possible in the current state (e.g. cancelling a cancelled order). |
| 422 | VALIDATION_ERROR | One or more fields are missing or invalid; details lists each field and the problem. |
| 429 | RATE_LIMITED | Too many requests. Wait for the number of seconds in Retry-After. |
| 500 | INTERNAL_ERROR | Unexpected error. Nothing internal is revealed; quote the requestId to support. |
Webhooks
Webhooks send events from this system to another system as they happen. Set them up in Online store > API & Webhooks or with the webhook endpoints. Each webhook listens to the events you choose, or to all events.
What is sent
A POST to your URL with a JSON body:
{
"id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"event": "order.created",
"createdAt": "2026-10-02T09:15:00.000Z",
"source": "pos",
"storeId": "66f1c2a9e4b0a1b2c3d4e5f6",
"actor": {
"type": "user",
"id": "66f1c2a9e4b0a1b2c3d4e5f7",
"name": "Jane Doe"
},
"data": {
"order": {
"id": "66f1c2a9e4b0a1b2c3d4e5f8",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"total": {
"amount": 2200,
"currency": "NGN"
},
"items": [
{
"sku": "RICE",
"name": "Rice 5kg",
"quantity": 2
}
]
}
}
}
| Header | Meaning |
|---|---|
X-Webhook-Id | Delivery id (whd_…). The same on every retry, so you can ignore duplicates. |
X-Webhook-Event | The event name, e.g. order.created. |
X-Webhook-Timestamp | When this attempt was signed (Unix seconds). |
X-Webhook-Signature | t=<timestamp>,v1=<signature>; present when the webhook has a secret (all new webhooks do). |
Checking the signature
The signature is the hex HMAC-SHA256 of <timestamp>.<raw body> using the webhook's signing secret (whsec_…, shown once when the webhook or a new secret is created). Use the raw body exactly as received, compare in constant time, and reject old timestamps (for example older than 5 minutes) to stop replays.
// Node.js (Express): app.post('/hooks', express.raw({ type: 'application/json' }), handler)
const crypto = require('crypto');
function verify(secret, rawBody, header) {
const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header || '');
if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}
<?php // PHP
function verify($secret, $rawBody, $header) {
if (!preg_match('/t=(\d+),v1=([a-f0-9]{64})/', $header ?? '', $m)) return false;
if (abs(time() - (int)$m[1]) > 300) return false;
$expected = hash_hmac('sha256', $m[1] . '.' . $rawBody, $secret);
return hash_equals($expected, $m[2]);
}
# Python
import hmac, hashlib, re, time
def verify(secret, raw_body: bytes, header):
m = re.search(r't=(\d+),v1=([a-f0-9]{64})', header or '')
if not m or abs(time.time() - int(m.group(1))) > 300:
return False
expected = hmac.new(secret.encode(), m.group(1).encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, m.group(2))
Responses, retries and the delivery log
- Answer with any 2xx status within 10 seconds. Do slow work after answering.
- Network errors, timeouts,
408,429and5xxare retried after about 30 s, 2 min, 10 min, 30 min, 1 h, 2 h and so on, up to the webhook's retry count (0–10, default 3). Other statuses (e.g.404) are not retried. - When the last attempt fails, a
webhook.failedevent is raised and super admins are notified in the app. - Every attempt is kept in the delivery log for 30 days (Online store > API & Webhooks > list icon, or GET /webhook-deliveries), where a delivery can be sent again.
- Webhook URLs must use http or https and cannot point to local or private network addresses. Redirects are not followed.
- Use POST /webhooks/{id}/test or the Test button to send a
webhook.testevent.
Events
| Event | When |
|---|---|
| Orders | |
order.created | A sale or online order was placed. |
order.updated | Any change to an order (approved, paid, ready, shipped, delivered, cancelled). change says what happened. |
order.approved | A pending order was approved. |
order.ready | The kitchen marked an order ready. |
order.shipped | An order was sent for delivery. |
order.delivered | An order was delivered (fulfilled). |
order.cancelled | An order was cancelled or rejected. |
| Payments | |
payment.successful | Payment for an order was confirmed. |
refund.created | A refund was recorded. |
| Customers | |
customer.created | A customer was added (CRM, POS, online store or API). |
customer.updated | A customer record was changed. |
loyalty.earned | A customer earned loyalty points. |
loyalty.redeemed | A customer redeemed loyalty points. |
loyalty.adjusted | Loyalty points were adjusted by staff. |
loyalty.expired | Loyalty points expired. |
loyalty.tier_changed | A customer moved to another membership tier. |
| Products & stock | |
product.created | A product was created. |
product.updated | A product was changed. |
inventory.updated | Stock of a product variant changed (sale, edit or adjustment). |
inventory.low_stock | A variant dropped to or below its low-stock level. |
inventory.out_of_stock | A variant ran out of stock. |
product.expiring | A product is close to its expiry date. |
product.expired | A product has expired. |
| HR | |
employee.created | An employee was added. |
employee.updated | An employee record was changed. |
| System | |
permission.changed | A user's permissions were changed. |
email.failed | An email could not be delivered. |
sms.failed | An SMS could not be delivered. |
webhook.failed | A webhook delivery failed after all retries (sent to other webhooks). |
Older webhooks created with a single event keep working; the names order.placed, payment.confirmed and refund.requested mean order.created, payment.successful and refund.created.
Authentication
Get an access token with a username and password, or use an API key created in Online store > API & Webhooks. Send either as Authorization: Bearer <token> (API keys may also use X-API-Key).
POST /auth/token
Get an access token
Signs in with a username and password (and the 6-digit code when two-factor sign-in is on) and returns a bearer token valid for 12 hours. The token is shown only once. Five wrong passwords in a row disable the account, as on the sign-in page.
- Authentication
- None (public)
Request body (JSON)
| Name | Type | Details |
|---|---|---|
username required | string | max 100 characters |
password required | string | max 200 characters |
otp | string | Two-factor code, when enabled for the account. must be 6 digits |
name | string | Label for this token, e.g. "Warehouse scanner". max 80 characters |
Example request
curl -X POST "https://your-store.example.com/api/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{"username":"jane","password":"••••••••"}'
Example response (201 Created)
{
"success": true,
"message": "Created",
"data": {
"token": "mtk_<token shown once>",
"tokenType": "Bearer",
"expiresAt": "2026-10-02T21:30:00.000Z",
"expiresIn": 43200,
"user": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"username": "jane",
"name": "Jane Doe"
}
}
}
GET /auth/me
Current user and credential
The user the request acts as, their permissions, and the credential used (type, name, scopes, expiry).
- Permission
- Any signed-in user
- API key scope
auth:read
Example request
curl -X GET "https://your-store.example.com/api/v1/auth/me" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"user": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"username": "jane",
"name": "Jane Doe",
"email": "jane@example.com",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"isSuperAdmin": false,
"permissions": {
"pos": {
"pos": "1",
"products": "1",
"sales": "1"
},
"crm": {
"customers": "1"
}
},
"twoFactorEnabled": true
},
"credential": {
"type": "token",
"id": "66f1c2a9e4b0a1b2c3d4e517",
"name": "Warehouse scanner",
"scopes": [
"*"
],
"expiresAt": "2026-10-02T21:30:00.000Z"
}
}
}
GET /auth/tokens
List your access tokens
Tokens you created with /auth/token (not their values).
- Permission
- Any signed-in user
- API key scope
auth:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/auth/tokens" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e517",
"name": "Warehouse scanner",
"scopes": [
"*"
],
"createdAt": "2026-10-01T09:30:00.000Z",
"expiresAt": "2026-10-02T21:30:00.000Z",
"lastUsedAt": "2026-10-02T14:05:00.000Z",
"lastIp": "102.89.1.20",
"revoked": false,
"current": true
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
DELETE /auth/tokens/:id
Revoke one of your tokens
Revoked tokens stop working at once. Use the id current to revoke the token making the request (sign out).
- Permission
- Any signed-in user
- API key scope
auth:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a token id or "current" |
Example request
curl -X DELETE "https://your-store.example.com/api/v1/auth/tokens/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e517",
"revoked": true
}
}
Users
Staff accounts. Password hashes, two-factor secrets and session data are never returned. API keys need the admin scope.
GET /users
List users
- Permission
admin.adminoradmin.view- API key scope
admin:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
active | boolean | Only active (true) or disabled (false) users. |
storeId | id (24 hex characters) | Only users assigned to this store. |
Example request
curl -X GET "https://your-store.example.com/api/v1/users" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"username": "jane",
"name": "Jane Doe",
"email": "jane@example.com",
"mobile": "08012345678",
"address": "",
"active": true,
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"isSuperAdmin": false,
"lastLoginAt": "2026-10-02T14:05:00.000Z",
"passwordChangedAt": "2026-10-01T09:30:00.000Z",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /users/:id
Get a user (with permissions)
- Permission
admin.adminoradmin.view- API key scope
admin:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/users/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"username": "jane",
"name": "Jane Doe",
"email": "jane@example.com",
"mobile": "08012345678",
"address": "",
"active": true,
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"isSuperAdmin": false,
"lastLoginAt": "2026-10-02T14:05:00.000Z",
"passwordChangedAt": "2026-10-01T09:30:00.000Z",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"permissions": {
"pos": {
"pos": "1",
"products": "1",
"sales": "1"
},
"crm": {
"customers": "1"
}
}
}
}
POST /users
Create a user
New users start with no permissions. They are created disabled unless active is true and you may approve users (admin.switch), as on the Admin page.
- Permission
admin.add- API key scope
admin:write
Request body (JSON)
| Name | Type | Details |
|---|---|---|
username required | string | 3–50 characters; may contain letters, numbers, dot, dash and underscore |
name required | string | max 100 characters |
email required | max 200 characters | |
mobile required | string | must be 7-15 digits |
address | string | max 300 characters |
password required | string | At least 8 characters with upper and lower case letters, a number and a symbol. max 128 characters |
storeId required | id (24 hex characters) | |
active | boolean | default false |
Example request
curl -X POST "https://your-store.example.com/api/v1/users" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"username":"username","name":"name","email":"jane@example.com","mobile":"mobile","password":"password","storeId":"66f1c2a9e4b0a1b2c3d4e5f6"}'
Example response (201 Created)
{
"success": true,
"message": "Created",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"username": "jane",
"name": "Jane Doe",
"email": "jane@example.com",
"mobile": "08012345678",
"address": "",
"active": true,
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"isSuperAdmin": false,
"lastLoginAt": "2026-10-02T14:05:00.000Z",
"passwordChangedAt": "2026-10-01T09:30:00.000Z",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"permissions": {
"pos": {
"pos": "1",
"products": "1",
"sales": "1"
},
"crm": {
"customers": "1"
}
}
}
}
PATCH /users/:id
Update a user
Send only the fields to change. Changing active needs admin.switch; you cannot disable your own account.
- Permission
admin.edit- API key scope
admin:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name | string | 1–100 characters |
email | max 200 characters | |
mobile | string | must be 7-15 digits |
address | string | max 300 characters |
storeId | id (24 hex characters) | |
active | boolean |
Example request
curl -X PATCH "https://your-store.example.com/api/v1/users/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"name","email":"jane@example.com"}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"username": "jane",
"name": "Jane Doe",
"email": "jane@example.com",
"mobile": "08012345678",
"address": "",
"active": true,
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"isSuperAdmin": false,
"lastLoginAt": "2026-10-02T14:05:00.000Z",
"passwordChangedAt": "2026-10-01T09:30:00.000Z",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"permissions": {
"pos": {
"pos": "1",
"products": "1",
"sales": "1"
},
"crm": {
"customers": "1"
}
}
}
}
PUT /users/:id/permissions
Replace a user's permissions
Send the complete set, e.g. { "permissions": { "pos": { "pos": true, "products": true }, "crm": { "customers": true } } }. Menus and keys are listed by GET /admin/permissions. You cannot change your own permissions.
- Permission
admin.permission- API key scope
admin:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
permissions required | object |
Example request
curl -X PUT "https://your-store.example.com/api/v1/users/66f1c2a9e4b0a1b2c3d4e5f6/permissions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"permissions":{}}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"username": "jane",
"name": "Jane Doe",
"email": "jane@example.com",
"mobile": "08012345678",
"address": "",
"active": true,
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"isSuperAdmin": false,
"lastLoginAt": "2026-10-02T14:05:00.000Z",
"passwordChangedAt": "2026-10-01T09:30:00.000Z",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"permissions": {
"pos": {
"pos": "1",
"products": "1",
"sales": "1"
},
"crm": {
"customers": "1"
}
}
}
}
Stores
Stores (branches). Without the pos.stores permission you only see the store your account is assigned to. API keys need the pos scope.
GET /stores
List stores
- Permission
- Any signed-in user
- API key scope
pos:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
status | string | max 30 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/stores" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e501",
"name": "Main Street",
"type": "retail",
"status": "active",
"address": "12 Market Road",
"city": "Lagos",
"state": "Lagos",
"zip": "",
"phone": "08012345678",
"email": "main@example.com",
"manager": "Jane Doe",
"timezone": "Africa/Lagos",
"currencySymbol": "NGN",
"vatRate": 7.5,
"stockControl": true,
"paymentBeforeOrder": true,
"onlineOrders": true,
"shipping": false,
"confirmationEmails": true,
"businessHours": null,
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /stores/:id
Get a store
- Permission
- Any signed-in user
- API key scope
pos:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/stores/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e501",
"name": "Main Street",
"type": "retail",
"status": "active",
"address": "12 Market Road",
"city": "Lagos",
"state": "Lagos",
"zip": "",
"phone": "08012345678",
"email": "main@example.com",
"manager": "Jane Doe",
"timezone": "Africa/Lagos",
"currencySymbol": "NGN",
"vatRate": 7.5,
"stockControl": true,
"paymentBeforeOrder": true,
"onlineOrders": true,
"shipping": false,
"confirmationEmails": true,
"businessHours": null,
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
Products & inventory
Products, variants, prices and stock. Reading needs pos.products or pos.pos; changes need pos.products. Cost prices are only shown with pos.products. API keys need the pos scope.
GET /products
List products
- Permission
pos.productsorpos.pos- API key scope
pos:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
store | string | "all" or a store id (needs pos.stores). Default: your store. max 30 characters; must be "all", "current" or a store id |
category | string | max 100 characters |
brand | string | max 100 characters |
status | one of: active, inactive, discontinued, draft | |
sku | string | Exact product or variant SKU. max 60 characters |
barcode | string | max 60 characters |
stock | one of: out, low, in | Products with at least one variant at this stock level. |
expiry | one of: expired, expiring, none | "expiring" = within the configured window. |
Example request
curl -X GET "https://your-store.example.com/api/v1/products" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"sku": "RICE5",
"barcode": "6151234567890",
"description": "Long-grain parboiled rice.",
"category": "Food",
"subcategory": "Grains",
"kitchenCategory": "",
"brand": "Golden Penny",
"status": "active",
"tags": [
"staple"
],
"images": [],
"weight": 5,
"expiryDate": "2027-06-30",
"expiryStatus": "valid",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"totalQuantity": 42,
"variants": [
{
"id": "66f1c2a9e4b0a1b2c3d4e504",
"variantId": "v_1a2b3c4d5e6f",
"name": "Rice 5kg",
"sku": "RICE5",
"price": 6500,
"compareAtPrice": 7000,
"currency": "NGN",
"quantity": 42,
"threshold": 5,
"stockLevel": "in",
"location": "Aisle 3",
"isActive": true,
"attributes": {
"size": "5kg"
},
"cost": 5200
}
],
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /products/:id
Get a product
- Permission
pos.productsorpos.pos- API key scope
pos:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/products/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"sku": "RICE5",
"barcode": "6151234567890",
"description": "Long-grain parboiled rice.",
"category": "Food",
"subcategory": "Grains",
"kitchenCategory": "",
"brand": "Golden Penny",
"status": "active",
"tags": [
"staple"
],
"images": [],
"weight": 5,
"expiryDate": "2027-06-30",
"expiryStatus": "valid",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"totalQuantity": 42,
"variants": [
{
"id": "66f1c2a9e4b0a1b2c3d4e504",
"variantId": "v_1a2b3c4d5e6f",
"name": "Rice 5kg",
"sku": "RICE5",
"price": 6500,
"compareAtPrice": 7000,
"currency": "NGN",
"quantity": 42,
"threshold": 5,
"stockLevel": "in",
"location": "Aisle 3",
"isActive": true,
"attributes": {
"size": "5kg"
},
"cost": 5200
}
],
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
POST /products
Create a product
Creates the product in your store (or storeId, with pos.stores). Images are added in the app.
- Permission
pos.products- API key scope
pos:write
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name required | string | max 200 characters |
sku required | string | max 60 characters; may contain letters, numbers, dot, dash and underscore |
barcode | string | max 60 characters |
description | string | max 5000 characters |
category required | string | max 100 characters |
subcategory | string | max 100 characters |
kitchenCategory | string | max 100 characters |
brand | string | max 100 characters |
status | one of: active, inactive, discontinued, draft | default "active" |
tags | array of string | max 30 items |
weight | number | min 0 |
expiryDate | string | YYYY-MM-DD; empty string clears it. max 10 characters; must be YYYY-MM-DD, or empty to clear |
currency | string | Defaults to the store's currency. max 10 characters |
storeId | id (24 hex characters) | |
variants required | array of object | 1–50 items |
variants[].name | string | max 100 characters |
variants[].sku | string | max 60 characters |
variants[].price required | number | min 0 |
variants[].compareAtPrice | number | min 0 |
variants[].cost | number | min 0 |
variants[].quantity | integer | min 0; default 0 |
variants[].threshold | integer | min 0 |
variants[].location | string | max 100 characters |
variants[].attributes | object | e.g. { "size": "M", "color": "red" } |
Example request
curl -X POST "https://your-store.example.com/api/v1/products" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"name","sku":"sku","category":"category","variants":[{"price":10.5}]}'
Example response (201 Created)
{
"success": true,
"message": "Created",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"sku": "RICE5",
"barcode": "6151234567890",
"description": "Long-grain parboiled rice.",
"category": "Food",
"subcategory": "Grains",
"kitchenCategory": "",
"brand": "Golden Penny",
"status": "active",
"tags": [
"staple"
],
"images": [],
"weight": 5,
"expiryDate": "2027-06-30",
"expiryStatus": "valid",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"totalQuantity": 42,
"variants": [
{
"id": "66f1c2a9e4b0a1b2c3d4e504",
"variantId": "v_1a2b3c4d5e6f",
"name": "Rice 5kg",
"sku": "RICE5",
"price": 6500,
"compareAtPrice": 7000,
"currency": "NGN",
"quantity": 42,
"threshold": 5,
"stockLevel": "in",
"location": "Aisle 3",
"isActive": true,
"attributes": {
"size": "5kg"
},
"cost": 5200
}
],
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
PATCH /products/:id
Update product details
Send only the fields to change. Prices and stock are changed per variant (see below).
- Permission
pos.products- API key scope
pos:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name | string | 1–200 characters |
barcode | string | max 60 characters |
description | string | max 5000 characters |
category | string | 1–100 characters |
subcategory | string | max 100 characters |
kitchenCategory | string | max 100 characters |
brand | string | max 100 characters |
status | one of: active, inactive, discontinued, draft | |
tags | array of string | max 30 items |
weight | number | min 0 |
expiryDate | string | YYYY-MM-DD; empty string clears it. max 10 characters; must be YYYY-MM-DD, or empty to clear |
Example request
curl -X PATCH "https://your-store.example.com/api/v1/products/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"name","barcode":"barcode"}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"sku": "RICE5",
"barcode": "6151234567890",
"description": "Long-grain parboiled rice.",
"category": "Food",
"subcategory": "Grains",
"kitchenCategory": "",
"brand": "Golden Penny",
"status": "active",
"tags": [
"staple"
],
"images": [],
"weight": 5,
"expiryDate": "2027-06-30",
"expiryStatus": "valid",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"totalQuantity": 42,
"variants": [
{
"id": "66f1c2a9e4b0a1b2c3d4e504",
"variantId": "v_1a2b3c4d5e6f",
"name": "Rice 5kg",
"sku": "RICE5",
"price": 6500,
"compareAtPrice": 7000,
"currency": "NGN",
"quantity": 42,
"threshold": 5,
"stockLevel": "in",
"location": "Aisle 3",
"isActive": true,
"attributes": {
"size": "5kg"
},
"cost": 5200
}
],
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
PATCH /products/:id/variants/:variantId
Update a variant (price, threshold…)
variantId may be the variant id, its variantId or its SKU. Use the stock endpoint to change quantities.
- Permission
pos.products- API key scope
pos:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) | |
variantId required | string | max 80 characters |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name | string | 1–100 characters |
price | number | min 0 |
compareAtPrice | number | min 0 |
cost | number | min 0 |
threshold | integer | min 0 |
location | string | max 100 characters |
isActive | boolean |
Example request
curl -X PATCH "https://your-store.example.com/api/v1/products/66f1c2a9e4b0a1b2c3d4e5f6/variants/variantId" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"name","price":10.5}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"sku": "RICE5",
"barcode": "6151234567890",
"description": "Long-grain parboiled rice.",
"category": "Food",
"subcategory": "Grains",
"kitchenCategory": "",
"brand": "Golden Penny",
"status": "active",
"tags": [
"staple"
],
"images": [],
"weight": 5,
"expiryDate": "2027-06-30",
"expiryStatus": "valid",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"totalQuantity": 42,
"variants": [
{
"id": "66f1c2a9e4b0a1b2c3d4e504",
"variantId": "v_1a2b3c4d5e6f",
"name": "Rice 5kg",
"sku": "RICE5",
"price": 6500,
"compareAtPrice": 7000,
"currency": "NGN",
"quantity": 42,
"threshold": 5,
"stockLevel": "in",
"location": "Aisle 3",
"isActive": true,
"attributes": {
"size": "5kg"
},
"cost": 5200
}
],
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
POST /products/:id/stock
Adjust stock
Either adjustment (e.g. 10 received, -2 damaged) or quantity (stock count). Stock never goes below zero; an adjustment that would is refused with 409. Low and out-of-stock alerts are raised as in the app.
- Permission
pos.products- API key scope
pos:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
variantId | string | Required when the product has several variants. max 80 characters |
adjustment | integer | -1000000–1000000 |
quantity | integer | 0–100000000 |
reason required | string | max 200 characters |
Example request
curl -X POST "https://your-store.example.com/api/v1/products/66f1c2a9e4b0a1b2c3d4e5f6/stock" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason":"Stock count"}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"variantId": "66f1c2a9e4b0a1b2c3d4e504",
"before": 42,
"after": 52,
"stockLevel": "in"
}
}
GET /inventory/summary
Inventory alerts summary
Counts of expired, expiring, out-of-stock and low-stock items (as on the inventory dashboard).
- Permission
pos.productsorpos.pos- API key scope
pos:read
Query parameters
| Name | Type | Details |
|---|---|---|
store | string | "all" or a store id (needs pos.stores). Default: your store. max 30 characters; must be "all", "current" or a store id |
days | integer | Expiring window in days. 1–365 |
Example request
curl -X GET "https://your-store.example.com/api/v1/inventory/summary" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"days": 30,
"expired": 1,
"expiring": 3,
"out": 2,
"low": 5,
"stores": [
"66f1c2a9e4b0a1b2c3d4e501"
]
}
}
GET /inventory/report
Inventory alert list
One row per affected product (expiry) or variant (stock).
- Permission
pos.productsorpos.pos- API key scope
pos:read
Query parameters
| Name | Type | Details |
|---|---|---|
type required | one of: expired, expiring, out, low | |
days | integer | 1–365 |
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
q | string | Search text. max 100 characters |
store | string | "all" or a store id (needs pos.stores). Default: your store. max 30 characters; must be "all", "current" or a store id |
Example request
curl -X GET "https://your-store.example.com/api/v1/inventory/report?type=expired" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"sku": "RICE5",
"category": "Food",
"variant": "Rice 5kg",
"variantSku": "RICE5",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"status": "low",
"quantity": 4,
"threshold": 5,
"location": "Aisle 3",
"expiryDate": "2027-06-30T00:00:00.000Z",
"daysLeft": 271,
"type": "low"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false,
"type": "low",
"days": 30
}
}
Orders & refunds
Sales orders and refunds. Reading needs pos.sales or pos.pos; selling needs pos.pos. Orders are created in your store with catalogue prices. API keys need the pos scope.
GET /orders
List orders
- Permission
pos.salesorpos.pos- API key scope
pos:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: pending, confirmed, processing, shipped, delivered, cancelled, refunded, on_hold | |
paymentStatus | one of: pending, authorized, paid, partially_refunded, refunded, failed, cancelled | |
customerId | id (24 hex characters) | |
orderNumber | string | max 60 characters |
source | one of: pos, web, mobile, api, other | |
store | string | "all" or a store id (needs pos.stores). Default: your store. max 30 characters; must be "all", "current" or a store id |
Example request
curl -X GET "https://your-store.example.com/api/v1/orders" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"variantId": "v_1a2b3c4d5e6f",
"sku": "RICE5",
"name": "Rice 5kg",
"quantity": 2,
"unitPrice": {
"amount": 6500,
"currency": "NGN"
},
"total": {
"amount": 13000,
"currency": "NGN"
}
}
],
"subtotal": {
"amount": 13000,
"currency": "NGN"
},
"discount": null,
"tax": {
"amount": 975,
"rate": 7.5
},
"shipping": null,
"total": {
"amount": 13975,
"currency": "NGN"
},
"payment": {
"method": "cash",
"status": "paid",
"paidAt": "2026-10-02T14:05:00.000Z"
},
"fulfillmentStatus": "unfulfilled",
"refundStatus": null,
"staff": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"note": "",
"statusHistory": [
{
"status": "confirmed",
"at": "2026-10-02T14:05:00.000Z",
"by": "Jane Doe",
"note": null
}
],
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /orders/:id
Get an order
- Permission
pos.salesorpos.pos- API key scope
pos:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/orders/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"variantId": "v_1a2b3c4d5e6f",
"sku": "RICE5",
"name": "Rice 5kg",
"quantity": 2,
"unitPrice": {
"amount": 6500,
"currency": "NGN"
},
"total": {
"amount": 13000,
"currency": "NGN"
}
}
],
"subtotal": {
"amount": 13000,
"currency": "NGN"
},
"discount": null,
"tax": {
"amount": 975,
"rate": 7.5
},
"shipping": null,
"total": {
"amount": 13975,
"currency": "NGN"
},
"payment": {
"method": "cash",
"status": "paid",
"paidAt": "2026-10-02T14:05:00.000Z"
},
"fulfillmentStatus": "unfulfilled",
"refundStatus": null,
"staff": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"note": "",
"statusHistory": [
{
"status": "confirmed",
"at": "2026-10-02T14:05:00.000Z",
"by": "Jane Doe",
"note": null
}
],
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
POST /orders
Create an order (sale)
Sells products from your store. Prices come from the catalogue and tax from the store VAT rate; coupons, automatic discounts and loyalty points are applied as on the POS screen. When the store takes payment before the order, the order is recorded as paid with payment.method.
- Permission
pos.pos- API key scope
pos:write
Request body (JSON)
| Name | Type | Details |
|---|---|---|
items required | array of object | 1–200 items |
items[].productId required | id (24 hex characters) | |
items[].variantId | string | Needed when the product has several variants (id, variantId or SKU). max 80 characters |
items[].quantity required | integer | 1–100000 |
customerId | id (24 hex characters) | CRM customer (for loyalty points and receipts). |
payment | object | |
payment.method | one of: cash, credit_card, debit_card, digital_wallet, bank_transfer, check, other | default "cash" |
couponCode | string | max 50 characters |
loyaltyRedeemPoints | integer | Points to redeem (needs customerId). min 0 |
Example request
curl -X POST "https://your-store.example.com/api/v1/orders" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"items":[{"productId":"66f1c2a9e4b0a1b2c3d4e5f6","quantity":1}]}'
Example response (201 Created)
{
"success": true,
"message": "Created",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"variantId": "v_1a2b3c4d5e6f",
"sku": "RICE5",
"name": "Rice 5kg",
"quantity": 2,
"unitPrice": {
"amount": 6500,
"currency": "NGN"
},
"total": {
"amount": 13000,
"currency": "NGN"
}
}
],
"subtotal": {
"amount": 13000,
"currency": "NGN"
},
"discount": null,
"tax": {
"amount": 975,
"rate": 7.5
},
"shipping": null,
"total": {
"amount": 13975,
"currency": "NGN"
},
"payment": {
"method": "cash",
"status": "paid",
"paidAt": "2026-10-02T14:05:00.000Z"
},
"fulfillmentStatus": "unfulfilled",
"refundStatus": null,
"staff": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"note": "",
"statusHistory": [
{
"status": "confirmed",
"at": "2026-10-02T14:05:00.000Z",
"by": "Jane Doe",
"note": null
}
],
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"loyalty": {
"redeemedPoints": 0,
"redeemedValue": 0,
"earnedPoints": 139,
"balance": 459
}
}
}
POST /orders/:id/cancel
Cancel an order
Same rules as the POS screen: orders being prepared, fulfilled or already refunded cannot be cancelled. Paid orders are refunded and loyalty points reversed.
- Permission
pos.pos- API key scope
pos:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
reason | string | max 300 characters |
Example request
curl -X POST "https://your-store.example.com/api/v1/orders/66f1c2a9e4b0a1b2c3d4e5f6/cancel" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason":"reason"}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "cancelled",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"variantId": "v_1a2b3c4d5e6f",
"sku": "RICE5",
"name": "Rice 5kg",
"quantity": 2,
"unitPrice": {
"amount": 6500,
"currency": "NGN"
},
"total": {
"amount": 13000,
"currency": "NGN"
}
}
],
"subtotal": {
"amount": 13000,
"currency": "NGN"
},
"discount": null,
"tax": {
"amount": 975,
"rate": 7.5
},
"shipping": null,
"total": {
"amount": 13975,
"currency": "NGN"
},
"payment": {
"method": "cash",
"status": "paid",
"paidAt": "2026-10-02T14:05:00.000Z"
},
"fulfillmentStatus": "unfulfilled",
"refundStatus": null,
"staff": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"note": "",
"statusHistory": [
{
"status": "confirmed",
"at": "2026-10-02T14:05:00.000Z",
"by": "Jane Doe",
"note": null
},
{
"status": "cancelled",
"at": "2026-10-02T14:05:00.000Z",
"by": "Jane Doe",
"note": "Customer changed their mind"
}
],
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
POST /orders/:id/payments
Record a payment
- Permission
pos.pos- API key scope
pos:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
amount required | number | min 0.01 |
method required | one of: cash, credit_card, debit_card, digital_wallet, bank_transfer, check, other |
Example request
curl -X POST "https://your-store.example.com/api/v1/orders/66f1c2a9e4b0a1b2c3d4e5f6/payments" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"amount":0.01,"method":"cash"}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"variantId": "v_1a2b3c4d5e6f",
"sku": "RICE5",
"name": "Rice 5kg",
"quantity": 2,
"unitPrice": {
"amount": 6500,
"currency": "NGN"
},
"total": {
"amount": 13000,
"currency": "NGN"
}
}
],
"subtotal": {
"amount": 13000,
"currency": "NGN"
},
"discount": null,
"tax": {
"amount": 975,
"rate": 7.5
},
"shipping": null,
"total": {
"amount": 13975,
"currency": "NGN"
},
"payment": {
"method": "cash",
"status": "paid",
"paidAt": "2026-10-02T14:05:00.000Z"
},
"fulfillmentStatus": "unfulfilled",
"refundStatus": null,
"staff": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"note": "",
"statusHistory": [
{
"status": "confirmed",
"at": "2026-10-02T14:05:00.000Z",
"by": "Jane Doe",
"note": null
}
],
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
POST /orders/:id/fulfill
Mark an order fulfilled
- Permission
pos.shippingorpos.pos- API key scope
pos:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X POST "https://your-store.example.com/api/v1/orders/66f1c2a9e4b0a1b2c3d4e5f6/fulfill" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "completed",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"storeName": "Main Street",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"variantId": "v_1a2b3c4d5e6f",
"sku": "RICE5",
"name": "Rice 5kg",
"quantity": 2,
"unitPrice": {
"amount": 6500,
"currency": "NGN"
},
"total": {
"amount": 13000,
"currency": "NGN"
}
}
],
"subtotal": {
"amount": 13000,
"currency": "NGN"
},
"discount": null,
"tax": {
"amount": 975,
"rate": 7.5
},
"shipping": null,
"total": {
"amount": 13975,
"currency": "NGN"
},
"payment": {
"method": "cash",
"status": "paid",
"paidAt": "2026-10-02T14:05:00.000Z"
},
"fulfillmentStatus": "fulfilled",
"refundStatus": null,
"staff": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"note": "",
"statusHistory": [
{
"status": "confirmed",
"at": "2026-10-02T14:05:00.000Z",
"by": "Jane Doe",
"note": null
}
],
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
GET /refunds
List refunds
- Permission
pos.refundorpos.sales- API key scope
pos:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
orderId | id (24 hex characters) | |
status | string | max 30 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/refunds" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e507",
"refundNumber": "REF-1002",
"orderId": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"status": "completed",
"method": "original",
"reason": "damaged",
"amount": {
"amount": 6500,
"currency": "NGN"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"quantity": 1
}
],
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi"
},
"processedAt": "2026-10-02T14:05:00.000Z",
"createdAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /refunds/:id
Get a refund
- Permission
pos.refundorpos.sales- API key scope
pos:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/refunds/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e507",
"refundNumber": "REF-1002",
"orderId": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"status": "completed",
"method": "original",
"reason": "damaged",
"amount": {
"amount": 6500,
"currency": "NGN"
},
"items": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"quantity": 1
}
],
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi"
},
"processedAt": "2026-10-02T14:05:00.000Z",
"createdAt": "2026-10-02T14:05:00.000Z"
}
}
Customers
CRM customers, with loyalty balances. Reading needs crm.customers (or pos.pos, for looking up customers at the till); changes need crm.addcustomer. API keys need the crm scope.
GET /customers
List customers
- Permission
crm.customersorcrm.addcustomerorcrm.supportorpos.pos- API key scope
crm:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
email | ||
phone | string | max 30 characters |
membershipTier | one of: Bronze, Silver, Gold | |
active | boolean |
Example request
curl -X GET "https://your-store.example.com/api/v1/customers" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e506",
"customerCode": "C-1001",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432",
"address": "4 Allen Avenue, Ikeja",
"taxId": "",
"membershipTier": "Silver",
"loyaltyPoints": 320,
"loyaltyLifetimePoints": 1450,
"balance": 0,
"minimumOrder": 0,
"active": true,
"reps": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
}
],
"createdBy": "Jane Doe",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /customers/:id
Get a customer
- Permission
crm.customersorcrm.addcustomerorcrm.supportorpos.pos- API key scope
crm:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/customers/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"customerCode": "C-1001",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432",
"address": "4 Allen Avenue, Ikeja",
"taxId": "",
"membershipTier": "Silver",
"loyaltyPoints": 320,
"loyaltyLifetimePoints": 1450,
"balance": 0,
"minimumOrder": 0,
"active": true,
"reps": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
}
],
"createdBy": "Jane Doe",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
POST /customers
Create a customer
Email, phone and customer code must be unique. A welcome email is sent when that setting is on.
- Permission
crm.addcustomer- API key scope
crm:write
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name required | string | max 150 characters |
email | max 200 characters | |
phone required | string | max 30 characters; must be a phone number |
customerCode | string | Your own customer number. Generated when omitted. max 50 characters |
address | string | max 300 characters |
taxId | string | max 50 characters |
membershipTier | one of: Bronze, Silver, Gold | default "Bronze" |
minimumOrder | number | min 0 |
active | boolean |
Example request
curl -X POST "https://your-store.example.com/api/v1/customers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"name","phone":"phone"}'
Example response (201 Created)
{
"success": true,
"message": "Created",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"customerCode": "C-1001",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432",
"address": "4 Allen Avenue, Ikeja",
"taxId": "",
"membershipTier": "Silver",
"loyaltyPoints": 320,
"loyaltyLifetimePoints": 1450,
"balance": 0,
"minimumOrder": 0,
"active": true,
"reps": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
}
],
"createdBy": "Jane Doe",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
PATCH /customers/:id
Update a customer
Send only the fields to change.
- Permission
crm.addcustomer- API key scope
crm:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name | string | max 150 characters |
email | max 200 characters | |
phone | string | max 30 characters; must be a phone number |
customerCode | string | Your own customer number. Generated when omitted. max 50 characters |
address | string | max 300 characters |
taxId | string | max 50 characters |
membershipTier | one of: Bronze, Silver, Gold | |
minimumOrder | number | min 0 |
active | boolean |
Example request
curl -X PATCH "https://your-store.example.com/api/v1/customers/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"name","email":"jane@example.com"}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"customerCode": "C-1001",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "08098765432",
"address": "4 Allen Avenue, Ikeja",
"taxId": "",
"membershipTier": "Silver",
"loyaltyPoints": 320,
"loyaltyLifetimePoints": 1450,
"balance": 0,
"minimumOrder": 0,
"active": true,
"reps": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
}
],
"createdBy": "Jane Doe",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
GET /customers/:id/loyalty
Loyalty balance and history
- Permission
crm.loyaltyorcrm.customersorpos.pos- API key scope
crm:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
type | one of: earn, redeem, reverse, restore, adjust, expire |
Example request
curl -X GET "https://your-store.example.com/api/v1/customers/66f1c2a9e4b0a1b2c3d4e5f6/loyalty" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"summary": {
"customerId": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"enabled": true,
"balance": 459,
"lifetime": 1589,
"value": 45.9,
"tier": "Silver",
"tierName": "Silver",
"nextTier": {
"key": "gold",
"name": "Gold",
"pointsNeeded": 3411
},
"redemption": {
"points": 100,
"value": 10
},
"redeemablePoints": 400,
"pointsPerAmount": 1,
"expiryMonths": 12
},
"history": [
{
"id": "66f1c2a9e4b0a1b2c3d4e508",
"type": "earn",
"points": 139,
"balanceAfter": 459,
"orderId": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"amount": 13975,
"description": "Earned on order ORD1790904240356987",
"source": "pos",
"by": "Jane Doe",
"createdAt": "2026-10-02T14:05:00.000Z",
"expiresAt": null
}
]
},
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
POST /customers/:id/loyalty/adjustments
Adjust loyalty points
Adds (positive) or removes (negative) points with a reason; recorded in the loyalty ledger. A balance cannot go below zero (409).
- Permission
crm.loyaltyadjust- API key scope
crm:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
points required | integer | -1000000–1000000 |
reason required | string | 3–200 characters |
Example request
curl -X POST "https://your-store.example.com/api/v1/customers/66f1c2a9e4b0a1b2c3d4e5f6/loyalty/adjustments" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"points":1,"reason":"reason"}'
Example response (201 Created)
{
"success": true,
"message": "Created",
"data": {
"summary": {
"customerId": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"enabled": true,
"balance": 459,
"lifetime": 1589,
"value": 45.9,
"tier": "Silver",
"tierName": "Silver",
"nextTier": {
"key": "gold",
"name": "Gold",
"pointsNeeded": 3411
},
"redemption": {
"points": 100,
"value": 10
},
"redeemablePoints": 400,
"pointsPerAmount": 1,
"expiryMonths": 12
},
"entry": {
"id": "66f1c2a9e4b0a1b2c3d4e508",
"type": "adjust",
"points": 50,
"balanceAfter": 509,
"orderId": null,
"orderNumber": null,
"amount": 0,
"description": "Goodwill for late delivery",
"source": "api",
"by": "Jane Doe",
"createdAt": "2026-10-02T14:05:00.000Z",
"expiresAt": null
}
}
}
CRM
Leads (crm.leads), support tickets (crm.view), the loyalty report (crm.loyalty) and a customer timeline. API keys need the crm scope.
GET /crm/leads
List leads
- Permission
crm.leads- API key scope
crm:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: Closed, Not Contacted, Contacted, Lost, Open | |
priority | one of: Low, Medium, High, Urgent |
Example request
curl -X GET "https://your-store.example.com/api/v1/crm/leads" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e509",
"name": "Bola Ade",
"company": "Ade Foods Ltd",
"email": "bola@adefoods.example",
"phone": "08031112222",
"status": "Contacted",
"priority": "High",
"source": "website",
"type": "wholesale",
"industry": "Retail",
"country": "Nigeria",
"state": "Lagos",
"expectedIncome": 2500000,
"currency": "NGN",
"probability": 60,
"owner": "Jane Doe",
"dueDate": "2026-10-15T00:00:00.000Z",
"lastContactedAt": "2026-10-01T09:30:00.000Z",
"nextFollowUpAt": "2026-10-05T10:00:00.000Z",
"closedAt": null,
"tags": [
"bulk"
],
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /crm/leads/:id
Get a lead (with recent activity)
- Permission
crm.leads- API key scope
crm:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/crm/leads/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e509",
"name": "Bola Ade",
"company": "Ade Foods Ltd",
"email": "bola@adefoods.example",
"phone": "08031112222",
"status": "Contacted",
"priority": "High",
"source": "website",
"type": "wholesale",
"industry": "Retail",
"country": "Nigeria",
"state": "Lagos",
"expectedIncome": 2500000,
"currency": "NGN",
"probability": 60,
"owner": "Jane Doe",
"dueDate": "2026-10-15T00:00:00.000Z",
"lastContactedAt": "2026-10-01T09:30:00.000Z",
"nextFollowUpAt": "2026-10-05T10:00:00.000Z",
"closedAt": null,
"tags": [
"bulk"
],
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"description": "Wants monthly supply of rice and oil.",
"website": "https://adefoods.example",
"activities": [
{
"type": "call",
"text": "Discussed pricing",
"by": "Jane Doe",
"at": "2026-10-01T09:30:00.000Z"
}
]
}
}
GET /crm/tickets
List support tickets
- Permission
crm.vieworcrm.support- API key scope
crm:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: open, answered, closed | |
customerId | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/crm/tickets" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e510",
"ticketNumber": "TCK-2041",
"title": "Wrong item delivered",
"category": "Delivery",
"status": "answered",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com"
},
"assignedTo": "Jane Doe",
"tag": "urgent",
"message": "I received beans instead of rice.",
"createdBy": "Jane Doe",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /crm/tickets/:id
Get a support ticket
- Permission
crm.vieworcrm.support- API key scope
crm:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/crm/tickets/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e510",
"ticketNumber": "TCK-2041",
"title": "Wrong item delivered",
"category": "Delivery",
"status": "answered",
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"email": "ada@example.com"
},
"assignedTo": "Jane Doe",
"tag": "urgent",
"message": "I received beans instead of rice.",
"createdBy": "Jane Doe",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
GET /crm/loyalty/report
Loyalty programme report
Points issued, redeemed and outstanding, top earners and customers per tier for a period.
- Permission
crm.loyalty- API key scope
crm:read
Query parameters
| Name | Type | Details |
|---|---|---|
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
Example request
curl -X GET "https://your-store.example.com/api/v1/crm/loyalty/report" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"period": {
"from": "2026-09-01T00:00:00.000Z",
"to": "2026-09-30T23:59:59.999Z"
},
"enabled": true,
"totals": {
"earn": {
"points": 18450,
"count": 212,
"amount": 1845000
},
"redeem": {
"points": -4200,
"count": 31,
"amount": 420
},
"reverse": {
"points": -300,
"count": 2,
"amount": 30000
},
"restore": {
"points": 100,
"count": 1,
"amount": 10
},
"adjust": {
"points": 250,
"count": 3,
"amount": 0
},
"expire": {
"points": -120,
"count": 4,
"amount": 0
}
},
"pointsIssued": 18700,
"pointsRedeemed": 4200,
"redeemedValue": 420,
"outstandingPoints": 52310,
"outstandingCustomers": 418,
"outstandingValue": 5231,
"topEarners": [
{
"customerId": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi",
"points": 1390,
"orders": 9
}
],
"tiers": [
{
"tier": "Bronze",
"customers": 301
},
{
"tier": "Silver",
"customers": 96
},
{
"tier": "Gold",
"customers": 21
}
]
}
}
GET /crm/customers/:id/activity
Customer timeline
Latest orders, loyalty entries and support tickets for one customer, newest first.
- Permission
crm.customersorcrm.supportorcrm.loyalty- API key scope
crm:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
limit | integer | 1–100; default 20 |
Example request
curl -X GET "https://your-store.example.com/api/v1/crm/customers/66f1c2a9e4b0a1b2c3d4e5f6/activity" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"customer": {
"id": "66f1c2a9e4b0a1b2c3d4e506",
"name": "Ada Obi"
},
"events": [
{
"type": "loyalty",
"at": "2026-10-02T14:05:00.000Z",
"id": "66f1c2a9e4b0a1b2c3d4e508",
"title": "Earned 139 points",
"detail": "Earned on order ORD1790904240356987",
"balanceAfter": 459
},
{
"type": "order",
"at": "2026-10-02T14:05:00.000Z",
"id": "66f1c2a9e4b0a1b2c3d4e505",
"title": "Order ORD1790904240356987",
"detail": "confirmed, paid by cash",
"amount": 13975,
"store": "Main Street"
}
]
}
}
Human resources
Employees (hr.employees), attendance (hr.attendance), leave (hr.leaves) and payroll (hr.payroll). Read only. API keys need the hr scope.
GET /hr/employees
List employees
- Permission
hr.employees- API key scope
hr:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
department | string | max 100 characters |
designation | string | max 100 characters |
active | boolean |
Example request
curl -X GET "https://your-store.example.com/api/v1/hr/employees" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e511",
"employeeNumber": "E-014",
"name": "Emma Obi",
"email": "emma@example.com",
"mobile": "08055556666",
"department": "Sales",
"designation": "Cashier",
"role": "Staff",
"unit": "Front desk",
"location": "Main Street",
"employmentType": "Full time",
"gender": "Female",
"reportingTo": "Jane Doe",
"active": true,
"joinedOn": "2025-03-01",
"probationEndsOn": "2025-06-01",
"contractEndsOn": null,
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /hr/employees/:id
Get an employee
Includes salary, bank and pension details only when you have hr.payroll.
- Permission
hr.employees- API key scope
hr:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/hr/employees/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e511",
"employeeNumber": "E-014",
"name": "Emma Obi",
"email": "emma@example.com",
"mobile": "08055556666",
"department": "Sales",
"designation": "Cashier",
"role": "Staff",
"unit": "Front desk",
"location": "Main Street",
"employmentType": "Full time",
"gender": "Female",
"reportingTo": "Jane Doe",
"active": true,
"joinedOn": "2025-03-01",
"probationEndsOn": "2025-06-01",
"contractEndsOn": null,
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"address": "7 Broad Street",
"country": "Nigeria",
"state": "Lagos",
"language": "English",
"salutation": "Ms",
"maritalStatus": "Single",
"skills": "Customer service",
"note": "",
"salary": {
"level": 3,
"gross": 250000,
"basic": 180000,
"allowance": 50000,
"other": 20000,
"cycle": "monthly"
},
"bank": {
"name": "First Bank",
"accountNumber": "0123456789"
},
"pension": {
"administrator": "Stanbic IBTC Pension",
"number": "PEN100200300"
},
"taxNumber": "12345678-0001",
"nhfNumber": "NHF-55001"
}
}
GET /hr/departments
Departments and head count
Departments set up in HR settings plus any used on employee records, with the number of employees in each.
- Permission
hr.employees- API key scope
hr:read
Example request
curl -X GET "https://your-store.example.com/api/v1/hr/departments" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"name": "Operations",
"employees": 4
},
{
"name": "Sales",
"employees": 9
}
]
}
GET /hr/attendance
Attendance records
- Permission
hr.attendance- API key scope
hr:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
employeeId | id (24 hex characters) | |
late | boolean |
Example request
curl -X GET "https://your-store.example.com/api/v1/hr/attendance" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e512",
"employeeId": "66f1c2a9e4b0a1b2c3d4e511",
"employeeNumber": "E-014",
"name": "Emma Obi",
"role": "Cashier",
"clockIn": "2026-10-02T07:58:00.000Z",
"clockOut": "2026-10-02T17:02:00.000Z",
"late": false,
"location": "Main Street",
"workday": "2026-10-02",
"createdAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /hr/leaves
Leave requests
- Permission
hr.leaves- API key scope
hr:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
employeeId | id (24 hex characters) | |
status | string | max 30 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/hr/leaves" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e513",
"employeeId": "66f1c2a9e4b0a1b2c3d4e511",
"employeeNumber": "E-014",
"name": "Emma Obi",
"type": "Annual leave",
"status": "1",
"startDate": "2026-11-03",
"endDate": "2026-11-07",
"duration": 5,
"paid": true,
"note": "Family trip",
"createdAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /hr/payroll
Payroll records (payslips)
- Permission
hr.payroll- API key scope
hr:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
q | string | Search text. max 100 characters |
employeeId | id (24 hex characters) | |
department | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/hr/payroll" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e514",
"employeeId": "66f1c2a9e4b0a1b2c3d4e511",
"employeeNumber": "E-014",
"name": "Emma Obi",
"designation": "Cashier",
"department": "Sales",
"payDate": "2026-09-30T00:00:00.000Z",
"payType": "month",
"basic": 180000,
"allowance": 50000,
"other": 20000,
"gross": 250000,
"net": 221500,
"deductions": {
"tax": 18500,
"pension": 10000
},
"attendanceDays": 21,
"totalDays": 22,
"unpaidLeaveDays": 0,
"latenessCount": 1,
"createdAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /hr/payroll/:id
Get a payroll record
- Permission
hr.payroll- API key scope
hr:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/hr/payroll/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e514",
"employeeId": "66f1c2a9e4b0a1b2c3d4e511",
"employeeNumber": "E-014",
"name": "Emma Obi",
"designation": "Cashier",
"department": "Sales",
"payDate": "2026-09-30T00:00:00.000Z",
"payType": "month",
"basic": 180000,
"allowance": 50000,
"other": 20000,
"gross": 250000,
"net": 221500,
"deductions": {
"tax": 18500,
"pension": 10000
},
"attendanceDays": 21,
"totalDays": 22,
"unpaidLeaveDays": 0,
"latenessCount": 1,
"createdAt": "2026-10-02T14:05:00.000Z"
}
}
Finance
Read-only access to the Finance module. Each list needs the matching Finance permission (e.g. financial.finexpenses). API keys need the finance scope.
GET /finance/income
List income entries
- Permission
financial.finincome- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: Received, Pending, Cancelled | |
category | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/income" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e520",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "INC-0042",
"date": "2026-10-02T14:05:00.000Z",
"reference": "POS-SALES-0210",
"description": "Daily POS sales",
"category": "Sales",
"source": "POS",
"amount": 845000,
"paymentMethod": "Cash",
"status": "Received",
"notes": ""
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/income/:id
Get one of the income entries
- Permission
financial.finincome- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/income/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e520",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "INC-0042",
"date": "2026-10-02T14:05:00.000Z",
"reference": "POS-SALES-0210",
"description": "Daily POS sales",
"category": "Sales",
"source": "POS",
"amount": 845000,
"paymentMethod": "Cash",
"status": "Received",
"notes": ""
}
}
GET /finance/expenses
List expenses
- Permission
financial.finexpenses- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: Paid, Unpaid, Partially Paid, Cancelled | |
vendorId | id (24 hex characters) | |
category | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/expenses" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e521",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "EXP-0108",
"date": "2026-10-02T14:05:00.000Z",
"dueDate": "2026-10-16T00:00:00.000Z",
"reference": "INV-7781",
"description": "Generator diesel",
"category": "Utilities",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"amount": 120000,
"paymentMethod": "Bank transfer",
"status": "Paid",
"notes": ""
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/expenses/:id
Get one of the expenses
- Permission
financial.finexpenses- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/expenses/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e521",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "EXP-0108",
"date": "2026-10-02T14:05:00.000Z",
"dueDate": "2026-10-16T00:00:00.000Z",
"reference": "INV-7781",
"description": "Generator diesel",
"category": "Utilities",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"amount": 120000,
"paymentMethod": "Bank transfer",
"status": "Paid",
"notes": ""
}
}
GET /finance/vendors
List vendors
- Permission
financial.finvendors- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: Active, Inactive |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/vendors" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e522",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "VEN-0007",
"code": "TOTAL",
"name": "Total Energies",
"company": "Total Energies Marketing Nigeria",
"email": "sales@total.example",
"phone": "01-2700000",
"address": "4 Adeola Odeku",
"city": "Lagos",
"state": "Lagos",
"contactPerson": "Musa Bello",
"openingBalance": 0,
"creditLimit": 1000000,
"paymentTerms": "Net 30",
"status": "Active"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/vendors/:id
Get one of the vendors
- Permission
financial.finvendors- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/vendors/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "VEN-0007",
"code": "TOTAL",
"name": "Total Energies",
"company": "Total Energies Marketing Nigeria",
"email": "sales@total.example",
"phone": "01-2700000",
"address": "4 Adeola Odeku",
"city": "Lagos",
"state": "Lagos",
"contactPerson": "Musa Bello",
"openingBalance": 0,
"creditLimit": 1000000,
"paymentTerms": "Net 30",
"status": "Active"
}
}
GET /finance/payables
List payables (bills to pay)
- Permission
financial.finpayables- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: Unpaid, Partially Paid, Paid, Overdue | |
vendorId | id (24 hex characters) | |
category | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/payables" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e523",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "PAY-0031",
"date": "2026-10-01T09:30:00.000Z",
"dueDate": "2026-10-31T00:00:00.000Z",
"reference": "INV-7790",
"description": "Rice supply (200 bags)",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"amount": 1040000,
"paid": 500000,
"balance": 540000,
"status": "Partially Paid",
"notes": ""
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/payables/:id
Get one of the payables (bills to pay)
- Permission
financial.finpayables- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/payables/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e523",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "PAY-0031",
"date": "2026-10-01T09:30:00.000Z",
"dueDate": "2026-10-31T00:00:00.000Z",
"reference": "INV-7790",
"description": "Rice supply (200 bags)",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"amount": 1040000,
"paid": 500000,
"balance": 540000,
"status": "Partially Paid",
"notes": ""
}
}
GET /finance/receivables
List receivables (money owed to you)
- Permission
financial.finreceivables- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: Outstanding, Partially Received, Received, Overdue | |
category | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/receivables" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e524",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "REC-0012",
"date": "2026-10-01T09:30:00.000Z",
"dueDate": "2026-10-20T00:00:00.000Z",
"reference": "WHL-0009",
"description": "Wholesale order for Ade Foods",
"source": "Wholesale",
"amount": 650000,
"received": 300000,
"balance": 350000,
"status": "Partially Received",
"notes": ""
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/receivables/:id
Get one of the receivables (money owed to you)
- Permission
financial.finreceivables- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/receivables/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e524",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "REC-0012",
"date": "2026-10-01T09:30:00.000Z",
"dueDate": "2026-10-20T00:00:00.000Z",
"reference": "WHL-0009",
"description": "Wholesale order for Ade Foods",
"source": "Wholesale",
"amount": 650000,
"received": 300000,
"balance": 350000,
"status": "Partially Received",
"notes": ""
}
}
GET /finance/vendor-payments
List payments to vendors
- Permission
financial.finpayments- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
vendorId | id (24 hex characters) | |
category | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/vendor-payments" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e525",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "VP-0019",
"date": "2026-10-02T14:05:00.000Z",
"reference": "TRF-55120",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"amount": 500000,
"paymentMethod": "Bank transfer",
"description": "Part payment for INV-7790",
"payableId": "66f1c2a9e4b0a1b2c3d4e523",
"notes": ""
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/vendor-payments/:id
Get one of the payments to vendors
- Permission
financial.finpayments- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/vendor-payments/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e525",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "VP-0019",
"date": "2026-10-02T14:05:00.000Z",
"reference": "TRF-55120",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"amount": 500000,
"paymentMethod": "Bank transfer",
"description": "Part payment for INV-7790",
"payableId": "66f1c2a9e4b0a1b2c3d4e523",
"notes": ""
}
}
GET /finance/receivable-payments
List payments received
- Permission
financial.finpayments- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
category | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/receivable-payments" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e526",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "RP-0008",
"date": "2026-10-02T14:05:00.000Z",
"reference": "TRF-88101",
"receivableId": "66f1c2a9e4b0a1b2c3d4e524",
"amount": 300000,
"paymentMethod": "Bank transfer",
"description": "Ade Foods part payment",
"notes": ""
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/receivable-payments/:id
Get one of the payments received
- Permission
financial.finpayments- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/receivable-payments/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e526",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "RP-0008",
"date": "2026-10-02T14:05:00.000Z",
"reference": "TRF-88101",
"receivableId": "66f1c2a9e4b0a1b2c3d4e524",
"amount": 300000,
"paymentMethod": "Bank transfer",
"description": "Ade Foods part payment",
"notes": ""
}
}
GET /finance/transactions
List ledger transactions
- Permission
financial.fintransactions- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
type | one of: Income, Expense, Vendor Payment, Receivable, Receivable Payment, Payable, Adjustment | |
vendorId | id (24 hex characters) | |
category | string | max 100 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/transactions" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e527",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "TXN-1201",
"date": "2026-10-02T14:05:00.000Z",
"reference": "EXP-0108",
"type": "Expense",
"description": "Generator diesel",
"category": "Utilities",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"debit": 120000,
"credit": 0,
"amount": 120000,
"balance": 3240000,
"paymentMethod": "Bank transfer",
"status": "Posted",
"sourceId": "66f1c2a9e4b0a1b2c3d4e521"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/transactions/:id
Get one of the ledger transactions
- Permission
financial.fintransactions- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/transactions/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e527",
"createdAt": "2026-10-02T14:05:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "TXN-1201",
"date": "2026-10-02T14:05:00.000Z",
"reference": "EXP-0108",
"type": "Expense",
"description": "Generator diesel",
"category": "Utilities",
"vendor": {
"id": "66f1c2a9e4b0a1b2c3d4e522",
"name": "Total Energies"
},
"debit": 120000,
"credit": 0,
"amount": 120000,
"balance": 3240000,
"paymentMethod": "Bank transfer",
"status": "Posted",
"sourceId": "66f1c2a9e4b0a1b2c3d4e521"
}
}
GET /finance/budgets
List budgets
- Permission
financial.finbudgets- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/budgets" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e528",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "BUD-2026-Q4",
"name": "Q4 utilities",
"category": "Utilities",
"period": "quarterly",
"startDate": "2026-10-01T00:00:00.000Z",
"endDate": "2026-12-31T00:00:00.000Z",
"amount": 600000,
"notes": ""
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/budgets/:id
Get one of the budgets
- Permission
financial.finbudgets- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/budgets/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e528",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "BUD-2026-Q4",
"name": "Q4 utilities",
"category": "Utilities",
"period": "quarterly",
"startDate": "2026-10-01T00:00:00.000Z",
"endDate": "2026-12-31T00:00:00.000Z",
"amount": 600000,
"notes": ""
}
}
GET /finance/categories
List categories
- Permission
financial.fincategories- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: Active, Inactive | |
type | one of: Income, Expense |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/categories" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e529",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "CAT-0004",
"name": "Utilities",
"type": "Expense",
"description": "Power, water, internet",
"status": "Active"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /finance/categories/:id
Get one of the categories
- Permission
financial.fincategories- API key scope
finance:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/categories/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e529",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"number": "CAT-0004",
"name": "Utilities",
"type": "Expense",
"description": "Power, water, internet",
"status": "Active"
}
}
GET /finance/summary
Income, expenses and balances for a period
Totals of received income and non-cancelled expenses in the period (default: this month), plus what is still owed to and by you today.
- Permission
financial.finreportsorfinancial.findashboard- API key scope
finance:read
Query parameters
| Name | Type | Details |
|---|---|---|
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
Example request
curl -X GET "https://your-store.example.com/api/v1/finance/summary" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"period": {
"from": "2026-10-01",
"to": "2026-10-31"
},
"income": {
"total": 1200000,
"count": 14
},
"expenses": {
"total": 830000,
"count": 22
},
"net": 370000,
"payablesOutstanding": {
"total": 150000,
"count": 3
},
"receivablesOutstanding": {
"total": 90000,
"count": 2
}
}
}
Projects
Projects (project.project) and tasks (project.alltask), limited to the ones you take part in. API keys need the projects scope.
GET /projects
List your projects
- Permission
project.project- API key scope
projects:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
status | one of: new, started, ongoing, in_review, completed |
Example request
curl -X GET "https://your-store.example.com/api/v1/projects" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e515",
"title": "Open the Ikeja branch",
"status": "ongoing",
"startsAt": "2026-09-01T00:00:00.000Z",
"endsAt": "2026-12-01T00:00:00.000Z",
"owner": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"members": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"tasks": {
"total": 12,
"completed": 5
},
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /projects/:id
Get a project
- Permission
project.project- API key scope
projects:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/projects/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e515",
"title": "Open the Ikeja branch",
"status": "ongoing",
"startsAt": "2026-09-01T00:00:00.000Z",
"endsAt": "2026-12-01T00:00:00.000Z",
"owner": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"members": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"tasks": {
"total": 12,
"completed": 5,
"byStatus": {
"new": 2,
"started": 1,
"ongoing": 3,
"in_review": 1,
"completed": 5
}
},
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
}
GET /projects/:id/tasks
List a project's tasks
- Permission
project.projectorproject.alltask- API key scope
projects:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
status | one of: new, started, ongoing, in_review, completed |
Example request
curl -X GET "https://your-store.example.com/api/v1/projects/66f1c2a9e4b0a1b2c3d4e5f6/tasks" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e516",
"projectId": "66f1c2a9e4b0a1b2c3d4e515",
"title": "Order shelving",
"type": "task",
"status": "started",
"startDate": "2026-10-01T00:00:00.000Z",
"endDate": "2026-10-10T00:00:00.000Z",
"budget": 450000,
"owner": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"assignedTo": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"members": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"workflow": "Purchase approval",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /tasks
List your tasks
- Permission
project.alltask- API key scope
projects:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
sort | string | Comma-separated fields; prefix with - for descending. Example: -createdAt,name max 100 characters |
fields | string | Comma-separated fields to return. Example: id,name,status max 500 characters |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
status | one of: new, started, ongoing, in_review, completed | |
projectId | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/tasks" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e516",
"projectId": "66f1c2a9e4b0a1b2c3d4e515",
"title": "Order shelving",
"type": "task",
"status": "started",
"startDate": "2026-10-01T00:00:00.000Z",
"endDate": "2026-10-10T00:00:00.000Z",
"budget": 450000,
"owner": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"assignedTo": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"members": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"workflow": "Purchase approval",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /tasks/:id
Get a task
- Permission
project.alltaskorproject.project- API key scope
projects:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | id (24 hex characters) |
Example request
curl -X GET "https://your-store.example.com/api/v1/tasks/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"id": "66f1c2a9e4b0a1b2c3d4e516",
"projectId": "66f1c2a9e4b0a1b2c3d4e515",
"title": "Order shelving",
"type": "task",
"status": "started",
"startDate": "2026-10-01T00:00:00.000Z",
"endDate": "2026-10-10T00:00:00.000Z",
"budget": 450000,
"owner": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"assignedTo": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"members": [
{
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"email": "jane@example.com"
}
],
"workflow": "Purchase approval",
"createdAt": "2026-10-01T09:30:00.000Z",
"updatedAt": "2026-10-02T14:05:00.000Z",
"description": "Get three quotes and order shelving for the new branch.",
"approvals": [
{
"title": "Manager approval",
"approved": true,
"by": "Jane Doe",
"at": "2026-10-02T14:05:00.000Z"
}
]
}
}
Reports
Sales reports (pos.report or pos.sales). Cancelled and refunded orders are left out. Default period: the last 30 days. API keys need the reports scope.
GET /reports/sales
Sales summary
Totals for the period plus a breakdown by day, week or month and by payment method.
- Permission
pos.reportorpos.sales- API key scope
reports:read
Query parameters
| Name | Type | Details |
|---|---|---|
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
store | string | "all" or a store id (needs pos.stores). Default: your store. max 30 characters; must be "all", "current" or a store id |
groupBy | one of: day, week, month | default "day" |
Example request
curl -X GET "https://your-store.example.com/api/v1/reports/sales" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"period": {
"from": "2026-09-01T00:00:00.000Z",
"to": "2026-09-30T23:59:59.999Z"
},
"totals": {
"orders": 412,
"revenue": 5384000,
"tax": 375600,
"discounts": 21000,
"averageOrder": 13067.96,
"itemsSold": 1530
},
"series": [
{
"period": "2026-09-01",
"orders": 14,
"revenue": 182500
},
{
"period": "2026-09-02",
"orders": 11,
"revenue": 151200
}
],
"byPaymentMethod": [
{
"method": "cash",
"orders": 260,
"revenue": 3105000
},
{
"method": "transfer",
"orders": 152,
"revenue": 2279000
}
],
"byStatus": [
{
"status": "completed",
"orders": 398
},
{
"status": "cancelled",
"orders": 14
}
]
}
}
GET /reports/top-products
Best-selling products
- Permission
pos.reportorpos.sales- API key scope
reports:read
Query parameters
| Name | Type | Details |
|---|---|---|
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
store | string | "all" or a store id (needs pos.stores). Default: your store. max 30 characters; must be "all", "current" or a store id |
limit | integer | 1–100; default 10 |
by | one of: revenue, quantity | default "revenue" |
Example request
curl -X GET "https://your-store.example.com/api/v1/reports/top-products" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"productId": "66f1c2a9e4b0a1b2c3d4e503",
"name": "Rice 5kg",
"sku": "RICE5",
"quantity": 186,
"revenue": 1209000,
"orders": 141
}
],
"meta": {
"period": {
"from": "2026-09-01T00:00:00.000Z",
"to": "2026-09-30T23:59:59.999Z"
}
}
}
GET /reports/staff
Sales by staff member
- Permission
pos.reportorpos.sales- API key scope
reports:read
Query parameters
| Name | Type | Details |
|---|---|---|
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
store | string | "all" or a store id (needs pos.stores). Default: your store. max 30 characters; must be "all", "current" or a store id |
Example request
curl -X GET "https://your-store.example.com/api/v1/reports/staff" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"staffId": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe",
"orders": 210,
"revenue": 2744000,
"averageOrder": 13066.67
}
],
"meta": {
"period": {
"from": "2026-09-01T00:00:00.000Z",
"to": "2026-09-30T23:59:59.999Z"
}
}
}
Administration
Activity log, permissions and settings. API keys need the admin scope.
GET /admin/activity-logs
Activity log
Who did what and when, across all modules (including API calls, marked with source "api"). Sensitive values in before/after snapshots are redacted.
- Permission
admin.adminorlogs/general.activityorlogs/general.logs- API key scope
admin:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–200; default 25 |
q | string | Search text. max 100 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
module | string | max 40 characters |
action | string | max 40 characters |
userId | id (24 hex characters) | |
resource | string | max 60 characters |
resourceId | string | max 60 characters |
status | one of: success, failure |
Example request
curl -X GET "https://your-store.example.com/api/v1/admin/activity-logs" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e518",
"at": "2026-10-02T14:05:00.000Z",
"module": "pos",
"action": "update",
"resource": "pos_product",
"resourceId": "66f1c2a9e4b0a1b2c3d4e503",
"description": "Updated product Rice 5kg (API, token)",
"status": "success",
"user": {
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"source": "api",
"ip": "102.89.1.20",
"method": "PATCH",
"path": "/api/v1/products/66f1c2a9e4b0a1b2c3d4e503",
"requestId": "106213322361546",
"before": {
"name": "Rice 5 kg"
},
"after": {
"name": "Rice 5kg"
}
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /admin/permissions
Permission catalogue
Every menu and permission key the app knows, as used by PUT /users/{id}/permissions.
- Permission
admin.permissionoradmin.admin- API key scope
admin:read
Example request
curl -X GET "https://your-store.example.com/api/v1/admin/permissions" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"menu": "pos",
"name": "POS",
"permissions": {
"pos": "View POS",
"products": "View Products"
}
}
]
}
GET /admin/settings
Main settings (no secrets)
- Permission
pos.settingorpos.onlinestore- API key scope
admin:read
Example request
curl -X GET "https://your-store.example.com/api/v1/admin/settings" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"vatRate": 7.5,
"currencySymbol": "NGN",
"lowStockAlert": true,
"enableOnlineOrder": true,
"minOrderAmount": 0,
"orderPrepTime": 20,
"notificationEmail": "owner@example.com",
"messaging": {
"emailConfigured": true,
"fromEmail": "shop@example.com",
"fromName": "Main Street",
"smsConfigured": false,
"smsProvider": "",
"sendOrderConfirmation": true,
"enableSmsNotifications": false,
"sendWelcomeEmails": false
},
"api": {
"keys": 2,
"activeKeys": 1
},
"webhooks": 1,
"maintenance": {
"enabled": false
}
}
}
Notifications
Your own in-app notifications (the bell). No extra permission needed. API keys need the notifications scope, or plain read/write.
GET /notifications
List your notifications
- Permission
- Any signed-in user
- API key scope
notifications:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
unread | boolean | |
category | string | max 30 characters |
Example request
curl -X GET "https://your-store.example.com/api/v1/notifications" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "66f1c2a9e4b0a1b2c3d4e530",
"type": "stock",
"icon": "fa-box",
"title": "Low stock: Rice 5kg",
"message": "Only 4 left at Main Street.",
"link": "/inventory",
"category": "inventory",
"event": "inventory.low_stock",
"priority": "high",
"read": false,
"readAt": null,
"from": "System",
"createdAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false,
"unread": 3
}
}
POST /notifications/:id/read
Mark a notification as read
- Permission
- Any signed-in user
- API key scope
notifications:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a notification id or "all" |
Example request
curl -X POST "https://your-store.example.com/api/v1/notifications/66f1c2a9e4b0a1b2c3d4e5f6/read" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"updated": 1
}
}
Webhooks & events
Send events to other systems. Each delivery is a signed JSON POST (see the X-Webhook-Signature header: HMAC-SHA256 of "<timestamp>.<body>" with the webhook secret), retried with growing delays when the receiver is down. Needs pos.onlinestore; API keys need the admin scope.
GET /event-types
Events you can subscribe to
- Permission
- Any signed-in user
- API key scope
admin:read
Example request
curl -X GET "https://your-store.example.com/api/v1/event-types" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"name": "order.created",
"group": "Orders",
"description": "A sale or online order was placed."
}
]
}
GET /webhooks
List webhooks
- Permission
pos.onlinestore- API key scope
admin:read
Example request
curl -X GET "https://your-store.example.com/api/v1/webhooks" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"name": "Accounting sync",
"url": "https://example.com/hooks/pos",
"events": [
"order.created",
"refund.created"
],
"event": "order.created",
"status": "active",
"retryCount": 3,
"signed": true,
"secretHint": "whsec_…9f0e",
"lastDeliveryAt": "2026-10-02T14:05:00.000Z",
"lastStatus": "success",
"lastError": null,
"consecutiveFailures": 0,
"createdAt": "2026-10-01T09:30:00.000Z"
}
]
}
GET /webhooks/:id
Get a webhook
- Permission
pos.onlinestore- API key scope
admin:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a webhook id (wh_…) |
Example request
curl -X GET "https://your-store.example.com/api/v1/webhooks/wh_3f9c0a1b2c3d4e5f" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"name": "Accounting sync",
"url": "https://example.com/hooks/pos",
"events": [
"order.created",
"refund.created"
],
"event": "order.created",
"status": "active",
"retryCount": 3,
"signed": true,
"secretHint": "whsec_…9f0e",
"lastDeliveryAt": "2026-10-02T14:05:00.000Z",
"lastStatus": "success",
"lastError": null,
"consecutiveFailures": 0,
"createdAt": "2026-10-01T09:30:00.000Z"
}
}
POST /webhooks
Create a webhook
The response includes secret once. Keep it to check signatures; afterwards only a hint is shown.
- Permission
pos.onlinestore- API key scope
admin:write
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name required | string | max 100 characters |
url required | string | max 500 characters |
events required | array of string | Event names from GET /event-types, or ["*"] for all events. 1–50 items |
status | one of: active, inactive | default "active" |
retryCount | integer | 0–10; default 3 |
Example request
curl -X POST "https://your-store.example.com/api/v1/webhooks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"name","url":"https://example.com/hooks/pos","events":["order.created","order.updated"]}'
Example response (201 Created)
{
"success": true,
"message": "Created",
"data": {
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"name": "Accounting sync",
"url": "https://example.com/hooks/pos",
"events": [
"order.created",
"refund.created"
],
"event": "order.created",
"status": "active",
"retryCount": 3,
"signed": true,
"secretHint": "whsec_…9f0e",
"lastDeliveryAt": "2026-10-02T14:05:00.000Z",
"lastStatus": "success",
"lastError": null,
"consecutiveFailures": 0,
"createdAt": "2026-10-01T09:30:00.000Z",
"secret": "whsec_<secret shown once>"
}
}
PATCH /webhooks/:id
Change a webhook
- Permission
pos.onlinestore- API key scope
admin:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a webhook id (wh_…) |
Request body (JSON)
| Name | Type | Details |
|---|---|---|
name | string | max 100 characters |
url | string | max 500 characters |
events | array of string | Event names from GET /event-types, or ["*"] for all events. 1–50 items |
status | one of: active, inactive | |
retryCount | integer | 0–10 |
Example request
curl -X PATCH "https://your-store.example.com/api/v1/webhooks/wh_3f9c0a1b2c3d4e5f" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"events":["order.created","order.updated"]}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"name": "Accounting sync",
"url": "https://example.com/hooks/pos",
"events": [
"order.created",
"refund.created"
],
"event": "order.created",
"status": "active",
"retryCount": 3,
"signed": true,
"secretHint": "whsec_…9f0e",
"lastDeliveryAt": "2026-10-02T14:05:00.000Z",
"lastStatus": "success",
"lastError": null,
"consecutiveFailures": 0,
"createdAt": "2026-10-01T09:30:00.000Z"
}
}
DELETE /webhooks/:id
Delete a webhook
- Permission
pos.onlinestore- API key scope
admin:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a webhook id (wh_…) |
Example request
curl -X DELETE "https://your-store.example.com/api/v1/webhooks/wh_3f9c0a1b2c3d4e5f" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"webhookId": "wh_3f9c0a1b2c3d4e5f"
}
}
POST /webhooks/:id/test
Send a test event
Sends a webhook.test event to this webhook now (even if it is inactive) and returns the result.
- Permission
pos.onlinestore- API key scope
admin:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a webhook id (wh_…) |
Example request
curl -X POST "https://your-store.example.com/api/v1/webhooks/wh_3f9c0a1b2c3d4e5f/test" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"webhookName": "Accounting sync",
"url": "https://example.com/hooks/pos",
"event": "webhook.test",
"eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"status": "success",
"test": true,
"signed": true,
"attempts": 1,
"maxAttempts": 4,
"nextAttemptAt": null,
"lastAttemptAt": "2026-10-02T14:05:00.000Z",
"deliveredAt": "2026-10-02T14:05:00.000Z",
"responseStatus": 200,
"durationMs": 182,
"error": "",
"createdAt": "2026-10-02T14:05:00.000Z",
"payload": {
"id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"event": "order.created",
"createdAt": "2026-10-02T14:05:00.000Z",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"actor": {
"type": "user",
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"data": {
"order": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"total": {
"amount": 13975,
"currency": "NGN"
}
}
}
},
"responseBody": "{\"received\":true}",
"history": [
{
"at": "2026-10-02T14:05:00.000Z",
"status": "success",
"responseStatus": 200,
"durationMs": 182,
"error": ""
}
]
}
}
POST /webhooks/:id/secret
Create a new signing secret
Replaces the signing secret; the new one is returned once. Deliveries from now on are signed with it.
- Permission
pos.onlinestore- API key scope
admin:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a webhook id (wh_…) |
Example request
curl -X POST "https://your-store.example.com/api/v1/webhooks/wh_3f9c0a1b2c3d4e5f/secret" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"secret": "whsec_<secret shown once>"
}
}
GET /webhook-deliveries
Delivery log
Newest first. Each delivery is one event sent to one webhook, with its attempts.
- Permission
pos.onlinestore- API key scope
admin:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
webhookId | string | max 40 characters |
event | string | max 60 characters |
status | one of: pending, retrying, success, failed, cancelled |
Example request
curl -X GET "https://your-store.example.com/api/v1/webhook-deliveries" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"webhookName": "Accounting sync",
"url": "https://example.com/hooks/pos",
"event": "order.created",
"eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"status": "success",
"test": false,
"signed": true,
"attempts": 1,
"maxAttempts": 4,
"nextAttemptAt": null,
"lastAttemptAt": "2026-10-02T14:05:00.000Z",
"deliveredAt": "2026-10-02T14:05:00.000Z",
"responseStatus": 200,
"durationMs": 182,
"error": "",
"createdAt": "2026-10-02T14:05:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
GET /webhook-deliveries/:id
Get a delivery
Includes the payload that was sent, the start of the response, and every attempt.
- Permission
pos.onlinestore- API key scope
admin:read
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a delivery id (whd_…) |
Example request
curl -X GET "https://your-store.example.com/api/v1/webhook-deliveries/66f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"webhookName": "Accounting sync",
"url": "https://example.com/hooks/pos",
"event": "order.created",
"eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"status": "success",
"test": false,
"signed": true,
"attempts": 1,
"maxAttempts": 4,
"nextAttemptAt": null,
"lastAttemptAt": "2026-10-02T14:05:00.000Z",
"deliveredAt": "2026-10-02T14:05:00.000Z",
"responseStatus": 200,
"durationMs": 182,
"error": "",
"createdAt": "2026-10-02T14:05:00.000Z",
"payload": {
"id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"event": "order.created",
"createdAt": "2026-10-02T14:05:00.000Z",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"actor": {
"type": "user",
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"data": {
"order": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"total": {
"amount": 13975,
"currency": "NGN"
}
}
}
},
"responseBody": "{\"received\":true}",
"history": [
{
"at": "2026-10-02T14:05:00.000Z",
"status": "success",
"responseStatus": 200,
"durationMs": 182,
"error": ""
}
]
}
}
POST /webhook-deliveries/:id/retry
Send a delivery again
- Permission
pos.onlinestore- API key scope
admin:write
Path parameters
| Name | Type | Details |
|---|---|---|
id required | string | must be a delivery id (whd_…) |
Example request
curl -X POST "https://your-store.example.com/api/v1/webhook-deliveries/66f1c2a9e4b0a1b2c3d4e5f6/retry" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
"webhookId": "wh_3f9c0a1b2c3d4e5f",
"webhookName": "Accounting sync",
"url": "https://example.com/hooks/pos",
"event": "order.created",
"eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"status": "success",
"test": false,
"signed": true,
"attempts": 1,
"maxAttempts": 4,
"nextAttemptAt": null,
"lastAttemptAt": "2026-10-02T14:05:00.000Z",
"deliveredAt": "2026-10-02T14:05:00.000Z",
"responseStatus": 200,
"durationMs": 182,
"error": "",
"createdAt": "2026-10-02T14:05:00.000Z",
"payload": {
"id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"event": "order.created",
"createdAt": "2026-10-02T14:05:00.000Z",
"source": "api",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"actor": {
"type": "user",
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"data": {
"order": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"total": {
"amount": 13975,
"currency": "NGN"
}
}
}
},
"responseBody": "{\"received\":true}",
"history": [
{
"at": "2026-10-02T14:05:00.000Z",
"status": "success",
"responseStatus": 200,
"durationMs": 182,
"error": ""
}
]
}
}
GET /events
Event history
Everything that happened (orders, payments, customers, stock, HR…), newest first, with the data sent to webhooks.
- Permission
pos.onlinestore- API key scope
admin:read
Query parameters
| Name | Type | Details |
|---|---|---|
page | integer | Page number (starts at 1). min 1; default 1 |
limit | integer | Items per page (max 100). 1–100; default 25 |
event | string | max 60 characters |
from | date (YYYY-MM-DD) | Only items on or after this date (YYYY-MM-DD). |
to | date (YYYY-MM-DD) | Only items on or before this date (YYYY-MM-DD, whole day included). |
Example request
curl -X GET "https://your-store.example.com/api/v1/events" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
"event": "order.created",
"source": "api",
"occurredAt": "2026-10-02T14:05:00.000Z",
"storeId": "66f1c2a9e4b0a1b2c3d4e501",
"actor": {
"type": "user",
"id": "66f1c2a9e4b0a1b2c3d4e502",
"name": "Jane Doe"
},
"webhooks": 1,
"data": {
"order": {
"id": "66f1c2a9e4b0a1b2c3d4e505",
"orderNumber": "ORD1790904240356987",
"status": "confirmed",
"total": {
"amount": 13975,
"currency": "NGN"
}
}
}
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1,
"pages": 1,
"hasNext": false,
"hasPrev": false
}
}
Assistant
Questions about sales, stock, customers, finance, HR and projects, answered from this installation's data without any internet service. API keys need the ai scope (or plain read) plus the scope of the data asked about.
POST /ai/ask
Ask a question
status is answered, no_match (with suggestions) or denied (the user or key may not see that data). Answers can include facts (headline figures), a table and a chart; money values are plain numbers in the store currency (currency).
- Permission
- Any signed-in user
- API key scope
ai:read
Request body (JSON)
| Name | Type | Details |
|---|---|---|
question required | string | 2–300 characters |
Example request
curl -X POST "https://your-store.example.com/api/v1/ai/ask" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"question":"How much did we sell this month?"}'
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": {
"status": "answered",
"question": "How much did we sell this month?",
"intent": "sales.summary",
"area": "sales",
"areaLabel": "Sales",
"period": {
"label": "this month",
"from": "2026-10-01T00:00:00.000Z",
"to": "2026-10-02T23:59:59.999Z"
},
"store": null,
"currency": "NGN",
"corrections": [],
"link": {
"href": "/pos/report",
"label": "Sales report"
},
"answer": "You sold NGN845,000 this month at Main Street from 64 orders (average NGN13,203.13). That is +12.5% compared with the previous period.",
"facts": [
{
"label": "Revenue",
"value": 845000,
"type": "money"
},
{
"label": "Orders",
"value": 64,
"type": "number"
},
{
"label": "Average order",
"value": 13203.13,
"type": "money"
},
{
"label": "Items sold",
"value": 211,
"type": "number"
}
],
"chart": {
"type": "line",
"labels": [
"2026-10-01",
"2026-10-02"
],
"series": [
{
"label": "Revenue",
"data": [
402000,
443000
]
}
],
"format": "money"
}
}
}
GET /ai/suggestions
Questions you can ask
Example questions grouped by area, limited to the data this user (and key) may see.
- Permission
- Any signed-in user
- API key scope
ai:read
Example request
curl -X GET "https://your-store.example.com/api/v1/ai/suggestions" \
-H "Authorization: Bearer $TOKEN"
Example response (200 OK)
{
"success": true,
"message": "Request successful",
"data": [
{
"area": "sales",
"label": "Sales",
"questions": [
"How much did we sell this month?"
]
},
{
"area": "inventory",
"label": "Inventory",
"questions": [
"Which products are out of stock?"
]
}
]
}
Generated from the API definitions in backend/api/v1/modules and the webhook events in backend/services/webhookService.js.