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

Running without our UI

You can use Tillstack with none of our screens: your own web app, a mobile app, scripts, or another system's admin. Everything the console does is an API call, and the API reference is generated from the running API, so it never drifts.

What the console does, as calls#

In the console API
Add a merchant POST /v1/organizations {type:"Merchant", parentId, name, slug, mid} (or sync)
Add an owner POST /v1/organizations/{id}/users {email, fullName, role:"Owner", invite:true} (emails a link; no password is shared)
Add a branch POST /v1/merchants/{id}/branches {name, code}
Register / assign a terminal POST /v1/terminals, PUT /v1/terminals/{id} {assignment:"assign", merchantId, branchId}
Staff: change role, switch off, reset password PUT /v1/organizations/{id}/users/{userId}, POST …/users/{userId}/password
Business details, receipt footer GET/PUT /v1/organizations/{id}/profile
Add products, import a CSV POST /v1/merchants/{id}/products, …/products/import
Product picture POST /v1/merchants/{id}/products/{productId}/image (multipart)
Receive, adjust, transfer, count stock catalog and stock
Sales, receipts sales
Reports reports
Branding and your own domain PUT /v1/organizations/{id}/branding, POST /v1/organizations/{id}/domains
Webhooks POST /v1/organizations/{id}/webhooks (webhooks)
API keys POST /v1/organizations/{id}/api-keys

Signing people in from your own UI#

Use POST /v1/auth/login and /v1/auth/refresh (authentication). Roles are enforced by the API, not the screen: a cashier's token cannot edit the catalog whatever your UI shows. Hide what a role cannot use, but never rely on hiding.

Cross-origin calls from a browser#

A web app on your own domain can call the API from the browser. The API allows the origins of your registered custom domains (and nothing else). Server-to-server calls need no CORS. Do not put an API key or signing secret in browser code: keep those on your server.

A checklist for going live#

  1. Develop against the sandbox with a tsk_test_ key.
  2. Keep keys and signing secrets in a secret store, one key per integration with the fewest scopes it needs.
  3. Make every write retry-safe: use externalIds, saleIds and eventIds. Retries then cost nothing.
  4. Verify webhook signatures and make your handler idempotent on the event id.
  5. Watch for warnings on sale responses and failed items in sync responses; they are information, not errors.
  6. Handle 409 (conflict) and 422 (cannot succeed as sent) differently from 5xx (retry).

Tools#

OpenAPI 3.1 spec · Postman collection (signs requests for you) · the sandbox-flow.sh script in the repository.