Queek docs
Merchant endpoint reference

Orders

List orders

GET
/orders

Requires scope merchant-orders-read.

Lists the store’s orders — the same object orders/* webhooks send. Same filtering and search as the dashboard table with cursor pagination (limit + starting_after, has_more/next_cursor). Optional updated_after walks order rows changed after a timestamp, oldest change first; start each poll five minutes before the previous poll start, deduplicate ids, keep filters fixed and walk sequentially. With updated_after, sort_by, sort_order, page and per_page return 422; a cursor is bound to the same timestamp and filters. Item/property, shipment, metafield or customer-profile changes and deleted orders may be missed; long-running changes may appear late. The filter time is not returned and may differ from updated_at; this is not a snapshot or deletion feed.

Authorization

merchantKey
X-Client-Key<token>

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

payment_status?|

Value in

  • "paid"
  • "unpaid"
  • "refunded"
  • "partial"
  • "pending"
  • "awaiting_confirmation"
  • null
delivery_method?|

Value in

  • "delivery"
  • "pickup"
  • "instore"
  • "shipping"
  • null
registry_id?|
Formatuuid
metafield[]?array<string>|null
sort_by?|

Value in

  • "created_at"
  • "updated_at"
  • "status"
  • "payment_status"
  • "total"
  • null
sort_order?|

Value in

  • "asc"
  • "desc"
  • null
limit?|
Range1 <= value <= 100
starting_after?string|null
updated_after?string

Header Parameters

X-Client-Key*string

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.

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/orders?payment_status=paid&delivery_method=delivery&limit=2&updated_after=2026-10-03T11%3A55%3A00Z" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": 58214,      "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a02",      "order_number": "26-0924-58214",      "status": "pending",      "payment_status": "paid",      "payment_method": "online",      "fulfillment_status": "unfulfilled",      "cancelled": false,      "cancel_reason": null,      "channel": null,      "platform": "third_party",      "custom_channel": "chowdeck",      "external_ref": "CD-7F3K2Q",      "delivery_method": "delivery",      "currency": "NGN",      "subtotal": "5000.00",      "discount_total": "0.00",      "shipping_total": "1500.00",      "tax_total": "0.00",      "total": "6500.00",      "customer": null,      "shipping_address": {        "address": null,        "latitude": null,        "longitude": null,        "name": "Ifeoma Adebayo",        "phone": "+2348091112233"      },      "shipment": null,      "line_items": [        {          "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a12",          "product_id": 20418,          "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22",          "title": "Homemade Chapman",          "variant_title": "50cl",          "quantity": 2,          "unit_price": "2500.00",          "total": "5000.00",          "properties": {}        }      ],      "note": null,      "metafields": {},      "metadata": {},      "created_at": "2026-09-24T14:05:00+01:00",      "updated_at": "2026-09-24T14:05:00+01:00",      "fulfilled_at": null    },    {      "id": 58213,      "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01",      "order_number": "26-0924-58213",      "status": "processing",      "payment_status": "paid",      "payment_method": "online",      "fulfillment_status": "unfulfilled",      "cancelled": false,      "cancel_reason": null,      "channel": null,      "platform": "storefront",      "custom_channel": null,      "external_ref": null,      "delivery_method": "delivery",      "currency": "NGN",      "subtotal": "37000.00",      "discount_total": "3700.00",      "shipping_total": "2500.00",      "tax_total": "0.00",      "total": "35800.00",      "customer": {        "id": 90341,        "name": "Chiamaka Obi",        "email": "[email protected]",        "phone": "+2348031234567"      },      "shipping_address": {        "address": "7 Ologun Agbaje Street, Victoria Island, Lagos",        "latitude": 6.4298,        "longitude": 3.4219,        "name": null,        "phone": null      },      "shipment": null,      "line_items": [        {          "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",          "product_id": 20417,          "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",          "title": "Jollof Rice Party Pack",          "variant_title": null,          "quantity": 2,          "unit_price": "18500.00",          "total": "37000.00",          "properties": {            "gift.note": "Happy birthday, Tolu!"          }        }      ],      "note": "Leave with the gateman if no one answers.",      "metafields": {},      "metadata": {        "erp_id": "SO-104882"      },      "created_at": "2026-09-24T13:40:00+01:00",      "updated_at": "2026-09-24T13:52:00+01:00",      "fulfilled_at": null    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6NTgyMTMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}

Retrieve an order

GET
/orders/{order}

Requires scope merchant-orders-read.

Retrieves one order — the same object orders/* webhooks send, with line items, customer, shipping address and shipment tracking. {order} is a p_id or UUID of this store.

Authorization

merchantKey
X-Client-Key<token>

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

order*string

Header Parameters

X-Client-Key*string

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.

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/orders/58213" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Order retrieved",  "data": {    "id": 58213,    "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01",    "order_number": "26-0924-58213",    "status": "processing",    "payment_status": "paid",    "payment_method": "online",    "fulfillment_status": "unfulfilled",    "cancelled": false,    "cancel_reason": null,    "channel": null,    "platform": "storefront",    "custom_channel": null,    "external_ref": null,    "delivery_method": "delivery",    "currency": "NGN",    "subtotal": "37000.00",    "discount_total": "3700.00",    "shipping_total": "2500.00",    "tax_total": "0.00",    "total": "35800.00",    "customer": {      "id": 90341,      "name": "Chiamaka Obi",      "email": "[email protected]",      "phone": "+2348031234567"    },    "shipping_address": {      "address": "7 Ologun Agbaje Street, Victoria Island, Lagos",      "latitude": 6.4298,      "longitude": 3.4219,      "name": null,      "phone": null    },    "shipment": null,    "line_items": [      {        "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "product_id": 20417,        "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "variant_title": null,        "quantity": 2,        "unit_price": "18500.00",        "total": "37000.00",        "properties": {          "gift.note": "Happy birthday, Tolu!"        }      }    ],    "note": "Leave with the gateman if no one answers.",    "metafields": {},    "metadata": {      "erp_id": "SO-104882"    },    "created_at": "2026-09-24T13:40:00+01:00",    "updated_at": "2026-09-24T13:52:00+01:00",    "fulfilled_at": null  }}

Update an order

PATCH
/orders/{order}

Requires scope merchant-orders-update.

Changes an order’s developer-extension fields only: metafields, metadata, and per-line properties (line_items: merged by key into each line’s properties; a string sets a key, null deletes it, keys left out keep their value). metafields must reference an existing definition and never use an app-owned (app.*, queek.*) namespace here. metadata is free-form integrator bookkeeping — replaced wholesale (null clears it), capped in size and count, with no namespace rule and no definitions. Line-item property keys from an installation key must live under its own app.{slug}. namespace; any other key writes none under app.* or queek.*. Order state has its own endpoints. Answers the updated order.

Authorization

merchantKey
X-Client-Key<token>

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

order*string

Header Parameters

X-Client-Key*string

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.

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.

PATCH orders/{order} — the developer-extension fields of an order, and nothing else.

An order's state is NOT editable here: status, cancellation, rider assignment and shipment each have their own endpoint with their own side effects (stock, settlement, notifications, webhooks). Any field outside the allowed set is rejected by name with a 422 rather than ignored — an integrator who tries to cancel an order by PATCHing status learns it from the error, not from an order that shipped anyway.

metafields must reference an existing definition for orders and never use an app-owned (app.*, queek.*) namespace on this endpoint. metadata is free-form integrator bookkeeping — replaced wholesale (null clears it), capped in size and count, with no namespace rule and no definitions. line_items merges per-line properties by key: an app mirrors what it booked or issued onto the line it belongs to. Property keys from an app installation key must live under its own app.{slug}. namespace; any other caller writes any checkout-shaped key EXCEPT the app-owned app.* / queek.* ones, so no merchant can forge or clear an app's keys. Keys and values obey the documented caps.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/orders/58213" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "metadata": {      "erp_id": "SO-104882"    },    "line_items": [      {        "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "properties": {          "gift.note": "Happy birthday, Tolu!",          "gift.wrap": null        }      }    ]  }'
{  "status": "success",  "message": "Order updated",  "data": {    "id": 58213,    "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01",    "order_number": "26-0924-58213",    "status": "processing",    "payment_status": "paid",    "payment_method": "online",    "fulfillment_status": "unfulfilled",    "cancelled": false,    "cancel_reason": null,    "channel": null,    "platform": "storefront",    "custom_channel": null,    "external_ref": null,    "delivery_method": "delivery",    "currency": "NGN",    "subtotal": "37000.00",    "discount_total": "3700.00",    "shipping_total": "2500.00",    "tax_total": "0.00",    "total": "35800.00",    "customer": {      "id": 90341,      "name": "Chiamaka Obi",      "email": "[email protected]",      "phone": "+2348031234567"    },    "shipping_address": {      "address": "7 Ologun Agbaje Street, Victoria Island, Lagos",      "latitude": 6.4298,      "longitude": 3.4219,      "name": null,      "phone": null    },    "shipment": null,    "line_items": [      {        "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "product_id": 20417,        "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "variant_title": null,        "quantity": 2,        "unit_price": "18500.00",        "total": "37000.00",        "properties": {          "gift.note": "Happy birthday, Tolu!"        }      }    ],    "note": "Leave with the gateman if no one answers.",    "metafields": {},    "metadata": {      "erp_id": "SO-104882"    },    "created_at": "2026-09-24T13:40:00+01:00",    "updated_at": "2026-09-24T13:52:00+01:00",    "fulfilled_at": null  }}

Import an order from a sales channel

POST
/orders/import

Requires scope merchant-orders-import.

Records an order the outside platform (Chowdeck, Glovo) already charged for: each item names its product (p_id, UUID or slug of this store) and, for a variant, its variant (p_id or UUID of a variant belonging to that product) — the old single ref is refused; totals are stored as charged with no commission, and a re-sent webhook returns the same order instead of a second one. The customer (name + phone) becomes the order’s shipping_address recipient, readable only with merchant-customers-contact-read like every contact — never metadata. Answers the order object orders/* webhooks send.

Authorization

merchantKey
X-Client-Key<token>

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

X-Client-Key*string

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.

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.

Import an order a sales channel (Chowdeck, Glovo) already charged for.

The payload is the platform's receipt, recorded as charged. Item unit prices, delivery fee, discount and total are amounts in naira with at most 2 decimals (6500 or "6500.00"), like every Merchant API amount, and they must add up: the sum of unit_price × quantity, plus delivery_fee, minus discount, equals total. Each item names its product (p_id, UUID or slug of a product in this store) and, for a variant, its variant (p_id or UUID of one of THAT product's variants). The old single ref is refused: product and variant p_ids are separate sequences, so one number could name two rows. A product from another store fails the import with a named 422, never a cross-store sale.

The customer travels as name + phone only and becomes the order's shipping_address recipient; no customer record is created.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/orders/import" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "channel": "chowdeck",    "external_ref": "CD-7F3K2Q",    "placed_at": "2026-09-24T13:05:00Z",    "customer": {      "name": "Ifeoma Adebayo",      "phone": "+2348091112233"    },    "items": [      {        "product": "20418",        "variant": "7731",        "quantity": 2,        "unit_price": 2500      }    ],    "delivery_fee": 1500,    "discount": 0,    "total": 6500,    "fulfilment": "delivery"  }'
{  "status": "success",  "message": "Order already imported.",  "data": {    "id": 58214,    "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a02",    "order_number": "26-0924-58214",    "status": "pending",    "payment_status": "paid",    "payment_method": "online",    "fulfillment_status": "unfulfilled",    "cancelled": false,    "cancel_reason": null,    "channel": null,    "platform": "third_party",    "custom_channel": "chowdeck",    "external_ref": "CD-7F3K2Q",    "delivery_method": "delivery",    "currency": "NGN",    "subtotal": "5000.00",    "discount_total": "0.00",    "shipping_total": "1500.00",    "tax_total": "0.00",    "total": "6500.00",    "customer": null,    "shipping_address": {      "address": null,      "latitude": null,      "longitude": null,      "name": "Ifeoma Adebayo",      "phone": "+2348091112233"    },    "shipment": null,    "line_items": [      {        "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a12",        "product_id": 20418,        "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22",        "title": "Homemade Chapman",        "variant_title": "50cl",        "quantity": 2,        "unit_price": "2500.00",        "total": "5000.00",        "properties": {}      }    ],    "note": null,    "metafields": {},    "metadata": {},    "created_at": "2026-09-24T14:05:00+01:00",    "updated_at": "2026-09-24T14:05:00+01:00",    "fulfilled_at": null  }}

Update an order status

POST
/orders/{order}/status

Requires scope merchant-orders-status-update.

Moves an order to a new status and answers the updated order. approve_payment requires payment_status awaiting_confirmation, a payment method other than online/wallet, and a payment that is not already paid; cancelled or rejected orders cannot be updated. It marks the order paid but does not verify provider receipt or call a provider. accept and rejected need a paid, not-yet-accepted order; every later action needs a paid and accepted order.

Authorization

merchantKey
X-Client-Key<token>

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

order*string

Header Parameters

X-Client-Key*string

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.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/orders/58213/status" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "status": "accept"  }'
{  "status": "success",  "message": "Order accepted",  "data": {    "id": 58213,    "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01",    "order_number": "26-0924-58213",    "status": "processing",    "payment_status": "paid",    "payment_method": "online",    "fulfillment_status": "unfulfilled",    "cancelled": false,    "cancel_reason": null,    "channel": null,    "platform": "storefront",    "custom_channel": null,    "external_ref": null,    "delivery_method": "delivery",    "currency": "NGN",    "subtotal": "37000.00",    "discount_total": "3700.00",    "shipping_total": "2500.00",    "tax_total": "0.00",    "total": "35800.00",    "customer": {      "id": 90341,      "name": "Chiamaka Obi",      "email": "[email protected]",      "phone": "+2348031234567"    },    "shipping_address": {      "address": "7 Ologun Agbaje Street, Victoria Island, Lagos",      "latitude": 6.4298,      "longitude": 3.4219,      "name": null,      "phone": null    },    "shipment": null,    "line_items": [      {        "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "product_id": 20417,        "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "variant_title": null,        "quantity": 2,        "unit_price": "18500.00",        "total": "37000.00",        "properties": {          "gift.note": "Happy birthday, Tolu!"        }      }    ],    "note": "Leave with the gateman if no one answers.",    "metafields": {},    "metadata": {      "erp_id": "SO-104882"    },    "created_at": "2026-09-24T13:40:00+01:00",    "updated_at": "2026-09-24T13:52:00+01:00",    "fulfilled_at": null  }}

Assign a rider to an order

POST
/orders/{order}/assign-rider

Requires scope merchant-orders-status-update.

Assigns one of the store’s active riders to a self-delivery order, or reassigns it. The order must be paid and confirmed with a rider delivery method; fleet and marketplace orders cannot be assigned here. Answers the updated order.

Authorization

merchantKey
X-Client-Key<token>

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

order*string

Header Parameters

X-Client-Key*string

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.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/orders/58213/assign-rider" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "rider_id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a70"  }'
{  "status": "success",  "message": "Rider assigned",  "data": {    "id": 58213,    "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01",    "order_number": "26-0924-58213",    "status": "processing",    "payment_status": "paid",    "payment_method": "online",    "fulfillment_status": "unfulfilled",    "cancelled": false,    "cancel_reason": null,    "channel": null,    "platform": "storefront",    "custom_channel": null,    "external_ref": null,    "delivery_method": "delivery",    "currency": "NGN",    "subtotal": "37000.00",    "discount_total": "3700.00",    "shipping_total": "2500.00",    "tax_total": "0.00",    "total": "35800.00",    "customer": {      "id": 90341,      "name": "Chiamaka Obi",      "email": "[email protected]",      "phone": "+2348031234567"    },    "shipping_address": {      "address": "7 Ologun Agbaje Street, Victoria Island, Lagos",      "latitude": 6.4298,      "longitude": 3.4219,      "name": null,      "phone": null    },    "shipment": null,    "line_items": [      {        "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11",        "product_id": 20417,        "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "variant_title": null,        "quantity": 2,        "unit_price": "18500.00",        "total": "37000.00",        "properties": {          "gift.note": "Happy birthday, Tolu!"        }      }    ],    "note": "Leave with the gateman if no one answers.",    "metafields": {},    "metadata": {      "erp_id": "SO-104882"    },    "created_at": "2026-09-24T13:40:00+01:00",    "updated_at": "2026-09-24T13:52:00+01:00",    "fulfilled_at": null  }}

Update an order shipment

PATCH
/orders/{order}/shipment

Requires scope merchant-orders-update.

Updates an order’s shipment tracking (carrier, tracking number and URL, dates) and optionally advances it to shipped; answers the order with its shipment block.

Authorization

merchantKey
X-Client-Key<token>

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

order*string

Header Parameters

X-Client-Key*string

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.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/orders/58190/shipment" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "carrier_name": "GIG Logistics",    "tracking_number": "GIG-2026-0924-7719",    "tracking_url": "https://giglogistics.com/track/GIG-2026-0924-7719",    "status": "on_transit",    "shipped_at": "2026-09-24T16:10:00+01:00",    "estimated_delivery_at": "2026-09-26T18:00:00+01:00"  }'
{  "status": "success",  "message": "Shipment updated",  "data": {    "id": 58190,    "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a03",    "order_number": "26-0923-58190",    "status": "on_transit",    "payment_status": "paid",    "payment_method": "online",    "fulfillment_status": "unfulfilled",    "cancelled": false,    "cancel_reason": null,    "channel": null,    "platform": "storefront",    "custom_channel": null,    "external_ref": null,    "delivery_method": "shipping",    "currency": "NGN",    "subtotal": "25200.00",    "discount_total": "0.00",    "shipping_total": "6650.00",    "tax_total": "0.00",    "total": "31850.00",    "customer": {      "id": 90342,      "name": "Tunde Bakare",      "email": "[email protected]",      "phone": "+2348059876543"    },    "shipping_address": {      "address": "22 Bompai Road, Nassarawa, Kano",      "latitude": 12.0107,      "longitude": 8.5387,      "name": null,      "phone": null    },    "shipment": {      "carrier_name": "GIG Logistics",      "tracking_number": "GIG-2026-0924-7719",      "tracking_url": "https://giglogistics.com/track/GIG-2026-0924-7719",      "zone_name": "Nationwide",      "shipped_at": "2026-09-24T16:10:00+01:00",      "estimated_delivery_at": "2026-09-26T18:00:00+01:00",      "delivered_at": null    },    "line_items": [      {        "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a13",        "product_id": 20418,        "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22",        "title": "Homemade Chapman",        "variant_title": "1 litre",        "quantity": 6,        "unit_price": "4200.00",        "total": "25200.00",        "properties": {}      }    ],    "note": null,    "metafields": {},    "metadata": {},    "created_at": "2026-09-23T18:22:00+01:00",    "updated_at": "2026-09-24T16:10:00+01:00",    "fulfilled_at": null  }}

Inventory

Previous Page

Customers

Next Page