Tactill API v0 (v0)

The Tactill API is an HTTP REST API for POS, catalog, sales, and inventory automation. It uses predictable resource URLs, standard HTTP status codes, and JSON in both request and response bodies.

Most actions in the Tactill Backoffice are exposed through this API so that you can automate any workflow you need. This reference documents every public resource currently shipped on v0.

Use any HTTP client in your language of choice, or the Tactill TypeScript SDK published on npm as @tactill/api-v5.

Make your first call in 30 seconds. Replace sk_test_… with a key issued from the Tactill Backoffice.

curl https://api.tactill.com/pos/v0/products \
  -H "X-Api-Key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx"

The response is a JSON object with items and a next_token for pagination. From here:

1. Authenticate every request with your X-Api-Key header — see Authentication.
2. Pick an environment — test keys hit test data, live keys hit live data. See Environments.
3. Paginate list endpoints with next_token until it is null. See Pagination.
4. Handle errors with the standard envelope. See Errors.

Tactill uses API keys. Each key is scoped to a single organization and grants the permissions configured at issue time.

Send your key in the X-Api-Key header on every request:

X-Api-Key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Keys are secrets. Never embed them in client-side code, mobile apps, or commit them to source control. If a key leaks, revoke it from the Backoffice and issue a new one — old keys are invalidated immediately.

Each key carries one or more scopes in the form <domain>:<read|write>. Available domains:

catalog, customer, inventory, sale, payment, cashbook

A :write scope automatically grants :read on the same domain. Calling an endpoint without the required scope returns 403 Forbidden.

Every resource lives in either test or live mode. The mode is bound to the API key — it is not a request-body parameter.

• A test key reads and writes test data only; live data is invisible to it.
• A live key reads and writes live data only; test data is invisible to it.

Switching environments means switching keys. Contact hello@tactill.com to provision a test key alongside your live key.

Each resource response carries a test boolean so you can confirm which environment a record belongs to.

Used consistently across every endpoint:

List endpoints are token-paginated. Responses include:

{
  "items": [ /* up to N records */ ],
  "next_token": "eyJpZCI6ICIuLi4ifQ=="
}

To fetch the next page, pass next_token back as a query parameter:

curl "https://api.tactill.com/pos/v0/products?next_token=eyJpZCI6..." \
  -H "X-Api-Key: sk_test_xxxxxxxxxxxx"

When next_token is null you have reached the last page. Never assume a single call returns every record — always loop until next_token is null.

Every error response uses the same envelope:

{
  "status_code": 404,
  "error": "Not Found",
  "message": "product id does not exist"
}

The error field is always Title Case and matches the HTTP reason phrase.

Your client must tolerate additional fields on the envelope. Diagnostic fields may be added without bumping the API version.

Limits are applied per organization. Sandbox keys are limited to 3000 non-GET requests per 10 minutes. Live limits are sized for typical business workloads.

Every response carries:

• X-RateLimit-Limit — the cap for the current window.
• X-RateLimit-Remaining — requests remaining in the current window.
• X-RateLimit-Retry-After — UTC timestamp of the next reset, present only when the limit is hit.

When the limit is exceeded the response is 429 Too Many Requests. Retry no earlier than X-RateLimit-Retry-After, with jitter.

Rules that keep an integration healthy:

• Pin the version in your base URL — always /pos/v0/… (or future /pos/vN/…). Never call the API without an explicit version segment.
• Idempotency — GET retries are always safe. For mutations, design your callers to deduplicate by your own external reference rather than relying on retries.
• Pagination — never assume a list endpoint returns every record in one call. Loop on next_token.
• Backoff — on 429 and 5xx, retry with exponential backoff and jitter. Respect X-RateLimit-Retry-After when present.
• Environment binding — mirror the test/live split in your own configuration. Never share a single key across environments.
• Forward-compat — tolerate unknown fields in responses. We may add fields without a version bump.

URI versioning: every endpoint is prefixed with /pos/v<N>/.

v0 is live and additive-only. Partners can rely on:

• No existing field will be removed or renamed.
• No required request field will be added.
• HTTP status semantics will not change for existing endpoints.

Non-breaking additions (new optional fields, new endpoints) ship on v0 without a version bump.

When a breaking change is required it ships as v1 alongside v0:

1. New routes are mounted under /pos/v1/…. Both v0 and v1 are served by the same backend.
2. v0 enters a 6-month deprecation window with a Sunset HTTP header on every response.
3. After sunset, v0 is retired.

The @tactill/api-v5 npm package tracks the latest stable version. A new major (@tactill/api-v5@2) is published when v1 ships.

Tactill publishes an official TypeScript SDK on npm as @tactill/api-v5. It is generated from this OpenAPI document and tracks every release.

npm install @tactill/api-v5

No SDK is required — every endpoint is reachable from any HTTP client.

A Postman collection is generated from this OpenAPI document and ships with each release.

Download: Tactill API Postman Collection

To request access, provision a test key, or discuss an integration, contact hello@tactill.com.

Products are the items sold from the cash register. Each product belongs to a category, has an associated tax rate, and may carry options, tags, custom fields, and variations.

Environment: bound to the API key's mode (test vs production); test and production data are not visible across modes.

• buy_price, sell_price — integer minor units (cents). 1200 is €12.00.
• category and tax — references to existing resources; both are required at creation.
• tags, options, custom_fields — arrays of references; each can also be detached individually via the nested DELETE routes.
• variations — managed through dedicated PATCH /product/:id/variation/... routes; price adjustments are applied per variation, not on the parent product.

• catalog:read — GET /product/:id, POST /product/request.
• catalog:write — POST /product, PATCH /product, DELETE /product/:id, all nested detach and variation routes.

• A product cannot be deleted while it is referenced by one or more packs. Detach or delete the parent packs first.
• Detaching a tag, option, or custom field uses dedicated routes:
  • DELETE /product/:id/tag/:tagId
  • DELETE /product/:id/option/:optionId
  • DELETE /product/:id/custom-field/:customFieldId
• Variation updates target a single variation by name:
  • PATCH /product/:id/variation/:variationName
  • PATCH /product/:id/variation/:variationName/option/:optionValue

Product Variants are the concrete sellable forms of a product (a specific size/colour/flavour combination). A variant carries its own pricing, barcode, and stock-keeping fields while inheriting the catalog metadata of its parent product.

Environment: bound to the API key's mode (test vs production); test and production data are not visible across modes.

• buy_price, sell_price — integer minor units (cents).
• Variant routes are addressed by composite path :productId/:variantId, not under /product/:id/....

• catalog:read — GET /productvariant/:productId/:variantId.
• catalog:write — POST /productvariant, PATCH /productvariant, DELETE /productvariant/:productId/:variantId.

• A variant cannot be deleted while it is referenced by an open sale, a pack variation, or any other active record. Detach the references first.

Packs are bundles of products sold as a single line item. A pack groups one or more product variations with quantities and per-variation price adjustments — typical use cases are menus, kits, or combo offers.

Environment: bound to the API key's mode (test vs production); test and production data are not visible across modes.

• sell_price — integer minor units (cents). The pack's sell_price overrides the sum of its components' prices on the line item.
• pack_variations[].options[].additional_price — integer minor units (cents); fine adjustments per included variation.
• custom_fields — arrays of { custom_field_id, value }; values are typed by the referenced custom field (TEXT, NUMBER, or BOOLEAN).

• catalog:read — GET /pack/:id, POST /pack/request.
• catalog:write — POST /pack, PATCH /pack, DELETE /pack/:id, DELETE /pack/:id/custom-field/:customFieldId.

• A product referenced by a pack cannot be deleted until the pack is removed or the reference is dropped (see Product).
• Detaching a single custom field from a pack uses DELETE /pack/:id/custom-field/:customFieldId; the custom-field definition is not deleted.