Taxes
Requires scope merchant-taxes-read.
Lists the store’s tax rows, lowest priority first, with cursor pagination (limit + starting_after, has_more/next_cursor); channel and active filter. Switched-off taxes are listed too. A tax adds its rate_percent on top of the order’s discounted subtotal at checkout, unless the store’s prices include tax: then the same tax is shown inside the total instead of added (an order says which with taxes_included). Several taxes that apply are added side by side (never compounded; when prices include tax their rates are summed and each row takes its share of the price), and each is rounded in the store’s currency. A tax applies on the channel it names and on every all tax: pos is the point of sale and the vendor apps, instore is the in-store QR menu, and website is the storefront, the apps and the chat inboxes. A tax with applies_to_shipping true is also charged on the delivery or shipping fee the store receives (never on a fee Queek keeps on the marketplace), on the share of the order that is taxable; a product with taxable false is left out of what any tax is charged on.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only taxes of this channel: all, pos, instore or website.
Value in
- "all"
- "pos"
- "instore"
- "website"
- null
true lists the taxes that are switched on, false the switched-off ones.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/taxes?limit=10&channel=all&active=true" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 1042, "name": "Sales tax", "description": "Sales tax on goods and services.", "rate_percent": "8.00", "active": true, "priority": 0, "channel": "all", "applies_to_shipping": false, "created_at": "2026-09-01T10:00:00+01:00", "updated_at": "2026-09-24T10:00:00+01:00" }, { "id": 1043, "name": "Tourism levy", "description": null, "rate_percent": "2.00", "active": false, "priority": 1, "channel": "instore", "applies_to_shipping": false, "created_at": "2026-09-02T10:00:00+01:00", "updated_at": "2026-09-02T10:00:00+01:00" } ], "has_more": true, "next_cursor": "eyJwcmlvcml0eSI6MCwidGF4ZXMucF9pZCI6MTA0MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-taxes-create.
Creates a tax row. rate_percent is a percentage from 0 to 100 with at most two decimals (a string or a number). channel defaults to all. applies_to_shipping (boolean, default false) also charges the tax on the delivery or shipping fee the store receives. A store keeps one active tax per channel: creating an active tax switches off the store’s other active tax of the same channel, so create a second rate only when it should replace the first. A name already used in the channel, by a switched-off tax too, answers 422: bring that tax back with active: true on its update instead. There is no delete: switch a tax off with active: false. Taxes are added on top of prices unless the merchant turned on “Prices include tax” in the store’s tax settings (a setting no key can change) and the rate is not checked against any country’s rules: the merchant is responsible for it. Answers 201 with the tax. Changing a tax changes what shoppers are charged at their next checkout, so only write what the merchant asked for. Idempotency-Key is optional and makes a retried create replay the first answer.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Creates a tax row on the Merchant API: the dashboard's rules, with the rate named for its unit.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/taxes" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Sales tax", "description": "Sales tax on goods and services.", "rate_percent": "8.00", "channel": "all", "active": true, "priority": 0 }'{ "status": "success", "message": "Tax created", "data": { "id": 1042, "name": "Sales tax", "description": "Sales tax on goods and services.", "rate_percent": "8.00", "active": true, "priority": 0, "channel": "all", "applies_to_shipping": false, "created_at": "2026-09-01T10:00:00+01:00", "updated_at": "2026-09-01T10:00:00+01:00" }}Requires scope merchant-taxes-read.
Retrieves one tax of this store by its integer id. An id of another store, or one that does not exist, answers 404.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the tax, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/taxes/1042" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Tax retrieved", "data": { "id": 1042, "name": "Sales tax", "description": "Sales tax on goods and services.", "rate_percent": "8.00", "active": true, "priority": 0, "channel": "all", "applies_to_shipping": false, "created_at": "2026-09-01T10:00:00+01:00", "updated_at": "2026-09-24T10:00:00+01:00" }}Requires scope merchant-taxes-update.
Changes any of name, description, rate_percent, active, priority, channel and applies_to_shipping of a tax; fields left out keep their value. Switching a tax on, or moving an active tax into another channel, switches off the store’s other active tax of that channel. Past orders keep the amount they were charged; only later checkouts use the new rate. An id of another store answers 404. A name already used in the channel answers 422.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the tax, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Changes a tax row on the Merchant API: the dashboard's rules, with the rate named for its unit.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/taxes/1042" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "rate_percent": "5.00" }'{ "status": "success", "message": "Tax updated", "data": { "id": 1042, "name": "Sales tax", "description": "Sales tax on goods and services.", "rate_percent": "5.00", "active": true, "priority": 0, "channel": "all", "applies_to_shipping": false, "created_at": "2026-09-01T10:00:00+01:00", "updated_at": "2026-09-24T10:00:00+01:00" }}