Shipping zones
Requires scope merchant-shipping-read.
Lists the store’s shipping zones.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
1 <= value <= 100Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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/shipping-zones?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c21", "name": "Lagos Island", "zone_type": "local", "countries": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "1500.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": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "3500.00", "per_kg_rate": "500.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"}Requires scope merchant-shipping-create.
Creates a shipping zone with rates and delivery windows.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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 under Dashboard → Settings → API keys. 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.
POST shipping-zones / PUT shipping-zones/{zone} on the merchant API.
Zone rules match the dashboard's, except the rates: this API speaks money as decimal strings in the currency's major unit ("1500.00", or a number) — the same shape a zone read returns, so a read round-trips into a write. Values are stored in the currency's minor unit; the dashboard sends minor-unit integers directly.
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": [ "NG" ], "base_rate": "3500.00", "per_kg_rate": "500.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": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "3500.00", "per_kg_rate": "500.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" }}Requires scope merchant-shipping-update.
Replaces a shipping zone; name, type, base rate and delivery window are required.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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.
POST shipping-zones / PUT shipping-zones/{zone} on the merchant API.
Zone rules match the dashboard's, except the rates: this API speaks money as decimal strings in the currency's major unit ("1500.00", or a number) — the same shape a zone read returns, so a read round-trips into a write. Values are stored in the currency's minor unit; the dashboard sends minor-unit integers directly.
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": "Lagos Island", "zone_type": "local", "countries": [ "NG" ], "base_rate": "1500.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": "Lagos Island", "zone_type": "local", "countries": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "1500.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" }}