Getting data in
Sync API reference
How an operator gets its already-onboarded merchants, branches and terminals into the ERP without
re-onboarding. Three routes, one engine (SyncEngine), identical rules.
Auth. An Operator API key with sync:write (create it as an operator admin: POST /v1/organizations/{operatorId}/api-keys).
Send X-Api-Key: tsk_live_… and sign every write body:
X-Tillstack-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "{t}.{raw body}" with your signing secret> (±5 min).
Humans who are operator admins can call the same endpoints without a signature. Resellers and merchants cannot sync.
Identity. Every record is keyed on your id (externalId), unique per operator. Replaying a snapshot changes and
writes nothing (unchanged). Terminals default externalId to the TID.
Bulk — PUT /v1/sync/{merchants|branches|terminals}#
Body { "items": [ … ] }, 1–500 items. Order matters across kinds: merchants → branches → terminals.
Response is 200 with per-item results; one bad item never fails the batch:
{ created, updated, unchanged, failed, items: [{ index, externalId, outcome, id, error }] }.
error is "<code>: <message>" (e.g. mid_taken, merchant_not_found, tid_taken, parent_change_unsupported).
| kind | item fields |
|---|---|
| merchants | externalId, name, mid?, slug?, resellerId?, status? — resellerId places it under one of your resellers; it cannot change later. Omitted mid on update = leave as is. |
| branches | externalId, merchantExternalId, name, code |
| terminals | externalId?, tid, serialNumber?, model?, status? (Active/Inactive/Lost), merchantExternalId?, branchExternalId? — no merchant = held unassigned by the operator. Items are full snapshots: omitting the merchant unassigns. |
Webhook — POST /v1/sync/webhooks#
{ eventId, type, occurredAt, data }, one event per call, signed like any write.
Types: merchant.created|updated, branch.created|updated, terminal.created|updated|assigned (data = the item above),
terminal.deactivated (data = { externalId }; leaves assignment alone).
200 { status }: processed · duplicate (eventId seen) · stale (we already hold something newer for that record) ·
ignored (unknown type — acknowledged so you do not retry forever).
422 = could not be applied yet (e.g. the merchant has not been synced). Failures are not recorded, so redeliver the
same eventId once fixed.
CSV — POST /v1/imports?kind=Merchants|Branches|Terminals&fileName=…#
Body is the raw CSV (Content-Type: text/csv, ≤5 MB, ≤50 000 rows). Header names are case-insensitive and ignore
spaces/underscores/hyphens. Returns 202 and a job; poll GET /v1/imports/{id} (Pending → Running → Completed|Failed)
for counts and per-line errors (line is the line in your file). GET /v1/imports lists recent jobs.
Columns — merchants: externalId, name + mid, slug, resellerId, status; branches: externalId, merchantExternalId, name, code;
terminals: tid + externalId, serialNumber, model, status, merchantExternalId, branchExternalId.
Re-uploading the same file is safe. Wrong headers are rejected immediately with 400.
Operating notes#
- Imports run on a background worker polling the
import_jobstable (Imports:PollSeconds, default 2;Imports:Enabled). Jobs are claimed with one conditional UPDATE, so several API instances can run; a job stuck "Running" >15 min is requeued. RabbitMQ is not involved yet (arrives with the outbox). - The worker runs the engine through
TenantOverrideacting as the importing operator. Nothing on a request path can set it.