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.

Step 1 — Get your JWT and companyID. Log in to v5.tactill.com, open your browser DevTools (F12) → Network, filter on graphql, and click any request:

• Request URL — the GraphQL endpoint (copy it; the production value is the one used below).
• Request Headers → Authorization — your JWT (starts with eyJ…; short-lived, so re-copy it if you get a 401).
• Payload — the companyID variable is your company identifier.

Step 2 — Create the key. Replace $JWT and YOUR_COMPANY_ID, then run:

curl -X POST https://uc3tlcffqnbtfet5fle7rjy3mm.appsync-api.eu-west-1.amazonaws.com/graphql \
  -H "Authorization: $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Create($input: CreateExternalApiCredentialInput!) { createExternalApiCredential(input: $input) { rawKey externalApiCredential { id label scopes test } } }",
    "variables": { "input": {
      "companyID": "YOUR_COMPANY_ID",
      "label": "My integration (test)",
      "test": true,
      "scopes": ["catalog:read", "catalog:write", "sale:read"]
    }}
  }'

• test: true issues an sk_test_… key; test: false issues an sk_live_… key. This field is required.
• scopes — request only what you need (:write implies :read). Every available scope, for easy copy-paste:

["catalog:read","catalog:write","settings:read","settings:write","customer:read","customer:write","inventory:read","inventory:write","sale:read","sale:write","payment:read","payment:write","cashbook:read","cashbook:write"]

Step 3 — Save rawKey. The response contains rawKey (e.g. sk_test_…). It is returned once and never stored — copy it into your secrets manager immediately, then send it as your X-Api-Key. Prefer a GUI? Download the Postman collection to explore every REST endpoint once you have a key.

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 still evolving. It is not frozen: fields can be removed or renamed, request shapes can change, and endpoints can gain required fields.

What we commit to instead:

• Every change is written up in the changelog, with the action it requires from you.
• Breaking changes are announced before they reach production, not after.
• We coordinate directly with each integration currently in build.

Pin the behaviour you depend on with contract tests rather than assuming a field will outlive a release, and read the changelog before upgrading.

Breaking changes ship on v0. Deliberately: while the API is young, correcting a wrong contract is worth more than preserving it.

A future v1 will be introduced once the surface is stable and integrations are numerous enough that coordinating a change one-to-one stops being realistic. At that point v0 gets a deprecation window and a Sunset header on every response. That has not happened yet.

The @tactill/api-v5 npm package tracks the latest release.

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.

Filters describe how searching works. Every POST /<resource>/request endpoint takes the same envelope, so once you can search one resource you can search all of them. Which fields a given resource accepts is listed in that resource's own request schema.

{
  "filter": { "name": { "contains": "shorts" } },
  "sort":   { "field": "created_at", "direction": "desc" },
  "limit":  20,
  "next_token": null
}

Every key is optional. Omit filter to retrieve everything.

Each criterion is an object keyed by operator, never a bare value. {"name": "shorts"} is rejected; {"name": {"eq": "shorts"}} is correct.

• Text — eq, ne, contains, not_contains, starts_with, ends_with, regexp, lt, lte, gt, gte, exists
• Dates — eq, ne, lt, lte, gt, gte, exists. ISO 8601, e.g. 2024-01-31T23:59:59Z
• Numbers — eq, ne, lt, lte, gt, gte, exists. Amounts are integers in minor units; see currency_decimals on the company
• Booleans — eq, ne, exists
• Identifiers — eq, ne, exists
• Enumerations — eq, ne, exists, with the accepted values listed on the resource

Several criteria in one object are combined with AND:

{ "filter": { "state": { "eq": "CLOSED" }, "total": { "gte": 1000 } } }

and, or and not take plain filters:

{
  "filter": {
    "state": { "eq": "CLOSED" },
    "or": [
      { "total": { "gte": 10000 } },
      { "source_name": { "contains": "web" } }
    ]
  }
}

and — every criterion must match

Redundant at the top level, since criteria there already AND together. It earns its place when you need two conditions on the same field:

{
  "filter": {
    "and": [
      { "created_at": { "gte": "2024-06-01T00:00:00Z" } },
      { "created_at": { "lt": "2024-07-01T00:00:00Z" } }
    ]
  }
}

or — at least one criterion must match

{
  "filter": {
    "or": [
      { "state": { "eq": "CLOSED" } },
      { "state": { "eq": "PENDING" } }
    ]
  }
}

not — the criterion must not match

{
  "filter": {
    "not": { "source_name": { "contains": "test" } }
  }
}

Combining them

Operators sit alongside ordinary criteria, and everything at the same level ANDs together. Read the example below as: closed and (over 100.00 € or from the web) and not a test source.

{
  "filter": {
    "state": { "eq": "CLOSED" },
    "or": [
      { "total": { "gte": 10000 } },
      { "source_name": { "contains": "web" } }
    ],
    "not": { "source_name": { "contains": "test" } }
  }
}

Combination is one level deep. The filters inside and, or and not are plain criteria — they cannot themselves contain and, or or not. A nested combination is rejected with 400. This is a deliberate limit: it keeps every filterable field visible in this documentation and in the generated SDK. If your query genuinely needs deeper nesting, tell us what you are trying to express.

Sending a field the resource does not accept returns 400 Bad Request. A misspelled criterion is reported rather than ignored, so a filter can never silently widen your result set.

Sales closed in January over 100.00 €, most recent first:

{
  "filter": {
    "state": { "eq": "CLOSED" },
    "closed_at": { "gte": "2024-01-01T00:00:00Z", "lte": "2024-01-31T23:59:59Z" },
    "total": { "gte": 10000 }
  },
  "sort": { "field": "closed_at", "direction": "desc" },
  "limit": 50
}

Products in one of two categories, excluding a tag:

{
  "filter": {
    "or": [
      { "category_id": { "eq": "ea9f3f98-6f35-41e3-8c47-92fc313be733" } },
      { "category_id": { "eq": "7c1b0a52-3f19-4f0e-9a44-1d3e5c8b7a20" } }
    ],
    "not": { "name": { "contains": "sample" } }
  }
}

Customers with an email recorded, created this year:

{
  "filter": {
    "email": { "exists": true },
    "created_at": { "gte": "2024-01-01T00:00:00Z" }
  }
}

Walking every page:

{ "filter": { "state": { "eq": "CLOSED" } }, "limit": 100 }

Repeat with next_token set to the value from the previous response until it comes back null. total stays constant across pages — it counts everything matching the filter, not the page.

• {"name": "shorts"} — a criterion is always an object: {"name": {"eq": "shorts"}}.
• Nesting a combination inside and / or / not. One level only.
• Filtering on a field the resource does not expose. Check the request schema; unknown criteria return 400.
• Assuming amounts are decimal. They are integers in minor units — 10000 is 100.00 € when currency_decimals is 2.

sort takes one field from the resource's sortable list, with direction set to asc or desc (default asc).

limit caps the page at 1 to 100 items. Responses carry items, total — the number of records matching your filter, not the page size — and next_token. Pass next_token back to fetch the next page; null means there are no more.

Account exposes the API key you are calling with, and the company it belongs to. It is the entry point of any integration: call it first to discover your company_id and confirm which permissions and mode your key actually has.

Environment: the endpoint itself is mode-agnostic — it describes the key, and reports the mode in the test field.

• id — identifier of the API key itself, not of the company or of a user.
• company_id — the company every other endpoint operates on. It is derived from the key, never sent by the client.
• scopes — permissions granted when the key was issued. A :write scope implies the matching :read.
• status — active. A revoked key never authenticates, so no other value is observable here.
• test — true for sk_test_ keys, false for sk_live_ keys. The mode is fixed at issuance and cannot be switched per request.

None. Every authenticated key can read its own identity, whatever its scopes — otherwise a key could not discover what it is allowed to do.

• This resource exposes GET /me only. The key is read-only through the API: issuing, rotating and revoking keys happen in the back office.
• The secret itself is never returned, by this or any other endpoint. It is shown once, at issuance. A lost key must be rotated.

Company is the account every other resource belongs to. Read it once at start-up to learn how to format amounts: every monetary value in the API is an integer in minor units, and currency_decimals tells you where the decimal point goes.

Environment: the company is shared between test and production modes — it is not duplicated per mode.

• currency / currency_decimals — 1050 with currency_decimals: 2 is 10.50 EUR. Some currencies use 0 decimals, in which case 1050 is 1050.
• locale — drives formatting and the language of printed documents.
• name — the trading name. Registered legal names live on each shop, under legal_name.

None. Every authenticated key can read its own company, whatever its scopes.

• This resource exposes GET /company only. The company is derived from the API key, so it takes no identifier and a key can never read another company.
• The company is read-only through the API.

Shops are the points of sale of the company. Their identifiers are required throughout the API: shop_id is mandatory when recording a sale, a cashbook movement or an inventory movement, so listing shops is normally the second call an integration makes, right after reading the company.

Environment: shops are shared between test and production modes — the same shops are returned whichever key you use.

• name — internal name, used to tell shops apart in the back office. brand_name is the customer-facing name printed on receipts.
• siret / vat — identify the shop itself as an establishment.
• legal_name, business_name, siren, naf — describe the legal entity operating the shop. Several shops may share one legal entity, in which case these fields repeat. They are null while no legal entity is attached to the shop.
• footnote and logo — printed on the shop's receipts.

None. Every authenticated key can read the company's shops, whatever its scopes — an integration cannot record a sale without a shop_id.

POST /shop/request takes limit and next_token only — there are no filter criteria on this resource. See Filters for the pagination rules.

• This resource exposes GET /shop/:id and POST /shop/request only. Shops are read-only through the API; they are created and edited in the back office.
• POST /shop/request returns every shop of the company in one response, and total is the real count. next_token is null except for companies with more than 1000 shops, where it resumes the listing.
• Requesting a shop belonging to another company answers 404 Not Found rather than 403, so the API never reveals whether an identifier exists elsewhere.

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.

POST /product/request uses the shared search contract: filter, sort, limit and next_token. The filterable fields are listed in the request schema above; the operators, how and / or / not combine, and the pagination rules are described once under Filters.

Unknown criteria are rejected with 400 rather than ignored.

• 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