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

Getting data in

How data gets in

You do not have to re-onboard anyone. Your merchants, branches and terminals already exist in your systems; Tillstack takes them from there. There are four ways in, and they all run through the same engine with the same rules, so you can mix them freely.

Way in Best for Auth
Bulk sync API PUT /v1/sync/{merchants,branches,terminals} Loading everything the first time, and nightly snapshots API key + signature
Event webhook POST /v1/sync/webhooks Keeping Tillstack current as things change in your system API key + signature
CSV import POST /v1/imports A spreadsheet, a one-off migration, a non-technical team API key + signature
The console Adding one merchant by hand, with its owner, branch and terminals A person signed in

Sales do not come in this way: terminals send those directly (terminals). Bank records come in as transactions.

The rules that make it safe#

Your id is the key. Every record has an externalId (yours), unique per operator. Terminals default it to the TID. Sending a record that already exists updates it; sending the same data again returns unchanged and writes nothing. So a retry, a replay or a nightly snapshot never creates duplicates.

Order matters across kinds. Merchants first, then branches (which name their merchant), then terminals (which name a merchant and branch). Within one request, one bad item never fails the others: the response lists each item's outcome.

Snapshots, not patches. A terminal item is a full snapshot. Leaving out the merchant means "unassigned, in stock", not "leave as it is".

Newer wins. Events carry occurredAt. If we already hold something newer for that record, the late event is stale and ignored, so out-of-order delivery cannot roll back a change.

Bulk sync#

PUT /v1/sync/merchants
{ "items": [ { "externalId": "m-1", "name": "Mama Put Foods", "mid": "2035MID0001" } ] }

1 to 500 items per call. The response is always 200 with per-item results:

json
{ "created": 1, "updated": 0, "unchanged": 0, "failed": 0,
  "items": [ { "index": 0, "externalId": "m-1", "outcome": "Created", "id": "…" } ] }

A failed item says why in error, as "<code>: <message>", for example mid_taken, merchant_not_found, tid_taken. Fields for each kind are in the sync reference.

Webhook events from your system#

If your platform can call out when something changes, point it at us:

POST /v1/sync/webhooks
{ "eventId": "evt_123", "type": "terminal.assigned", "occurredAt": "2026-11-16T10:00:00+01:00", "data": { …the item… } }

Types: merchant.created|updated, branch.created|updated, terminal.created|updated|assigned, terminal.deactivated, transaction.created. Responses: processed, duplicate (we have seen this eventId), stale, ignored (unknown type, acknowledged so you do not retry forever). A 422 means it cannot be applied yet (for example the merchant has not arrived): redeliver the same eventId once it can.

CSV#

POST /v1/imports?kind=Terminals&fileName=terminals.csv      Content-Type: text/csv

Up to 5 MB and 50,000 rows. You get 202 and a job to poll (GET /v1/imports/{id}): Pending, Running, then Completed or Failed, with counts and a message per bad line. Headers ignore case, spaces and underscores (External ID, external_id and externalId are the same column). Re-uploading the same file is safe.

By hand, in the console#

An Operator admin (or platform staff acting for an operator) can add a merchant in a few steps: business, owner, first branch, terminals. See the Operator portal. It uses the same endpoints you can call yourself: POST /v1/organizations, POST /v1/merchants/{id}/branches, POST /v1/terminals.

What comes in after the setup#

Data From How
Catalog and stock The merchant (console, CSV import) or your system Catalog and stock
Sales, returns, shifts The terminal app Terminals
Card and transfer records Your acquirer or payment provider Payment providers
Everything that happens Out to you Webhooks