Queek docs
Merchant endpoint reference

Shipping zones

GET
/shipping-zones

Requires scope merchant-shipping-read.

Lists the store’s shipping zones.

Authorization

merchantKey
X-Client-Key<token>

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

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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/shipping-zones?limit=2" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c21",      "name": "Manhattan",      "zone_type": "local",      "countries": [        "US"      ],      "state_ids": [],      "area_ids": [],      "currency": "USD",      "base_rate": "3.00",      "per_kg_rate": null,      "min_weight_kg": null,      "max_weight_kg": null,      "min_days": 1,      "max_days": 1,      "active": true,      "position": 1,      "created_at": "2026-07-05T10:00:00+01:00",      "updated_at": "2026-09-10T14:30:00+01:00"    },    {      "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c22",      "name": "Nationwide",      "zone_type": "national",      "countries": [        "US"      ],      "state_ids": [],      "area_ids": [],      "currency": "USD",      "base_rate": "7.00",      "per_kg_rate": "1.00",      "min_weight_kg": "0.50",      "max_weight_kg": "30.00",      "min_days": 2,      "max_days": 5,      "active": true,      "position": 2,      "created_at": "2026-07-05T10:05:00+01:00",      "updated_at": "2026-09-10T14:32:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6IjAxOWEyYzVkLTNlNGYtN2E1Yi04YzZkLTdlOGY5YTBiMWMyMiIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}
POST
/shipping-zones

Requires scope merchant-shipping-create.

Creates a shipping zone with rates and delivery windows.

Authorization

merchantKey
X-Client-Key<token>

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

X-Client-Key*string

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.

X-Request-Id?string

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.

Idempotency-Key?string

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.

POST shipping-zones / PUT shipping-zones/{zone} on the merchant API.

Same zone rules and money rates as the dashboard zone write: major-unit decimal strings or numbers, the shape a read returns. This request only adds the row's scope gate.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/shipping-zones" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "name": "Nationwide",    "zone_type": "national",    "countries": [      "US"    ],    "base_rate": "7.00",    "per_kg_rate": "1.00",    "min_weight_kg": 0.5,    "max_weight_kg": 30,    "min_days": 2,    "max_days": 5,    "active": true,    "sort_order": 2  }'
{  "status": "success",  "message": "Shipping zone created",  "data": {    "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c22",    "name": "Nationwide",    "zone_type": "national",    "countries": [      "US"    ],    "state_ids": [],    "area_ids": [],    "currency": "USD",    "base_rate": "7.00",    "per_kg_rate": "1.00",    "min_weight_kg": "0.50",    "max_weight_kg": "30.00",    "min_days": 2,    "max_days": 5,    "active": true,    "position": 2,    "created_at": "2026-07-05T10:05:00+01:00",    "updated_at": "2026-07-05T10:05:00+01:00"  }}
PUT
/shipping-zones/{zone}

Requires scope merchant-shipping-update.

Replaces a shipping zone; name, type, base rate and delivery window are required.

Authorization

merchantKey
X-Client-Key<token>

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

zone*string

Identifier of the shipping zone, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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.

Idempotency-Key?string

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.

POST shipping-zones / PUT shipping-zones/{zone} on the merchant API.

Same zone rules and money rates as the dashboard zone write: major-unit decimal strings or numbers, the shape a read returns. This request only adds the row's scope gate.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/shipping-zones/019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c21" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "name": "Manhattan",    "zone_type": "local",    "countries": [      "US"    ],    "base_rate": "3.00",    "min_days": 1,    "max_days": 1,    "active": true,    "sort_order": 1  }'
{  "status": "success",  "message": "Shipping zone updated",  "data": {    "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c21",    "name": "Manhattan",    "zone_type": "local",    "countries": [      "US"    ],    "state_ids": [],    "area_ids": [],    "currency": "USD",    "base_rate": "3.00",    "per_kg_rate": null,    "min_weight_kg": null,    "max_weight_kg": null,    "min_days": 1,    "max_days": 1,    "active": true,    "position": 1,    "created_at": "2026-07-05T10:00:00+01:00",    "updated_at": "2026-09-10T14:30:00+01:00"  }}