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

Reference

Sandbox, OpenAPI, Postman

Sandbox#

A sandbox operator is created by platform staff: POST /v1/organizations {type:"Operator", name, slug, sandbox:true}. Everything beneath it (resellers, merchants synced in) is sandbox automatically; the flag can't be set on a live tree or removed.

  • API keys from a sandbox organization are tsk_test_…; a live key never works on a sandbox tenant and a test key never works on a live one (same 401 as a wrong key).
  • Webhook events from a sandbox carry livemode:false.
  • Sandbox data is real rows in the same database, isolated by the usual org-path scoping. Nothing in it touches real money; transactions are whatever you post.

Run the whole flow from the docs#

bash
BASE=https://<sandbox-host> API_KEY=tsk_test_... SIGNING_SECRET=... ./scripts/sandbox-flow.sh

It syncs a merchant, branch and terminal, creates a product and stock, opens a terminal session, records a card sale, posts the matching bank transaction and shows the reconciliation summary (the two pair up, zero exceptions). Set WEBHOOK_URL to also register an endpoint and watch sale.created arrive. Key scopes needed: sync:write terminals:session catalog:write inventory:write sales:read transactions:write webhooks:write. Verified live against a local API on 16 Nov 2026 (including a delivered webhook with livemode:false).

OpenAPI#

openapi/tillstack.v1.json (OpenAPI 3.1) is generated from the running API and checked in. OpenApiContractTests fails when the API's shape drifts from it. After an intentional change: UPDATE_OPENAPI=1 dotnet test --filter OpenApi, review the diff, commit. The spec includes auth schemes and the webhook events. Live copy: GET /openapi/v1.json.

Postman#

node openapi/make-postman.mjs → openapi/tillstack.postman_collection.json (92 requests, folder per controller). Import it, set baseUrl, apiKey, and signingSecret (a pre-request script then signs POST/PUT/PATCH bodies), or token for a user/terminal session. Regenerate after the spec changes; the collection is derived, never hand-edited.

Not done#

No self-serve sandbox sign-up (platform staff provision it); no sandbox reset/seed endpoint; no console screens for webhooks yet; the Postman collection has not been run in Newman against a live environment.