Guides

Start here

What Tillstack isQuickstartAuthentication

Getting data in

How data gets inSync API referenceYour payment providerReconciliation

Building on it

Terminal integrationSales, returns, shiftsCatalog and stockInventory ledgerCatalog layout on devicesProduct picturesReportsWebhooksEmail and EngageRunning without our UI

Using the console

Operator portalMerchant guide

Reference

Sandbox, OpenAPI, PostmanErrors and limitsSecurity

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:

json
{ "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.