Las guías para desarrolladores están en inglés.

Machine-readable version: openapi.json (OpenAPI 3) — import it into Postman or Insomnia, or use the ready-made Postman collections (one per category, sign-in included).

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

HeaderDirectionMeaning
Authorization: Bearer …requestAccess token or API key.
X-API-KeyrequestAPI key (alternative to Authorization).
Content-Type: application/jsonrequestRequired when sending a body.
X-Request-IdresponseUnique id of the request; also in error bodies. Quote it when asking for help.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetresponseYour request allowance (see rate limits).
Retry-AfterresponseSeconds 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:

ParameterMeaning
pagePage number, from 1.
limitItems per page, default 25, maximum 100.
sortComma-separated fields, - for descending, e.g. -createdAt,name. An unknown field returns 400 with the list of sortable fields.
fieldsOnly return these fields, e.g. id,name,status.
qSearch text (where offered).
from, toDate 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,totalQuantity

Permissions 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_LIMITED and a Retry-After header.

Errors and status codes

StatusCodeMeaning
200OKThe request worked.
201CreatedSomething was created (token, product, order, customer, webhook…).
400BAD_REQUESTThe request is malformed: invalid JSON, a bad id, or an unknown sort field.
401UNAUTHORIZEDNo credential, or it is wrong, expired or revoked. Also OTP_REQUIRED when a two-factor code is needed.
403FORBIDDEN / INSUFFICIENT_SCOPEThe user lacks the permission (details.required names it), or the API key is not allowed this module or writes. ACCOUNT_DISABLED for disabled accounts.
404NOT_FOUNDNo such record, or it belongs to a store you cannot see. Also returned for unknown endpoints.
405METHOD_NOT_ALLOWEDThe path exists but not with this method; the Allow header lists the methods.
409CONFLICT / ACTION_FAILEDDuplicate (e.g. username), not enough stock, or the action is not possible in the current state (e.g. cancelling a cancelled order).
422VALIDATION_ERROROne or more fields are missing or invalid; details lists each field and the problem.
429RATE_LIMITEDToo many requests. Wait for the number of seconds in Retry-After.
500INTERNAL_ERRORUnexpected 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
        }
      ]
    }
  }
}
HeaderMeaning
X-Webhook-IdDelivery id (whd_…). The same on every retry, so you can ignore duplicates.
X-Webhook-EventThe event name, e.g. order.created.
X-Webhook-TimestampWhen this attempt was signed (Unix seconds).
X-Webhook-Signaturet=<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, 429 and 5xx are 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.failed event 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.test event.

Events

EventWhen
Orders
order.createdA sale or online order was placed.
order.updatedAny change to an order (approved, paid, ready, shipped, delivered, cancelled). change says what happened.
order.approvedA pending order was approved.
order.readyThe kitchen marked an order ready.
order.shippedAn order was sent for delivery.
order.deliveredAn order was delivered (fulfilled).
order.cancelledAn order was cancelled or rejected.
Payments
payment.successfulPayment for an order was confirmed.
refund.createdA refund was recorded.
Customers
customer.createdA customer was added (CRM, POS, online store or API).
customer.updatedA customer record was changed.
loyalty.earnedA customer earned loyalty points.
loyalty.redeemedA customer redeemed loyalty points.
loyalty.adjustedLoyalty points were adjusted by staff.
loyalty.expiredLoyalty points expired.
loyalty.tier_changedA customer moved to another membership tier.
Products & stock
product.createdA product was created.
product.updatedA product was changed.
inventory.updatedStock of a product variant changed (sale, edit or adjustment).
inventory.low_stockA variant dropped to or below its low-stock level.
inventory.out_of_stockA variant ran out of stock.
product.expiringA product is close to its expiry date.
product.expiredA product has expired.
HR
employee.createdAn employee was added.
employee.updatedAn employee record was changed.
System
permission.changedA user's permissions were changed.
email.failedAn email could not be delivered.
sms.failedAn SMS could not be delivered.
webhook.failedA 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)

NameTypeDetails
username requiredstring
max 100 characters
password requiredstring
max 200 characters
otpstringTwo-factor code, when enabled for the account.
must be 6 digits
namestringLabel 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"
    }
  }
}

Status codes: 201, 422, 429

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"
    }
  }
}

Status codes: 200, 401, 403, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

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

NameTypeDetails
id requiredstring
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
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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.admin or admin.view
API key scope
admin:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
activebooleanOnly active (true) or disabled (false) users.
storeIdid (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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /users/:id

Get a user (with permissions)

Permission
admin.admin or admin.view
API key scope
admin:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
fieldsstringComma-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"
      }
    }
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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)

NameTypeDetails
username requiredstring
3–50 characters; may contain letters, numbers, dot, dash and underscore
name requiredstring
max 100 characters
email requiredemail
max 200 characters
mobile requiredstring
must be 7-15 digits
addressstring
max 300 characters
password requiredstringAt least 8 characters with upper and lower case letters, a number and a symbol.
max 128 characters
storeId requiredid (24 hex characters)
activeboolean
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"
      }
    }
  }
}

Status codes: 201, 401, 403, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
namestring
1–100 characters
emailemail
max 200 characters
mobilestring
must be 7-15 digits
addressstring
max 300 characters
storeIdid (24 hex characters)
activeboolean

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"
      }
    }
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
permissions requiredobject

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"
      }
    }
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
statusstring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /stores/:id

Get a store

Permission
Any signed-in user
API key scope
pos:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
fieldsstringComma-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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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.products or pos.pos
API key scope
pos:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
storestring"all" or a store id (needs pos.stores). Default: your store.
max 30 characters; must be "all", "current" or a store id
categorystring
max 100 characters
brandstring
max 100 characters
statusone of: active, inactive, discontinued, draft
skustringExact product or variant SKU.
max 60 characters
barcodestring
max 60 characters
stockone of: out, low, inProducts with at least one variant at this stock level.
expiryone 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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /products/:id

Get a product

Permission
pos.products or pos.pos
API key scope
pos:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
fieldsstringComma-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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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)

NameTypeDetails
name requiredstring
max 200 characters
sku requiredstring
max 60 characters; may contain letters, numbers, dot, dash and underscore
barcodestring
max 60 characters
descriptionstring
max 5000 characters
category requiredstring
max 100 characters
subcategorystring
max 100 characters
kitchenCategorystring
max 100 characters
brandstring
max 100 characters
statusone of: active, inactive, discontinued, draft
default "active"
tagsarray of string
max 30 items
weightnumber
min 0
expiryDatestringYYYY-MM-DD; empty string clears it.
max 10 characters; must be YYYY-MM-DD, or empty to clear
currencystringDefaults to the store's currency.
max 10 characters
storeIdid (24 hex characters)
variants requiredarray of object
1–50 items
variants[].namestring
max 100 characters
variants[].skustring
max 60 characters
variants[].price requirednumber
min 0
variants[].compareAtPricenumber
min 0
variants[].costnumber
min 0
variants[].quantityinteger
min 0; default 0
variants[].thresholdinteger
min 0
variants[].locationstring
max 100 characters
variants[].attributesobjecte.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"
  }
}

Status codes: 201, 401, 403, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
namestring
1–200 characters
barcodestring
max 60 characters
descriptionstring
max 5000 characters
categorystring
1–100 characters
subcategorystring
max 100 characters
kitchenCategorystring
max 100 characters
brandstring
max 100 characters
statusone of: active, inactive, discontinued, draft
tagsarray of string
max 30 items
weightnumber
min 0
expiryDatestringYYYY-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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)
variantId requiredstring
max 80 characters

Request body (JSON)

NameTypeDetails
namestring
1–100 characters
pricenumber
min 0
compareAtPricenumber
min 0
costnumber
min 0
thresholdinteger
min 0
locationstring
max 100 characters
isActiveboolean

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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
variantIdstringRequired when the product has several variants.
max 80 characters
adjustmentinteger
-1000000–1000000
quantityinteger
0–100000000
reason requiredstring
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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

GET /inventory/summary

Inventory alerts summary

Counts of expired, expiring, out-of-stock and low-stock items (as on the inventory dashboard).

Permission
pos.products or pos.pos
API key scope
pos:read

Query parameters

NameTypeDetails
storestring"all" or a store id (needs pos.stores). Default: your store.
max 30 characters; must be "all", "current" or a store id
daysintegerExpiring 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"
    ]
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /inventory/report

Inventory alert list

One row per affected product (expiry) or variant (stock).

Permission
pos.products or pos.pos
API key scope
pos:read

Query parameters

NameTypeDetails
type requiredone of: expired, expiring, out, low
daysinteger
1–365
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
qstringSearch text.
max 100 characters
storestring"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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

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.sales or pos.pos
API key scope
pos:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: pending, confirmed, processing, shipped, delivered, cancelled, refunded, on_hold
paymentStatusone of: pending, authorized, paid, partially_refunded, refunded, failed, cancelled
customerIdid (24 hex characters)
orderNumberstring
max 60 characters
sourceone of: pos, web, mobile, api, other
storestring"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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /orders/:id

Get an order

Permission
pos.sales or pos.pos
API key scope
pos:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
fieldsstringComma-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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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)

NameTypeDetails
items requiredarray of object
1–200 items
items[].productId requiredid (24 hex characters)
items[].variantIdstringNeeded when the product has several variants (id, variantId or SKU).
max 80 characters
items[].quantity requiredinteger
1–100000
customerIdid (24 hex characters)CRM customer (for loyalty points and receipts).
paymentobject
payment.methodone of: cash, credit_card, debit_card, digital_wallet, bank_transfer, check, other
default "cash"
couponCodestring
max 50 characters
loyaltyRedeemPointsintegerPoints 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
    }
  }
}

Status codes: 201, 401, 403, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
reasonstring
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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

POST /orders/:id/payments

Record a payment

Permission
pos.pos
API key scope
pos:write

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
amount requirednumber
min 0.01
method requiredone 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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

POST /orders/:id/fulfill

Mark an order fulfilled

Permission
pos.shipping or pos.pos
API key scope
pos:write

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /refunds

List refunds

Permission
pos.refund or pos.sales
API key scope
pos:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
orderIdid (24 hex characters)
statusstring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /refunds/:id

Get a refund

Permission
pos.refund or pos.sales
API key scope
pos:read

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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.customers or crm.addcustomer or crm.support or pos.pos
API key scope
crm:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
emailemail
phonestring
max 30 characters
membershipTierone of: Bronze, Silver, Gold
activeboolean

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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /customers/:id

Get a customer

Permission
crm.customers or crm.addcustomer or crm.support or pos.pos
API key scope
crm:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
fieldsstringComma-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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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)

NameTypeDetails
name requiredstring
max 150 characters
emailemail
max 200 characters
phone requiredstring
max 30 characters; must be a phone number
customerCodestringYour own customer number. Generated when omitted.
max 50 characters
addressstring
max 300 characters
taxIdstring
max 50 characters
membershipTierone of: Bronze, Silver, Gold
default "Bronze"
minimumOrdernumber
min 0
activeboolean

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"
  }
}

Status codes: 201, 401, 403, 422, 429

PATCH /customers/:id

Update a customer

Send only the fields to change.

Permission
crm.addcustomer
API key scope
crm:write

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
namestring
max 150 characters
emailemail
max 200 characters
phonestring
max 30 characters; must be a phone number
customerCodestringYour own customer number. Generated when omitted.
max 50 characters
addressstring
max 300 characters
taxIdstring
max 50 characters
membershipTierone of: Bronze, Silver, Gold
minimumOrdernumber
min 0
activeboolean

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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

GET /customers/:id/loyalty

Loyalty balance and history

Permission
crm.loyalty or crm.customers or pos.pos
API key scope
crm:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
typeone 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
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)

Request body (JSON)

NameTypeDetails
points requiredinteger
-1000000–1000000
reason requiredstring
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
    }
  }
}

Status codes: 201, 400, 401, 403, 404, 422, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: Closed, Not Contacted, Contacted, Lost, Open
priorityone 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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /crm/leads/:id

Get a lead (with recent activity)

Permission
crm.leads
API key scope
crm:read

Path parameters

NameTypeDetails
id requiredid (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"
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /crm/tickets

List support tickets

Permission
crm.view or crm.support
API key scope
crm:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: open, answered, closed
customerIdid (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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /crm/tickets/:id

Get a support ticket

Permission
crm.view or crm.support
API key scope
crm:read

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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

NameTypeDetails
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (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
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /crm/customers/:id/activity

Customer timeline

Latest orders, loyalty entries and support tickets for one customer, newest first.

Permission
crm.customers or crm.support or crm.loyalty
API key scope
crm:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
limitinteger
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"
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
departmentstring
max 100 characters
designationstring
max 100 characters
activeboolean

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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

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

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
fieldsstringComma-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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

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
    }
  ]
}

Status codes: 200, 401, 403, 429

GET /hr/attendance

Attendance records

Permission
hr.attendance
API key scope
hr:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
employeeIdid (24 hex characters)
lateboolean

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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /hr/leaves

Leave requests

Permission
hr.leaves
API key scope
hr:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
employeeIdid (24 hex characters)
statusstring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /hr/payroll

Payroll records (payslips)

Permission
hr.payroll
API key scope
hr:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
qstringSearch text.
max 100 characters
employeeIdid (24 hex characters)
departmentstring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /hr/payroll/:id

Get a payroll record

Permission
hr.payroll
API key scope
hr:read

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: Received, Pending, Cancelled
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/income/:id

Get one of the income entries

Permission
financial.finincome
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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": ""
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/expenses

List expenses

Permission
financial.finexpenses
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: Paid, Unpaid, Partially Paid, Cancelled
vendorIdid (24 hex characters)
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/expenses/:id

Get one of the expenses

Permission
financial.finexpenses
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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": ""
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/vendors

List vendors

Permission
financial.finvendors
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone 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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/vendors/:id

Get one of the vendors

Permission
financial.finvendors
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/payables

List payables (bills to pay)

Permission
financial.finpayables
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: Unpaid, Partially Paid, Paid, Overdue
vendorIdid (24 hex characters)
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/payables/:id

Get one of the payables (bills to pay)

Permission
financial.finpayables
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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": ""
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/receivables

List receivables (money owed to you)

Permission
financial.finreceivables
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: Outstanding, Partially Received, Received, Overdue
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/receivables/:id

Get one of the receivables (money owed to you)

Permission
financial.finreceivables
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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": ""
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/vendor-payments

List payments to vendors

Permission
financial.finpayments
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
vendorIdid (24 hex characters)
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/vendor-payments/:id

Get one of the payments to vendors

Permission
financial.finpayments
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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": ""
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/receivable-payments

List payments received

Permission
financial.finpayments
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/receivable-payments/:id

Get one of the payments received

Permission
financial.finpayments
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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": ""
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/transactions

List ledger transactions

Permission
financial.fintransactions
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
typeone of: Income, Expense, Vendor Payment, Receivable, Receivable Payment, Payable, Adjustment
vendorIdid (24 hex characters)
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/transactions/:id

Get one of the ledger transactions

Permission
financial.fintransactions
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/budgets

List budgets

Permission
financial.finbudgets
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/budgets/:id

Get one of the budgets

Permission
financial.finbudgets
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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": ""
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /finance/categories

List categories

Permission
financial.fincategories
API key scope
finance:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: Active, Inactive
typeone 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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /finance/categories/:id

Get one of the categories

Permission
financial.fincategories
API key scope
finance:read

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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.finreports or financial.findashboard
API key scope
finance:read

Query parameters

NameTypeDetails
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (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
    }
  }
}

Status codes: 200, 400, 401, 403, 422, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
statusone 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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /projects/:id

Get a project

Permission
project.project
API key scope
projects:read

Path parameters

NameTypeDetails
id requiredid (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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

GET /projects/:id/tasks

List a project's tasks

Permission
project.project or project.alltask
API key scope
projects:read

Path parameters

NameTypeDetails
id requiredid (24 hex characters)

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
statusone 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
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

GET /tasks

List your tasks

Permission
project.alltask
API key scope
projects:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
sortstringComma-separated fields; prefix with - for descending. Example: -createdAt,name
max 100 characters
fieldsstringComma-separated fields to return. Example: id,name,status
max 500 characters
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
statusone of: new, started, ongoing, in_review, completed
projectIdid (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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /tasks/:id

Get a task

Permission
project.alltask or project.project
API key scope
projects:read

Path parameters

NameTypeDetails
id requiredid (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"
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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.report or pos.sales
API key scope
reports:read

Query parameters

NameTypeDetails
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
storestring"all" or a store id (needs pos.stores). Default: your store.
max 30 characters; must be "all", "current" or a store id
groupByone 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
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /reports/top-products

Best-selling products

Permission
pos.report or pos.sales
API key scope
reports:read

Query parameters

NameTypeDetails
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
storestring"all" or a store id (needs pos.stores). Default: your store.
max 30 characters; must be "all", "current" or a store id
limitinteger
1–100; default 10
byone 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"
    }
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /reports/staff

Sales by staff member

Permission
pos.report or pos.sales
API key scope
reports:read

Query parameters

NameTypeDetails
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
storestring"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"
    }
  }
}

Status codes: 200, 400, 401, 403, 422, 429

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.admin or logs/general.activity or logs/general.logs
API key scope
admin:read

Query parameters

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–200; default 25
qstringSearch text.
max 100 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (YYYY-MM-DD)Only items on or before this date (YYYY-MM-DD, whole day included).
modulestring
max 40 characters
actionstring
max 40 characters
userIdid (24 hex characters)
resourcestring
max 60 characters
resourceIdstring
max 60 characters
statusone 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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

GET /admin/permissions

Permission catalogue

Every menu and permission key the app knows, as used by PUT /users/{id}/permissions.

Permission
admin.permission or admin.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"
      }
    }
  ]
}

Status codes: 200, 401, 403, 429

GET /admin/settings

Main settings (no secrets)

Permission
pos.setting or pos.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
    }
  }
}

Status codes: 200, 401, 403, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
unreadboolean
categorystring
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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

POST /notifications/:id/read

Mark a notification as read

Permission
Any signed-in user
API key scope
notifications:write

Path parameters

NameTypeDetails
id requiredstring
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
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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."
    }
  ]
}

Status codes: 200, 401, 403, 429

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"
    }
  ]
}

Status codes: 200, 401, 403, 429

GET /webhooks/:id

Get a webhook

Permission
pos.onlinestore
API key scope
admin:read

Path parameters

NameTypeDetails
id requiredstring
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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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)

NameTypeDetails
name requiredstring
max 100 characters
url requiredstring
max 500 characters
events requiredarray of stringEvent names from GET /event-types, or ["*"] for all events.
1–50 items
statusone of: active, inactive
default "active"
retryCountinteger
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>"
  }
}

Status codes: 201, 401, 403, 422, 429

PATCH /webhooks/:id

Change a webhook

Permission
pos.onlinestore
API key scope
admin:write

Path parameters

NameTypeDetails
id requiredstring
must be a webhook id (wh_…)

Request body (JSON)

NameTypeDetails
namestring
max 100 characters
urlstring
max 500 characters
eventsarray of stringEvent names from GET /event-types, or ["*"] for all events.
1–50 items
statusone of: active, inactive
retryCountinteger
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"
  }
}

Status codes: 200, 400, 401, 403, 404, 422, 429

DELETE /webhooks/:id

Delete a webhook

Permission
pos.onlinestore
API key scope
admin:write

Path parameters

NameTypeDetails
id requiredstring
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"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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

NameTypeDetails
id requiredstring
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": ""
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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

NameTypeDetails
id requiredstring
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>"
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
webhookIdstring
max 40 characters
eventstring
max 60 characters
statusone 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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

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

NameTypeDetails
id requiredstring
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": ""
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 404, 429

POST /webhook-deliveries/:id/retry

Send a delivery again

Permission
pos.onlinestore
API key scope
admin:write

Path parameters

NameTypeDetails
id requiredstring
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": ""
      }
    ]
  }
}

Status codes: 200, 400, 401, 403, 404, 429

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

NameTypeDetails
pageintegerPage number (starts at 1).
min 1; default 1
limitintegerItems per page (max 100).
1–100; default 25
eventstring
max 60 characters
fromdate (YYYY-MM-DD)Only items on or after this date (YYYY-MM-DD).
todate (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
  }
}

Status codes: 200, 400, 401, 403, 422, 429

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)

NameTypeDetails
question requiredstring
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"
    }
  }
}

Status codes: 200, 401, 403, 422, 429

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?"
      ]
    }
  ]
}

Status codes: 200, 401, 403, 429

Generated from the API definitions in backend/api/v1/modules and the webhook events in backend/services/webhookService.js.