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

Inventory ledger

All routes are under /v1/merchants/{merchantId} and resolve the merchant through the caller's scope: a merchant outside the caller's subtree is a 404. Humans act by role (read: every role; write catalog/stock: Admin, Owner, Manager, Stockkeeper); API keys need catalog:read|write, inventory:read|write. Money is whole kobo (long); quantities are decimals with up to 3 places.

Catalog#

  • Product (name, unit, taxClass Standard=7.5% VAT / Exempt / ZeroRated, trackStock) → Variants (the sellable unit: sku, barcode?, priceKobo, costKobo?). A simple product has one variant. SKU (stored uppercase) and barcode are unique per merchant; the same values at another merchant are fine. Items are deactivated, never deleted (sales history).
  • PUT …/variants/{id}/prices/{branchId} sets a per-branch price; DELETE removes it.
  • GET …/products?q= matches a name fragment, an exact SKU or an exact barcode. GET …/lookup?barcode= resolves one scan.

Delta feed — GET …/catalog?branchId=&cursor=&limit=#

Keyset feed ordered by (updatedAt, id); the cursor is opaque, keep what you are given. First call has no cursor and returns active items only; keep calling with the returned cursor while hasMore. Later calls return only what changed, and anything deactivated arrives as deleted: true. An unchanged feed hands the same cursor back. Prices are resolved for branchId; onHandHint is advisory (it does not bump the feed — refresh it with the stock endpoint). (The plan said ETag; a cursor is strictly better for paging a delta.)

Terminal profile — /v1/terminal/* (terminal session token only)#

Merchant and branch come from the token, never the URL. GET catalog (same feed, lean fields: no cost/description/admin flags), GET lookup?barcode=, GET stock/{variantId}. A terminal token is refused everywhere else, and humans/keys are refused here.

Inventory — the ledger#

StockMovement is append-only (a database trigger rejects UPDATE/DELETE); a StockLevel is a cache of it. Every change goes through IStockLedger, which per movement runs ONE atomic UPDATE … SET "OnHand" = "OnHand" + @qty … RETURNING (row-locked, so concurrent callers queue and no update is lost), computes the weighted-average cost in the same statement, and appends the ledger row with the returned balanceAfter in the same transaction. Invariant, asserted in tests: OnHand == SUM(Qty).

  • Batches are all-or-nothing and applied in a fixed (variant, branch) order, so opposite-order batches cannot deadlock.
  • Removing stock below zero is refused (409 insufficient_stock) except for paid sales (Phase 4) and physical counts, where the goods/the count are the truth; those may go negative and are valued at zero (shown as negativeUnits).
  • Average cost: receipts at cost c → (onHand·avg + qty·c)/(onHand+qty); if on-hand was ≤ 0 the average restarts at c; outgoing stock leaves at the current average and never changes it; a receipt with no stated cost uses the variant's default cost.
endpoint notes
POST inventory/receipts lines {variantId, quantity>0, unitCostKobo?}; one variant once per receipt
POST inventory/adjustments signed quantityDelta; a note is required when removing
PUT inventory/reorder-levels per branch+variant; drives levels?lowOnly=true
GET inventory/levels · movements · valuation paged; valuation = Σ round(onHand×avg) per branch, detail=true for lines
POST inventory/transfers → /{id}/receive | /cancel send removes stock from the source immediately (in transit); receive may record a shortfall (quantityReceived < sent); cancel returns it. The destination's average moves by what arrived, at the cost it left with
POST inventory/counts → /{id}/lines → /post | /cancel snapshot expected qty, record counted, post applies counted − expected as a delta so sales during the count survive; uncounted lines are untouched

Transfers and counts are state machines guarded by Postgres xmin as an optimistic-concurrency token: of N concurrent receivers/posters exactly one wins (the status change is saved before any stock moves), the rest get 409.

Not here yet#

Sales and returns (Phase 4) will call the ledger with Reason=Sale/Return, AllowNegative=true. No purchasing/suppliers, no variant-level units of measure conversions, no serial/lot tracking, no stock.low webhook (Phase 7 outbox).