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

Errors and limits

Error shape#

Failures are application/problem+json with a stable code you can switch on:

json
{ "title": "SKU 'RICE-5' is invalid (letters, digits and . _ - /, max 40).", "status": 400, "code": "validation" }
Status code Meaning Retry?
400 validation The request is wrong. The title says how. No: fix it
401 unauthorized No or bad credential, wrong signature, or a stale timestamp No: fix the credential
403 forbidden Valid credential, not allowed to do that No
404 not_found Not found, or outside your tenant (the two look identical on purpose) No
409 conflict Already exists, or an idempotency key was reused for different content No
422 unprocessable Cannot succeed as sent (for example a sale line for an unknown item). Kept for review where relevant No
503 unavailable A feature isn't set up on this server (for example picture storage) Later
5xx Our side Yes, with backoff

Retrying safely#

Everything that creates something is idempotent by an id you choose (externalId, saleId, eventId, Idempotency-Key). Retry any request that timed out or returned 5xx with the same id and body. For sales, the same saleId with different contents is 409, never a silent overwrite.

Conventions#

  • Money: integer kobo. Quantities: decimals with up to three places.
  • Time: ISO 8601 with an offset. We store UTC and report in Nigerian time where a "day" matters.
  • Pagination: page (from 1) and pageSize (up to 200). Lists return { items, pageNumber, pageSize, total }. Catalog and sync feeds use a cursor instead.
  • Enums are strings ("Completed", "Card").
  • Unknown fields in a request are ignored; do not rely on that.

Limits#

Sync batch 500 items
Transactions batch 500 items
CSV import (sync kinds) 5 MB, 50,000 rows
Product import 5 MB, 2,000 rows
Product picture 6 MB, 8,000 px a side
Network report range 93 days
Webhook endpoints 10 per organisation
Signature clock skew 5 minutes

There are no published request-rate limits yet. Be considerate: batch where batches exist, and back off on 5xx. If you plan sustained high volume, tell us so we can size for it.