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

Sales, returns, shifts

Two front doors, one engine. A terminal uses /v1/terminal/* with its session token (merchant, branch and terminal are fixed by the token). The Operator backend or back office uses /v1/merchants/{merchantId}/*, naming the branch and (optionally) the terminal by tid. Same handlers, same rules. Money is whole kobo; prices are VAT-inclusive (a line's tax is the VAT already inside its net amount, net × 7.5 / 107.5, rounded half away from zero).

Recording a sale — POST /v1/terminal/sales · POST /v1/merchants/{id}/sales#

{ "saleId": "<uuid>", "occurredAt": "2026-11-16T10:02:11+01:00", "shiftId"?, "receiptNo"?, "cashierRef"?,
  "lines":   [{ "variantId", "quantity", "unitPriceKobo", "discountKobo"? }],
  "tenders": [{ "type": "Cash|Card|Transfer|Other", "amountKobo", "rrn"?, "stan"?, "tid"?, "maskedPan"?, "authCode"?, "reference"? }],
  "expectedTotalKobo"?, "note"? }

Optional header Idempotency-Key. Response { receipt, replayed, warnings }; the receipt is print-ready (the business's name leads; ours never appears).

  • The charged price wins. The terminal may have sold from a stale cache; we record what the customer paid and add a price_differs:SKU warning rather than refuse.
  • Tenders. cash + non-cash must cover the total. Only cash may exceed it (that is change); a card or transfer may not.
  • Idempotent by saleId. Replay → 200 with the original receipt and no second stock move or receipt number. Same id, different contents → 409 idempotency_conflict. A reused Idempotency-Key for a different sale → 409. Ten identical requests at once create one sale (the sale row is written first, so a duplicate fails before stock moves).
  • A paid sale is never refused for lack of stock. Stock may go negative; the shortfall is a warnings: ["oversold:SKU:n"] entry and an oversell alert a manager acknowledges (GET/POST …/oversells). Untracked items (services) never move stock.
  • Receipt numbers. If the device printed one offline, send it and we keep it verbatim. Otherwise we assign {TID}-{000001…}, gapless (counter in the same transaction; a rolled-back sale gives its number back).
  • Time. Send occurredAt (any offset; +01:00 is fine — stored as UTC). A device clock >5 min ahead is flagged future_clock and reported at our receive time; older than 7 days is flagged very_old. Both are still accepted.
  • Cost of goods is snapshotted per line from the ledger (the average cost the stock left at).

What gets refused, and how#

status meaning retry?
400 malformed request (bad shape, zero quantity, anything that looks like a card number) — nothing is stored fix the device
409 idempotency_conflict / idempotency_key_reused no: that id means something else
422 a business fact retrying cannot change: tender_mismatch, overpaid_non_cash, total_mismatch, discount_exceeds_price, unknown_variant, unknown_shift, terminal_branch_mismatch… no — and the submission is kept on the dead-letter list (GET …/rejections) for a manager to see and resolve
5xx ours yes, with the same ids

Card data: never send a card number. maskedPan may show at most the first six and last four digits; free-text fields are scanned (Luhn) and refused. A refused number is never persisted — not even in the dead-letter payload.

Returns — POST …/sales/{saleId}/returns#

{ returnId, occurredAt, reason?, lines:[{ saleLineId, quantity, restock? }], refunds:[{ type, amountKobo, rrn?, reference? }] } The refund is computed here, not trusted: each line refunds its share of what was actually paid (discount and VAT in proportion) as a cumulative figure, so three partial returns of an awkward amount sum to exactly the line (299 kobo → 100 + 99 + 100). Refunds must be paid out in full, and card/transfer money can only go back as far as it came in (net of earlier refunds); cash is always allowed. restock (default true) puts stock back at the cost it left with, so the average does not move; restock:false is a write-off. Idempotent by returnId; concurrent returns of the same line cannot over-return (the sale's xmin serialises them).

Shifts — POST /v1/terminal/shifts · …/{id}/close#

One open shift per terminal, enforced by a partial unique index. Open/close are idempotent by shiftId. Expected cash = opening float + cash taken − change given − cash refunds; closing records counted − expected as the variance. A sale joins the shift open at its occurredAt (or the one it names), even if it syncs after that shift closed; sales outside any shift are simply unattributed. Cash that arrives after close is reported as lateCashKobo, never folded into the closed figures. A manager can close a lost terminal's shift: POST …/shifts/{id}/close.

Z report — GET …/reports/z · GET /v1/terminal/shifts/{id}/report#

For a shiftId, or a window (date=YYYY-MM-DD in Nigerian time, or from/to, ≤31 days; default today), optionally narrowed to branchId/terminalId. Gross, discounts, net, VAT, returns, net after returns, per-tender sales/refunds/net (cash net of change), the drawer reconciliation, the shifts involved, open oversell alerts and flagged sales.

Not here yet#

Matching card/transfer tenders to the acquirer's transactions (Phase 5 uses the stored rrn/stan/tid); sale-level (basket) discounts; voiding an unpaid sale; cash pay-ins/pay-outs mid-shift; the sale.created webhook (Phase 7 outbox).