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

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_jobs table (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 TenantOverride acting as the importing operator. Nothing on a request path can set it.