API Endpoints

All endpoints are relative to the base URL https://app.sabibooks.app/api/v1/. Unless marked as public, every endpoint requires a valid Bearer token in the Authorization header.

Interactive API Explorer (Swagger UI) Try out endpoints directly in your browser with the full OpenAPI documentation.

Tip

Swagger UI is the best way to explore the API interactively. You can authorise with your Bearer token and execute requests directly from the browser.

Endpoint Groups

Auth

Public — Registration, login, OTP verification, and token refresh.

POST /auth/register
POST /auth/login
POST /auth/verify-otp
POST /auth/refresh

Business

Manage business profile, branches, staff members, and subscription details.

GET    /businesses/me
PUT    /businesses/me
POST   /businesses/branches
GET    /businesses/staff

Products

Full inventory management — create, update, search products, manage categories, and track stock levels.

GET    /products
POST   /products
PUT    /products/{id}
GET    /products/categories
POST   /products/stock-adjustment

Sales

Point-of-sale operations — create sales, process payments, generate receipts, and view sales history.

POST   /sales
GET    /sales
GET    /sales/{id}
GET    /sales/{id}/receipt
POST   /sales/{id}/void

Customers

Customer database management — create and search customers, view purchase history.

GET    /customers
POST   /customers
PUT    /customers/{id}
GET    /customers/{id}/transactions

Credit

Credit account management — track credit sales, record payments, and view aging reports.

GET    /customers/{id}/credit
POST   /customers/{id}/credit/payment
GET    /credit/aging-report

Expenses

Expense recording — log business expenses, categorise them, and track spending.

GET    /expenses
POST   /expenses
GET    /expenses/categories
GET    /expenses/summary

Reports

Business analytics — dashboard metrics, profit/loss, inventory valuation, exports, the Top Services breakdown (Business/Pro plans), and the Loan Readiness Pack.

GET    /reports/dashboard
GET    /reports/profit-loss
GET    /reports/inventory
GET    /reports/sales/export
GET    /reports/profit-loss/export
GET    /reports/inventory/export
GET    /reports/cash-flow/export
GET    /reports/dashboard/top-services
GET    /reports/loan-pack
POST   /reports/loan-pack
POST   /reports/loan-pack/{reference}/checkout
POST   /reports/loan-pack/payment/verify
GET    /reports/loan-pack/{reference}/download

Partner

Partner integration endpoints — merchant management, aggregated analytics, and white-label configuration. Requires partner API key.

GET    /partner/merchants
GET    /partner/merchants/{id}
GET    /partner/analytics
PUT    /partner/branding

Notifications

Notification delivery — SMS alerts, WhatsApp messages, and push notification preferences.

POST   /notifications/sms
POST   /notifications/whatsapp
GET    /notifications/preferences
PUT    /notifications/preferences

Authentication Requirements

Group	Auth Required	Notes
Auth	No	Public endpoints for registration and login
Business	Yes	Bearer JWT — scoped to authenticated user’s business
Products	Yes	Bearer JWT — scoped to authenticated user’s business
Sales	Yes	Bearer JWT — scoped to authenticated user’s business
Customers	Yes	Bearer JWT — scoped to authenticated user’s business
Credit	Yes	Bearer JWT — scoped to authenticated user’s business
Expenses	Yes	Bearer JWT — scoped to authenticated user’s business
Reports	Yes	Bearer JWT — scoped to authenticated user’s business
Partner	Yes	Partner API key — scoped to partner’s merchant network
Notifications	Yes	Bearer JWT — scoped to authenticated user’s business

Note

All authenticated endpoints are scoped to the user’s business_id from the JWT token. You can only access data belonging to your own business. Partner endpoints use a separate API key authentication and can access aggregated data across their merchant network.

Plan-Gated Endpoints

Some endpoints and actions depend on the business’s subscription plan. When a caller’s plan does not include a feature or has reached a limit, the API responds with 402 Payment Required (rather than 403), carrying a machine-readable error code that identifies the specific gate. Branch on the error code, not just the status:

Endpoint / action	Error code	Gate
GET /reports/dashboard/top-services	FEATURE_NOT_AVAILABLE	Business and Pro plans only
GET /reports/loan-pack/{reference}/download	LOAN_PACK_PAYMENT_REQUIRED	On Free/Starter, requires a completed one-time payment for that pack
POST /sales	PLAN_LIMIT_EXCEEDED	Free plan is capped at 50 sales per month

Clients should treat a 402 as a prompt to upgrade the plan (or complete a one-time purchase), not as an authentication failure. See Plans and Billing for the merchant-facing view.

Common Query Parameters

Most list endpoints support these parameters:

Parameter	Type	Default	Description
cursor	string	—	Pagination cursor from previous response
limit	integer	20	Items per page (max 100)
search	string	—	Full-text search across relevant fields
sort_by	string	created_at	Field to sort by
sort_dir	string	desc	Sort direction (asc or desc)
start_date	string	—	Filter from date (ISO 8601)
end_date	string	—	Filter to date (ISO 8601)

Quick Example

List products with search and pagination:

curl -X GET "https://app.sabibooks.app/api/v1/products?search=milk&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

{
  "success": true,
  "message": "Products retrieved successfully",
  "data": {
    "content": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Peak Milk 400g",
        "sku": "PMK-400",
        "price": 1250.00,
        "quantity": 48,
        "category": "Provisions"
      }
    ],
    "cursor": "eyJpZCI6ImE1YjZjN2Q4In0=",
    "has_next": false,
    "limit": 10
  },
  "timestamp": "2026-02-20T14:22:08Z"
}