Building on it
Catalog and stock
A merchant's catalog is products with one or more variants (the sellable unit: a SKU, a price, an optional barcode). Stock is tracked per variant per branch in an append-only ledger, so every number can be explained.
Products and variants#
POST /v1/merchants/{id}/products
{ "name": "Zobo Drink", "categoryId": "…", "unit": "bottle", "taxClass": "Standard", "trackStock": true,
"variants": [ { "sku": "ZOBO-S", "name": "Small", "barcode": "6150001", "priceKobo": 30000, "costKobo": 18000 } ] }SKUs and barcodes are unique per merchant, never globally. Branch prices: PUT /v1/merchants/{id}/variants/{variantId}/prices/{branchId}. Categories, ordering and favourites
(how items are arranged on a terminal): catalog layout. Pictures: product pictures.
Loading many products#
POST /v1/merchants/{id}/products/import takes CSV text and a dryRun flag:
{ "csv": "name,sku,price,cost,category\nPalm Oil 1L,OIL-1L,2500,1800,Groceries\n", "dryRun": true }Columns: name, sku, price (naira; ₦1,250.50 is fine) are required; cost, barcode, category (created if new), unit, tax, variant, favourite are optional. The response says
how many products would be created, updated, unchanged or failed, with a reason per failed row. Run it with dryRun: false to apply. Rows that fail are skipped and the rest go in.
An existing SKU is updated, never duplicated, so the way to fix a file is to correct it and import again. Rows sharing a product name with new SKUs become the variants of one product.
Up to 2,000 rows a time.
Stock#
| Do | Call |
|---|---|
| Receive a delivery | POST /v1/merchants/{id}/inventory/receipts |
| Adjust (loss, found, correction) | POST /v1/merchants/{id}/inventory/adjustments |
| Move stock between branches | POST …/inventory/transfers, then …/transfers/{id}/receive (or /cancel) |
| Stock-take | POST …/inventory/counts, PUT …/counts/{id}/lines, POST …/counts/{id}/post |
| What is on hand | GET …/inventory/levels |
| The trail | GET …/inventory/movements |
| What it is worth | GET …/inventory/valuation (weighted-average cost) |
A stock count shows the system figure, what was counted and the difference per item, and posting it adjusts stock to match. Items not counted are left alone.
Sales reduce stock automatically. A paid sale is never blocked by an empty shelf: stock may go negative and an oversell alert is raised for a manager. Details and ledger rules: catalog and inventory.