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

Terminal integration

The terminal app is yours. It talks to Tillstack over HTTPS with a short session token, and Tillstack is shaped for small screens and flaky networks. The whole flow:

your backend: mint a session  ->  device: sync catalog  ->  open shift  ->  sell (cache first)  ->  close shift

1. Mint a session#

Your backend asks for a short-lived token for one terminal (authentication). The device never holds an API key.

2. Sync the catalog#

GET /v1/terminal/catalog?cursor=<cursor>&limit=500

Compact items for a small screen: variantId, productId, name, variantName, sku, barcode, priceKobo, taxRateBp, unit, trackStock, categoryId, onHandHint, deleted, imageId, productSort, favourite.

  • First call: no cursor, active items only. Keep the returned cursor, and pass it back until hasMore is false. Later syncs pass the stored cursor and receive only what changed, with removed items as deleted: true tombstones.
  • Prices are for this terminal's branch, so a branch override arrives already applied.
  • onHandHint is advisory and may be stale. A sale is never blocked on it.
  • GET /v1/terminal/categories gives the tabs in the order the shop wants, with optional colours. It is small, so fetch it on every sync. Build the screen as a Favourites tab first (if any item is favourite), then the active categories, then Other; sort items by productSort. See catalog layout.
  • GET /v1/terminal/lookup?barcode=… resolves one scan the local cache missed.
  • Pictures: GET /v1/images/{imageId}?w=200&h=200&fit=cover&fmt=webp. No auth header, cached for a year, and a changed picture gets a new id. See product pictures.

3. Open a shift#

POST /v1/terminal/shifts   { "shiftId": "<uuid>", "openedAt": "…", "openingFloatKobo": 50000, "cashierRef": "ada" }

One open shift per terminal. At close you send the counted cash and get the variance.

4. Sell#

POST /v1/terminal/sales
Idempotency-Key: <optional>
{ "saleId": "<uuid>", "occurredAt": "…", "shiftId": "…", "lines": [ … ], "tenders": [ … ] }
  • Generate saleId on the device. Replaying the same sale returns the same receipt and moves stock once.
  • The charged price wins. If the cache was stale, we record what the customer paid and add a warning.
  • A paid sale is never refused for lack of stock. Stock may go negative; the manager sees an oversell alert.
  • The response includes a print-ready receipt, with the business's name, address, phone, tax ID and footer.
  • Returns: POST /v1/terminal/sales/{id}/returns.

Full detail and the error cases: sales, returns and shifts.

5. Working offline#

Queue sales on the device and replay them in occurredAt order when the network returns. Send the receipt number you printed, if any, and we keep it. A sale refused for a permanent reason (unknown variant, wrong branch) returns 422 and is kept in a refused submissions list a manager can review, so the device can drop it instead of retrying forever. A device clock more than five minutes ahead is flagged but still accepted.

6. Receipts and the card tender#

Put the payment provider's data on the card tender so reconciliation can match it: rrn, stan, tid, maskedPan (first 6 and last 4 at most), authCode. Never send a full card number: it is refused.