Shop API — introduction
Base address, keys, scopes, errors, idempotency, pages and rate limits of the shop API.
| What | Value |
|---|---|
| Base address | https://api.tocler.com/v1 |
| Format | JSON in and out, UTF-8, request bodies up to 64 KB |
| Authentication | Authorization: Bearer tk_live_<id>.<secret> — a key of ONE shop, made by its owner in Dashboard → Developers |
| Where | Server to server only — a request with an Origin header (a browser) is refused |
| Money | Decimal text with an ISO 4217 currency: { "amount": "19.99", "currency": "EUR" } |
| Versions | v1 in the address; fields are only added — a removal or rename comes with v2 |
Keys
Only the store owner makes, rotates and revokes keys — with the account password and the 2-step code. The secret is shown once and Tocler keeps only a keyed hash, so a lost key can’t be shown again: rotate or revoke it. A key can have allowed addresses (IPs or IPv4 ranges) and lasts up to 2 years; the owner is emailed 14 days before it expires.
Scopes
A key may do only what its scopes allow:
| Scope | Name | What it allows |
|---|---|---|
| store:read | Read the shop | The shop’s name, address, currency and what the API may do. |
| products:read | Read products | Products of every type with their options, prices, stock and visibility. |
| products:write | Change prices, stock and visibility | The same quick changes as Inventory: an option’s price, a physical product’s stock count, shown / hidden. |
| orders:read | Read orders | Orders with their lines, money, status and delivery — buyers’ emails masked, never addresses or secret answers. |
| orders:write | Deliver orders | Mark a service line delivered with a note for the buyer. |
| checkout:write | Create orders and Tocler Pay payments | Create an order for a buyer’s email through the shop’s checkout, and the Tocler Pay payment of that order. Tocler’s fee applies exactly as in the shop. |
Errors
Every error has an HTTP status and a stable code; message is for people and may change:
{ "error": { "code": "missing_scope", "message": "This key can’t do that — it needs the “orders:read” permission." } }| Status | Codes | When |
|---|---|---|
| 400 | invalid_request · tax_country · answer_required · shipping_required · bad_email · discount | A field (see field) or a checkout rule |
| 401 | missing_key · invalid_key · key_revoked · key_expired | The key |
| 403 | missing_scope · ip_not_allowed · browser_not_allowed · plan_required · store_inactive · api_stopped · checkout_unavailable | What the key or the shop may do |
| 404 | not_found | No such object in this shop |
| 409 | conflict · idempotency_mismatch · request_in_progress · not_payable · coin_unavailable · payment_in_progress · tocler_pay_unavailable | The state changed |
| 413 / 428 | body_too_large · idempotency_key_required | The request |
| 429 | rate_limited · too_many_invalid_keys · too_many_open | Slow down |
| 500 / 503 | server_error · unavailable · api_unavailable · maintenance | Try again later with the same Idempotency-Key |
Idempotency
Every POST and PATCH needs an Idempotency-Key header (1–64 letters, digits, _ - : .). Sending the same request again with the same key returns the first answer for 48 hours (header Idempotent-Replayed: true) — so a retry after a network error never makes a second order. The same key with a different body answers 409 idempotency_mismatch.
Rate limits
Each key may send the number of requests a minute its plan allows. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds); over the limit → 429 rate_limited with Retry-After.
Pages
Lists answer { object: "list", data: [...], has_more }. Ask for the next page with starting_after = the last id you got.
What the API never shows
Tocler’s fee, the settlement of a payment, keys and accounts of orders, secret answers of buyers, shipping addresses and full buyer emails (they are masked). The owner sees those in the Dashboard.