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 shift1. 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=500Compact 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 untilhasMoreis false. Later syncs pass the stored cursor and receive only what changed, with removed items asdeleted: truetombstones. - Prices are for this terminal's branch, so a branch override arrives already applied.
onHandHintis advisory and may be stale. A sale is never blocked on it.GET /v1/terminal/categoriesgives 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 isfavourite), then the active categories, then Other; sort items byproductSort. 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
saleIdon 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.