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#
- Develop against the sandbox with a
tsk_test_key. - Keep keys and signing secrets in a secret store, one key per integration with the fewest scopes it needs.
- Make every write retry-safe: use
externalIds,saleIds andeventIds. Retries then cost nothing. - Verify webhook signatures and make your handler idempotent on the event id.
- Watch for
warningson sale responses andfaileditems in sync responses; they are information, not errors. - Handle
409(conflict) and422(cannot succeed as sent) differently from5xx(retry).
Tools#
OpenAPI 3.1 spec · Postman collection (signs requests for you) · the sandbox-flow.sh script in the repository.