Orders
Requires scope merchant-orders-read.
Lists the store’s orders using the same base object as orders/* webhooks; recorded payment transactions and Queek wallet-refund rows are present only with merchant-orders-read (webhooks include them only for active installations granted that scope). Order status, shipment, import, rider-assignment and patch responses do not include those finance arrays. Same filtering and search as the dashboard table with cursor pagination (limit + starting_after, has_more/next_cursor). from_date and to_date (YYYY-MM-DD, whole days) or date_range (today, this_week, this_month) keep orders created in a window, counted on the store’s own calendar (its timezone). status=open keeps orders that are not cancelled, rejected or completed; payment_status=outstanding keeps orders with money still owed (stored pending, unpaid, partially_paid or awaiting_confirmation) that are not cancelled or rejected; every stored payment word still filters on its exact value. payment_method is one stored method, or offline_all (offline, pos, bank_transfer, or an offline payment mode) / online_all (every other order that has a method). Each line item carries variant_id (the variant’s id), variant_uid and sku, so sales per variant need no match on variant_title. publication scopes the list to one of the calling installation’s channel publications (p_id or key; human keys use p_id and need the publications-read permission, without it the filter answers 404). custom_channel scopes the list to one hand-recorded or third-party channel name (for example physical_sale or others) and combines with the other filters. 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. Provider-side, vendor-collected, offline and manual-review refunds without a recorded Queek refund row are omitted.
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
A stored payment word (exact match), or outstanding: money still owed on an order that is not cancelled or rejected (pending, unpaid, partially_paid, awaiting_confirmation).
Value in
- "paid"
- "overpaid"
- "partially_refunded"
- "partially_paid"
- "partial"
- "unpaid"
- "refunded"
- "pending"
- "awaiting_confirmation"
- "outstanding"
- null
all (default), open (placed, not cancelled or rejected, not completed: the set the dashboard badge counts), pending (not yet accepted), active, completed, awaiting_pickup, rejected, cancelled, settled or in_progress. Any other word filters nothing.
One stored method (online, bank_transfer, pos, …), or a group word: offline_all (offline method: offline, pos, bank_transfer, or an offline payment mode) or online_all (every other order that has a method; an order with no method is in neither).
One of delivery, pickup, instore, shipping.
Value in
- "delivery"
- "pickup"
- "instore"
- "shipping"
- null
Only orders delivered by this rider (a user id).
uuidOnly orders recorded by this staff member (a user id).
uuidOnly orders placed by this customer (a user id).
uuidOnly orders with this payment mode (for example cash, manual, split).
Only orders rung up in this point-of-sale register session (a register session UUID). Orders placed outside a register never match.
uuidExact-match filter on an order metafield the store has defined, typed by its definition: metafield[custom.erp_id]=ERP-42. Several handles are ANDed. An undefined handle answers 422 metafield_definition_missing; a value the definition cannot hold, 422 metafield_value_invalid.
Only orders attributed to this sales channel: a channel id, or an app key's own channel key. Unknown channel 404, archived 410.
length <= 255One hand-recorded or third-party channel name; combines with ?channel= (channel=third_party narrows the platform, this picks the name). The Merchant API list pages the same rows.
Value in
- "physical_sale"
- "instagram"
- "whatsapp"
- "facebook"
- "flutterwave"
- "jiji"
- "jumia"
- "konga"
- "tiktok"
- "glovo"
- "chowdeck"
- "paystack"
- "snapchat"
- "x_twitter"
- "others"
- null
Field to sort the list by. One of created_at, placed_at, updated_at, status, payment_status, total.
Value in
- "created_at"
- "placed_at"
- "updated_at"
- "status"
- "payment_status"
- "total"
- null
Sort direction. One of asc, desc.
Value in
- "asc"
- "desc"
- null
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 orders placed on or after this day (YYYY-MM-DD), a day on the store's own calendar (its timezone). Ignored when date_range is sent.
dateOnly orders placed on or before this day (YYYY-MM-DD), same time zone, so to_date is a whole day, not midnight. Must not be before from_date. Ignored when date_range is sent.
dateA named window on the store's own calendar: today, this_week (Monday to Sunday) or this_month (the calendar month). Takes precedence over from_date and to_date.
Value in
- "today"
- "this_week"
- "this_month"
- null
Only items changed after this ISO-8601 timestamp.
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/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", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "third_party", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": "glovo", "external_ref": "GL-7F3K2Q", "publication": null, "delivery_method": "delivery", "currency": "USD", "subtotal": "10.00", "discount_total": "0.00", "coupon_code": null, "shipping_total": "3.00", "tax_total": "0.00", "taxes_included": false, "total": "13.00", "amount_paid": "13.00", "balance_due": "0.00", "customer": null, "shipping_address": { "address": null, "latitude": null, "longitude": null, "name": "Jordan Lee", "phone": "+12025550155" }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a12", "product_id": 20418, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "variant_id": null, "variant_uid": null, "sku": "NWG-LEM-000", "title": "Fresh Lemonade", "variant_title": "16 oz", "quantity": 2, "refundable_quantity": null, "unit_price": "5.00", "total": "10.00", "taxable": true, "properties": {} } ], "note": null, "metafields": {}, "metadata": {}, "created_at": "2026-09-24T14:05:00+01:00", "placed_at": null, "updated_at": "2026-09-24T14:05:00+01:00", "fulfilled_at": null, "transactions": [ { "id": 992001, "type": "payment", "status": "success", "payment_method": "online", "payment_provider": "stripe", "amount": "71.60", "currency": "USD", "created_at": "2026-09-24T13:41:00+01:00" } ], "refundable": { "amount": "66.60", "currency": "USD" }, "refunds": [ { "id": 992002, "transaction_id": 992001, "type": "wallet_credit", "reason": "order_cancelled", "status": "success", "amount": "5.00", "currency": "USD", "created_at": "2026-09-24T14:20:00+01:00" } ] }, { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01", "order_number": "26-0924-58213", "status": "processing", "payment_status": "paid", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": null, "external_ref": null, "publication": null, "delivery_method": "delivery", "currency": "USD", "subtotal": "74.00", "discount_total": "7.40", "coupon_code": "WELCOME10", "shipping_total": "5.00", "tax_total": "0.00", "taxes_included": false, "total": "71.60", "amount_paid": "71.60", "balance_due": "0.00", "customer": { "id": 90341, "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148" }, "shipping_address": { "address": "88 Greenwich Street, New York, NY 10006", "latitude": 40.7074, "longitude": -74.0113, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "variant_id": null, "variant_uid": null, "sku": "NWG-SPP-001", "title": "Smokehouse Party Pack", "variant_title": null, "quantity": 2, "refundable_quantity": null, "unit_price": "37.00", "total": "74.00", "taxable": true, "properties": { "gift.note": "Happy birthday, Sam!" } } ], "note": "Leave with the doorman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "placed_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null, "transactions": [ { "id": 992001, "type": "payment", "status": "success", "payment_method": "online", "payment_provider": "stripe", "amount": "71.60", "currency": "USD", "created_at": "2026-09-24T13:41:00+01:00" } ], "refundable": { "amount": "66.60", "currency": "USD" }, "refunds": [ { "id": 992002, "transaction_id": 992001, "type": "wallet_credit", "reason": "order_cancelled", "status": "success", "amount": "5.00", "currency": "USD", "created_at": "2026-09-24T14:20:00+01:00" } ] } ], "has_more": true, "next_cursor": "eyJpZCI6NTgyMTMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-orders-create.
Creates an order for this store, awaiting payment, and answers the order object orders/* webhooks send. Each line names its product (p_id, UUID or slug of this store), a variant when the product has variants (p_id or UUID of one of that product’s variants), a quantity and optional addons (option item p_id or UUID of that product). No price is ever sent: the order engine the dashboard uses prices every line, adds delivery and tax, and applies at most one optional discount: discount_amount, a store-funded amount that is refused when it would leave nothing to charge, or coupon_code, one of the store’s discount codes applied to the order’s lines for its customer and refused with the code’s own reason when it does not apply. Sending both is a 422. delivery_method is instore, pickup or delivery; delivery needs delivery_address, map_lat and map_lng. payment_method is bank_transfer (instore or pickup; the order waits as awaiting_confirmation until payment is approved with orders/{order}/status) or online (any delivery method; needs a customer with an account; the order waits as pending for the customer’s payment). An order is never created paid, and cash, wallet and split payments are not offered. customer is optional: name one customer of this store by exactly one of id (customer id, uid or user id), email or phone; email and phone lookups need merchant-customers-contact-read; without a customer the order is recorded for a guest. The order is attributed to the calling app (platform custom, channel others, labelled with the app name), carries no platform commission, and sends no new-order alert and no customer email. Stock is checked now and taken when the order completes, as for every order. Send an Idempotency-Key header: without one, a retried request creates a second order. No payment link is returned and no draft is kept: an unpaid order is a real order that stays open, holding no stock, until it is paid or cancelled; nothing expires it automatically. Metafields and metadata are written afterwards with PATCH orders/{order}.
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.
POST orders on the Merchant API: an order the store's own app or key rings up for a customer, created awaiting payment.
The body names WHAT is sold, never what it costs: every product, variant and add-on is a reference resolved inside the key's store, and every amount is computed by the same order engine the dashboard uses. Fields that would let a caller dictate money, state or origin (a total, a status, a payment status, a platform) are refused by name rather than ignored, so a caller that sends one learns it now.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/orders" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "line_items": [ { "product": "20418", "variant": "7731", "quantity": 2 } ], "customer": { "id": "90341" }, "delivery_method": "pickup", "payment_method": "bank_transfer", "discount_amount": "1.00", "note": "Collect after 5pm." }'{ "status": "success", "message": "Order created.", "data": { "id": 58215, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a04", "order_number": "26-0924-58215", "status": "pending_payment", "payment_status": "awaiting_confirmation", "is_paid": false, "is_payable": true, "payment_method": "offline", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "custom", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": "others", "external_ref": null, "publication": null, "delivery_method": "pickup", "currency": "USD", "subtotal": "10.00", "discount_total": "1.00", "coupon_code": null, "shipping_total": "0.00", "tax_total": "0.00", "taxes_included": false, "total": "9.00", "amount_paid": "0.00", "balance_due": "9.00", "customer": { "id": 90341, "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148" }, "shipping_address": null, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a13", "product_id": 20418, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "variant_id": null, "variant_uid": null, "sku": "NWG-LEM-000", "title": "Fresh Lemonade", "variant_title": "16 oz", "quantity": 2, "refundable_quantity": null, "unit_price": "5.00", "total": "10.00", "taxable": true, "properties": {} } ], "note": "Collect after 5pm.", "metafields": {}, "metadata": {}, "created_at": "2026-09-24T14:30:00+01:00", "placed_at": null, "updated_at": "2026-09-24T14:30:00+01:00", "fulfilled_at": null }}Requires scope merchant-orders-read.
Retrieves one order using the same base object as orders/* webhooks, with line items, customer, shipping address and shipment tracking. Recorded payment transactions and Queek wallet-refund rows are present only with merchant-orders-read (webhooks include them only for active installations granted that scope); status, shipment, import, rider-assignment and patch responses do not include those finance arrays. Provider-side, vendor-collected, offline and manual-review refunds without a recorded Queek refund row are omitted. {order} is a p_id or UUID of this store.
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 order, 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/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", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": null, "external_ref": null, "publication": null, "delivery_method": "delivery", "currency": "USD", "subtotal": "74.00", "discount_total": "7.40", "coupon_code": "WELCOME10", "shipping_total": "5.00", "tax_total": "0.00", "taxes_included": false, "total": "71.60", "amount_paid": "71.60", "balance_due": "0.00", "customer": { "id": 90341, "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148" }, "shipping_address": { "address": "88 Greenwich Street, New York, NY 10006", "latitude": 40.7074, "longitude": -74.0113, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "variant_id": null, "variant_uid": null, "sku": "NWG-SPP-001", "title": "Smokehouse Party Pack", "variant_title": null, "quantity": 2, "refundable_quantity": null, "unit_price": "37.00", "total": "74.00", "taxable": true, "properties": { "gift.note": "Happy birthday, Sam!" } } ], "note": "Leave with the doorman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "placed_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null, "transactions": [ { "id": 992001, "type": "payment", "status": "success", "payment_method": "online", "payment_provider": "stripe", "amount": "71.60", "currency": "USD", "created_at": "2026-09-24T13:41:00+01:00" } ], "refundable": { "amount": "66.60", "currency": "USD" }, "refunds": [ { "id": 992002, "transaction_id": 992001, "type": "wallet_credit", "reason": "order_cancelled", "status": "success", "amount": "5.00", "currency": "USD", "created_at": "2026-09-24T14:20:00+01:00" } ] }}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 the platform namespaces app.* or queek.*; an app-owned definition’s values (app_{slug}) are written only by that app. 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 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 order, 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.
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
a platform (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, Sam!", "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", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": null, "external_ref": null, "publication": null, "delivery_method": "delivery", "currency": "USD", "subtotal": "74.00", "discount_total": "7.40", "coupon_code": "WELCOME10", "shipping_total": "5.00", "tax_total": "0.00", "taxes_included": false, "total": "71.60", "amount_paid": "71.60", "balance_due": "0.00", "customer": { "id": 90341, "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148" }, "shipping_address": { "address": "88 Greenwich Street, New York, NY 10006", "latitude": 40.7074, "longitude": -74.0113, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "variant_id": null, "variant_uid": null, "sku": "NWG-SPP-001", "title": "Smokehouse Party Pack", "variant_title": null, "quantity": 2, "refundable_quantity": null, "unit_price": "37.00", "total": "74.00", "taxable": true, "properties": { "gift.note": "Happy birthday, Sam!" } } ], "note": "Leave with the doorman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "placed_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null }}Requires scope merchant-checkouts-read.
Lists the store’s abandoned checkouts, newest first, with cursor pagination (limit + starting_after, has_more/next_cursor). stage picks the kind: cart (the default) is signed-in customers of this store whose cart has been unchanged for the idle delay (60 minutes by default) and is no older than the maximum age (72 hours by default); payment is unpaid checkouts, orders a signed-in customer placed and never paid, left unpaid for the unpaid-checkout delay (2 hours by default) and no older than the maximum age, and also needs the merchant-checkouts-payments-read scope (403 without it). Each stage is its own list with its own cursor, and a row is keyed by stage plus id: a cart and an order can share an id. A customer is reported at most once per stage, by their latest cart or latest unpaid order. A cart is dropped once the customer placed an order at this store after its last change; an unpaid order is dropped once they placed an order, or started another order that was not cancelled, after it. Guest carts and orders, orders made on the Queek marketplace (the store dashboard lists those under abandoned orders), orders sent as a staff payment link, orders with a payment under review, empty carts and carts last changed before this feature started are not listed. include_completed=true (payment only) also lists recovered checkouts: orders paid at least the idle delay after they were created, with completed_at set; a refunded one stays listed, and it is off by default so a recovery app never messages someone who already paid. Each row has id, stage, created_at, updated_at (a cart’s last change; a payment row’s paid-or-created time, which does not move when the shopper opens the pay page), completed_at, the customer (id; name, email and phone are null without merchant-customers-contact-read), line_items (product and variant ids, the store’s own title, quantity; no prices) and checkout_url, the store’s checkout page, the same link for every shopper (the shopper signs in to see their cart). Four more keys are null on a cart: order (id, which opens orders/{order}, and order_number), currency (the store’s currency, never a shopper’s presentment currency), total (the order total as a decimal string, the same number as orders/{order}) and recovery_url, the order’s payment page, present only for an online order that can still be paid. The link does not expire and cannot be revoked, except that it is null for an order in a market whose exchange rate has expired (the shopper places the order again): treat it as a secret, never log it or pass it to a third party. A cart row is the object the checkouts/create and checkouts/update webhooks send, which carry carts only and need merchant-checkouts-read; a payment row is the object the payment_checkouts/create webhook sends once per unpaid order, which needs both merchant-checkouts-read and merchant-checkouts-payments-read (there is no update event: a recovered checkout is the orders/create webhook for the same order id; sent once per unpaid checkout in normal operation; a delivery can occasionally be missed (infrastructure failure after the checkout is claimed) or arrive twice (retries): deduplicate by (topic, order id), and use GET abandoned-checkouts?stage=payment to reconcile). updated_since (RFC 3339 with an explicit offset) keeps rows changed at or after that time. A cart counts as abandoned when it is unchanged, not when the shopper is inactive. The window moves with the clock and rows change, so a walk through pages is not a snapshot: poll with updated_since and deduplicate on stage, id and updated_at. A customer who buys after a cart is detected with orders/create.
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.
Which checkouts to list: cart (default) is signed-in customers' idle carts, payment is unpaid checkouts (orders whose payment never arrived) and needs the merchant-checkouts-payments-read scope. Each stage has its own cursor; a row is keyed by stage plus id.
Value in
- "cart"
- "payment"
- null
payment only: also list recovered checkouts, orders paid after being left, with completed_at set. Off by default so a recovery app never nudges a shopper who already paid. Ignored for cart.
Only items last changed at or after this RFC 3339 timestamp with an explicit offset, for example 2026-10-14T09:30:00+01:00. Poll with it and deduplicate on id plus updated_at.
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/abandoned-checkouts?limit=2&stage=cart&updated_since=2026-09-24T09%3A00%3A00%2B01%3A00" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 48217, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T11:05:00+01:00", "customer": { "id": 90341, "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148" }, "line_items": [ { "product": 1042, "variant": 771, "title": "Canvas Tote", "quantity": 2 }, { "product": 1058, "variant": null, "title": "Beaded Bracelet", "quantity": 1 } ], "checkout_url": "https://northwind-goods.queek.shop/checkout", "stage": "cart", "completed_at": null, "order": null, "currency": "USD", "total": null, "recovery_url": null } ], "has_more": true, "next_cursor": "eyJjYXJ0cy51cGRhdGVkX2F0IjoiMjAyNi0wOS0yNCAxMTowNTowMCIsImNhcnRzLnBfaWQiOjQ4MjE3LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"}Requires scope merchant-orders-import.
Records an order already charged by an outside platform: 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 order returns the same record. The authenticated app installation supplies source attribution; only an installed legacy marketplace app sends channel, and it must match its own app slug; any other app omits it, and a supplied value is rejected. The customer (name + phone) becomes the order’s shipping_address recipient, readable only with merchant-customers-contact-read like every contact — never metadata. delivery_fee and discount are required: send "0.00" when there is none, and total must equal the lines plus delivery_fee minus discount. placed_at is when the outside platform took the order: on a dev store it becomes the order’s created_at (the order’s updated_at is still the import time), so a developer can build sales history, and it must be within the last 120 days, the time a dev store keeps imported orders (older answers 422); on a live store the order is recorded now and placed_at is kept as its order date. Answers the order object orders/* webhooks send. Generic app installations derive source from the authenticated installation and omit channel; supplying it is a 422. An installed legacy marketplace app must send the channel slug matching its own app slug; mismatches are 422. Human-key legacy imports still require channel and may choose either slug. Those slugs are not reserved.
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.
Import an order an outside sales channel already charged for. Generic app source attribution comes from the authenticated installation.
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 '{ "external_ref": "APP-7F3K2Q", "placed_at": "2026-09-24T13:05:00Z", "customer": { "name": "Jordan Lee", "phone": "+12025550155" }, "items": [ { "product": "20418", "variant": "7731", "quantity": 2, "unit_price": 5 } ], "delivery_fee": 3, "discount": 0, "total": 13, "fulfilment": "delivery", "inventory_behavior": "decrement" }'{ "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", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "third_party", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": "example-sales-app", "external_ref": "APP-7F3K2Q", "publication": null, "delivery_method": "delivery", "currency": "USD", "subtotal": "10.00", "discount_total": "0.00", "coupon_code": null, "shipping_total": "3.00", "tax_total": "0.00", "taxes_included": false, "total": "13.00", "amount_paid": "13.00", "balance_due": "0.00", "customer": null, "shipping_address": { "address": null, "latitude": null, "longitude": null, "name": "Jordan Lee", "phone": "+12025550155" }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a12", "product_id": 20418, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "variant_id": null, "variant_uid": null, "sku": "NWG-LEM-000", "title": "Fresh Lemonade", "variant_title": "16 oz", "quantity": 2, "refundable_quantity": null, "unit_price": "5.00", "total": "10.00", "taxable": true, "properties": {} } ], "note": null, "metafields": {}, "metadata": {}, "created_at": "2026-09-24T14:05:00+01:00", "placed_at": null, "updated_at": "2026-09-24T14:05:00+01:00", "fulfilled_at": null }, "meta": { "inventory_behavior": "decrement" }}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 records the payment and 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. out_for_delivery and mark_delivered finish a local delivery the store carries itself (no rider or Queek delivery on it): out_for_delivery from ready for pickup, then mark_delivered with the optional pin (string, up to 12 characters), which must match the customer's delivery PIN when the order has one. An unknown order answers 404; every refusal (a wrong or missing PIN, a cancelled or rejected order, a status the order cannot take now) 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 order, 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.
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", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": null, "external_ref": null, "publication": null, "delivery_method": "delivery", "currency": "USD", "subtotal": "74.00", "discount_total": "7.40", "coupon_code": "WELCOME10", "shipping_total": "5.00", "tax_total": "0.00", "taxes_included": false, "total": "71.60", "amount_paid": "71.60", "balance_due": "0.00", "customer": { "id": 90341, "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148" }, "shipping_address": { "address": "88 Greenwich Street, New York, NY 10006", "latitude": 40.7074, "longitude": -74.0113, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "variant_id": null, "variant_uid": null, "sku": "NWG-SPP-001", "title": "Smokehouse Party Pack", "variant_title": null, "quantity": 2, "refundable_quantity": null, "unit_price": "37.00", "total": "74.00", "taxable": true, "properties": { "gift.note": "Happy birthday, Sam!" } } ], "note": "Leave with the doorman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "placed_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null }}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 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 order, 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.
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", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": null, "external_ref": null, "publication": null, "delivery_method": "delivery", "currency": "USD", "subtotal": "74.00", "discount_total": "7.40", "coupon_code": "WELCOME10", "shipping_total": "5.00", "tax_total": "0.00", "taxes_included": false, "total": "71.60", "amount_paid": "71.60", "balance_due": "0.00", "customer": { "id": 90341, "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148" }, "shipping_address": { "address": "88 Greenwich Street, New York, NY 10006", "latitude": 40.7074, "longitude": -74.0113, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "variant_id": null, "variant_uid": null, "sku": "NWG-SPP-001", "title": "Smokehouse Party Pack", "variant_title": null, "quantity": 2, "refundable_quantity": null, "unit_price": "37.00", "total": "74.00", "taxable": true, "properties": { "gift.note": "Happy birthday, Sam!" } } ], "note": "Leave with the doorman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "placed_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null }}Requires scope merchant-orders-refund-create.
Refunds part or all of what a customer paid for an order, against ONE payment of the order: payment names it (a payment id from the order's transactions), else the newest received payment with something left. The refund follows the original payment and the caller never chooses where it goes: a payment Queek collected through its provider goes back to the customer through that provider (it starts pending and ends success or failed), a payment from the customer's Queek wallet goes back to the wallet, a payment on the store's own gateway account goes back through that account when its provider supports refunds, and a payment the store collected itself or took offline is only RECORDED: Queek moves no money and the store refunds the customer itself. amount is always sent (a decimal string in the order currency) and may not exceed what is left to refund on that payment and on the order; a refund cannot be undone. line_items (order_item: a line id from the order, quantity, restock) tell Queek which lines were refunded and put tracked stock back on the shelf; they never set the amount. return (a return id, a p_id or UUID, of this order) links the refund to a return: only an open or closed return can be refunded (409 return_transition_invalid), another store's or another order's return answers 404, and naming one needs the merchant-returns-read scope; without line_items the refund covers each line of the return for the units received and not yet refunded through it (422 refund_line_invalid when none is left), with them each must be a line of the return and at most its quantity less what was already refunded through it, and a linked line is not restocked unless its restock is true (the return's receive puts the goods back). Idempotency-Key is required: the same key with the same body returns the refund already made (200), the same key with another body is 409. notify (default true) tells the customer when the refund lands; note is for the store only and is never sent to the customer or in a webhook. Fires refunds/create when the refund is created, returns/update for the return when return is sent, and orders/updated when a provider refund finishes or fails. Answers 201 with the refund, refundable and restocked.
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 order, 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.
POST orders/{order}/refunds, on the dashboard and the Merchant API: the one refund operation.
The gate order is the permission (the row's scope on the Merchant API), the permission to read a return when the refund names one, then the required Idempotency-Key, all before validation. A dashboard SESSION that refunds money Queek holds (a wallet credit or a provider refund) then confirms with the store transaction PIN, as a withdrawal does; a refund that is only recorded needs none, and keys and apps act on their scope and the merchant's consent. Where the money goes is never a field: it follows the original payment.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/orders/58213/refunds" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "amount": "5.00", "reason": "damaged", "notify": true, "note": "Tray arrived crushed." }'{ "status": "success", "message": "Refund already created", "data": { "id": 992002, "order": 58213, "transaction_id": 992001, "type": "recorded", "reason": "merchant_refund", "status": "success", "amount": "5.00", "currency": "USD", "created_at": "2026-09-24T14:20:00+01:00", "refundable": { "amount": "66.60", "currency": "USD" }, "restocked": [] }}Requires scope merchant-orders-read.
Answers what a refund of some lines of an order would give back, computed by Queek on the order as it was charged, so the amount to send to POST orders/{order}/refunds is never computed by the caller. The suggestion is the lines at what the customer paid for those units (after any automatic line discount), less the units' share of a discount code that covered them, plus the tax those units carried on top of the price; delivery or shipping and its tax, and service, small-order, shop-for-me and processing fees are never included (the merchant may type more). Send line_items (order_item: a line id from the order, quantity), or return (a return id, a p_id or UUID, of this order) alone for the units a refund naming that return would take, and optionally payment (a payment id from the order's transactions) to read the cap from that payment; each line is checked exactly as a refund checks it (422 refund_line_invalid). Money is a decimal string in currency; the amount is rounded once, at the currency's precision, so refunding units one at a time adds up exactly to the order's items. amount is never above cap, the most a refund of that payment can give back now. capped is true when amount was cut down to cap, so it is below subtotal - discount + tax. amount is null, never "0.00", with a reason, when a refund would be refused anyway (courier_request, return_not_refundable, not_refundable, nothing_to_refund) or when the order's stored figures cannot be rebuilt to the cent (currency_precision, order_not_reconcilable, code_scope_unverifiable, tax_base_unverifiable): then send the amount yourself. provider_minimum is the provider's smallest refund when this payment would go back through the payment provider. Naming a return needs the merchant-returns-read scope (403 insufficient_scope); another store's order or return answers 404. Reads only: nothing is refunded, restocked or changed.
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 order, as returned by the Merchant API.
Query Parameters
Suggest for the units of a return of this order, a return id (a p_id or UUID). Only an open or closed return can be refunded (amount is null with the reason return_not_refundable otherwise); another store's return or another order's answers 404. Without line_items the units are the ones a refund naming this return would take: for each line of the return, the units received and not yet refunded through it. Needs the permission to read returns (merchant-returns-read for a key).
length <= 64The payment a refund would reverse, a payment id from the order's transactions; the cap is that payment's. Without it, the newest received payment with something left, as a refund picks it.
length <= 64The lines to suggest for (up to 100), sent as line_items[0][order_item] and line_items[0][quantity]: the line id from the order's line_items and how many units of it. Required unless return is sent; each is checked exactly as a refund checks it (422 refund_line_invalid).
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
application/json
curl -X GET "https://example.com/orders/58213/refund-suggestion" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Refund suggestion retrieved.", "data": { "amount": "5.00", "capped": false, "reason": null, "currency": "USD", "subtotal": "5.00", "discount": "0.00", "tax": "0.00", "shipping": "0.00", "cap": "66.60", "payment": "992001", "provider_minimum": null, "line_items": [ { "order_item": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "quantity": 1, "subtotal": "5.00", "discount": "0.00", "tax": "0.00" } ] }}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 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 order, 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.
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": "Example Express", "tracking_number": "EXP-2026-0924-7719", "tracking_url": "https://express.example/track/EXP-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", "notify_customer": true }'{ "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", "is_paid": true, "is_payable": false, "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "location_id": null, "routing": { "reason": "default", "message": "Fulfilled from the default location.", "short": false, "sell_anyway": false, "sell_anyway_reason": null }, "custom_channel": null, "external_ref": null, "publication": null, "delivery_method": "shipping", "currency": "USD", "subtotal": "50.40", "discount_total": "0.00", "coupon_code": null, "shipping_total": "13.30", "tax_total": "0.00", "taxes_included": false, "total": "63.70", "amount_paid": "63.70", "balance_due": "0.00", "customer": { "id": 90342, "name": "Sam Rivera", "email": "[email protected]", "phone": "+12025550149" }, "shipping_address": { "address": "22 Lake Street, Chicago, IL 60601", "latitude": 41.8858, "longitude": -87.6181, "name": null, "phone": null }, "shipment": { "carrier_name": "Example Express", "tracking_number": "EXP-2026-0924-7719", "tracking_url": "https://express.example/track/EXP-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", "variant_id": 7732, "variant_uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "NWG-LEM-32OZ", "title": "Fresh Lemonade", "variant_title": "32 oz", "quantity": 6, "refundable_quantity": null, "unit_price": "8.40", "total": "50.40", "taxable": true, "properties": {} } ], "note": null, "metafields": {}, "metadata": {}, "created_at": "2026-09-23T18:22:00+01:00", "placed_at": null, "updated_at": "2026-09-24T16:10:00+01:00", "fulfilled_at": null }}