Inventory
Requires scope merchant-inventory-read.
Retrieves the store’s inventory overview: product counts by stock state (tracked, in stock, out of stock, low, negative).
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.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/inventory" \ -H "X-Client-Key: {{merchantKey}}"{ "success": true, "data": { "total_products": 9, "tracked_products": 8, "untracked_products": 1, "in_stock": 8, "out_of_stock": 1, "low_stock": 2, "negative_stock": 0 }}Requires scope merchant-inventory-read.
Lists on-hand product and variant stock levels, ordered by product p_id. Filters product by p_id or slug and barcode by exact product OR variant barcode; when both are supplied they are ANDed. Unresolved product references return 404. Includes inactive variants and published or unpublished products; omits soft-deleted products. Each product lists all of its variants (no per-product cap); use a small limit for products with many variants. Each product and variant lists its quantity per store location (locations, with what open orders hold there); stock is the online total.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only this product: its integer id or its slug. A UUID is not accepted.
length <= 255Only products whose own barcode, or one of their variants' barcodes, equals this value exactly (surrounding spaces are trimmed).
length <= 100Header 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/inventory/levels?limit=2&starting_after=eyJwX2lkIjoyMDQxNywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "p_id": 20418, "slug": "fresh-lemonade", "barcode": null, "stock": 60, "locations": [ { "location_id": 1000, "quantity": 60, "mode": "sells_online", "counts_online": true, "committed": 0 } ], "online": { "units": 60, "locations": 1, "message": "60 units can be sold online." }, "effective_tracking": true, "variants": [ { "p_id": 7731, "sku": "NWG-LEM-16OZ", "barcode": "012345300050", "title": "16 oz", "stock": 36, "locations": [ { "location_id": 1000, "quantity": 30, "mode": "sells_online", "counts_online": true, "committed": 0 }, { "location_id": 1001, "quantity": 6, "mode": "sells_online", "counts_online": true, "committed": 0 } ], "online": { "units": 36, "locations": 2, "message": "36 units can be sold online, from 2 locations." }, "is_active": true, "effective_tracking": true }, { "p_id": 7732, "sku": "NWG-LEM-32OZ", "barcode": null, "title": "32 oz", "stock": 24, "locations": [ { "location_id": 1000, "quantity": 24, "mode": "sells_online", "counts_online": true, "committed": 0 } ], "online": { "units": 24, "locations": 1, "message": "24 units can be sold online." }, "is_active": true, "effective_tracking": true } ] } ], "has_more": true, "next_cursor": "eyJwX2lkIjoyMDQxOCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-inventory-update.
Sets a tracked product or variant on-hand quantity with expected_stock compare-and-set, or applies a tracked delta, and writes an adjustment audit row with a configured reason code. Body product/variant references outside this store return 404. A stale expected_stock returns 409 with current_stock; refresh the level before retrying. Idempotency-Key is optional. One item per call; the optional location (its number) changes that location’s level and expected_stock is read against it, while left out the change is to the product’s online total. No bulk adjustments, purchase orders or forecasts, or check against open-order reservations.
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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/inventory/levels/adjustments" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "product": "20417", "mode": "set", "quantity": 44, "expected_stock": 42, "reason_code": "count" }'{ "status": "success", "message": "Inventory level adjusted.", "data": { "result": "adjusted", "level": { "product_p_id": 20417, "variant_p_id": null, "location_id": null, "mode": "set", "before": 42, "change": 2, "after": 44, "reason_code": "count" }, "adjustment": { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b13", "type": "adjustment", "quantity_before": 42, "quantity_change": 2, "quantity_after": 44, "reason": "Physical count", "reason_code": "count", "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack" }, "variant": null, "order": null, "location_id": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-10-04T12:00:00+01:00" } }}Requires scope merchant-inventory-detail.
Retrieves the stock-movement history for one product.
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 product, as returned by the Merchant API.
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only movements of these kinds, one or a comma list: initial, restock, sale, adjustment, damage, return or purchase_order_received.
length <= 255Only movements made at this location (its number); one that is not the store's matches nothing. Older movements belong to the default location.
1 <= valueHeader 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/inventory/products/20417/history?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b11", "type": "sale", "quantity_before": 44, "quantity_change": -2, "quantity_after": 42, "reason": "Order 26-0924-58213", "reason_code": null, "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack" }, "variant": null, "order": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01" }, "location_id": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T13:42:00+01:00" }, { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b10", "type": "restock", "quantity_before": 24, "quantity_change": 20, "quantity_after": 44, "reason": "Morning batch", "reason_code": null, "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack" }, "variant": null, "order": null, "location_id": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T07:05:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEzYTBlLTZkMjEtN2I1NC04ZTkwLTJmNGE2YzhlMGIxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-stock_adjustments-read.
Lists stock adjustments: the store’s stock audit trail, newest first, with cursor pagination. type keeps one or several kinds, comma-separated (sale,return); product_id keeps one product, by its id (the product.id each movement shows), slug or uid; date_from / date_to bound the day. Each movement names its variant by id (p_id) and uid when it moved a variant.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only movements of these kinds, comma-separated (sale,return): initial, restock, sale, adjustment, damage, return or purchase_order_received.
length <= 255Only movements of this product: its id (the product.id on each movement), slug or uid.
length <= 255Only movements made at this location (its number); one that is not the store's matches nothing. Older movements belong to the default location.
1 <= valueOnly movements recorded on or after this day (the date part of an ISO-8601 date or timestamp is used).
date-timeOnly movements recorded on or before this day, inclusive (the date part of an ISO-8601 date or timestamp is used).
date-timeHeader 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/inventory/adjustments?limit=2&date_from=2026-09-24T00%3A00%3A00%2B01%3A00&date_to=2026-09-24T23%3A59%3A59%2B01%3A00" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b12", "type": "restock", "quantity_before": 12, "quantity_change": 24, "quantity_after": 36, "reason": "Afternoon batch", "reason_code": null, "scope": "variant", "product": { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Fresh Lemonade", "slug": "fresh-lemonade" }, "variant": { "id": null, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "title": "16 oz", "option_values": { "Size": "16 oz" } }, "order": null, "location_id": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T15:30:00+01:00" }, { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b11", "type": "sale", "quantity_before": 44, "quantity_change": -2, "quantity_after": 42, "reason": "Order 26-0924-58213", "reason_code": null, "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack" }, "variant": null, "order": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01" }, "location_id": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T13:42:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEzYTBlLTZkMjEtN2I1NC04ZTkwLTJmNGE2YzhlMGIxMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-inventory-update.
Applies a stock delta to products and writes the audit-trail entry. A single adjustment answers the stock-movement object (the history and audit rows list the same one); a bulk restock names each skipped product by id (p_id) and uid.
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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/inventory/adjustments" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "product_ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22" ], "variant_id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "quantity_change": 24, "type": "restock", "reason": "Afternoon batch" }'{ "success": true, "message": "Stock adjusted successfully", "data": { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b12", "type": "restock", "quantity_before": 12, "quantity_change": 24, "quantity_after": 36, "reason": "Afternoon batch", "reason_code": null, "scope": "variant", "product": { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Fresh Lemonade", "slug": "fresh-lemonade" }, "variant": { "id": null, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "title": "16 oz", "option_values": { "Size": "16 oz" } }, "order": null, "location_id": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T15:30:00+01:00" }}Requires scope merchant-inventory-read.
Lists tracked products whose available stock (on hand minus what open orders hold) is above zero and at or under threshold (default 5, up to 100000), by product id with cursor pagination (limit + starting_after, has_more/next_cursor). A product with variants is judged on the sum of its active tracked variants and lists the variants that are themselves low in variants; a product with an untracked variant is never low. Each row carries quantities only: on_hand, reserved, available. The same products the dashboard low-stock list shows. Quantities are the online total, not per location: read per-location levels with GET inventory/levels.
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.
Available stock at or under which a product counts as low (1 to 100000, default 5).
1 <= value <= 100000Header 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/inventory/low-stock?limit=2&threshold=5" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 20418, "slug": "fresh-lemonade", "title": "Fresh Lemonade", "on_hand": 6, "reserved": 2, "available": 4, "tracks_inventory": true, "has_variants": false, "variants": [] }, { "id": 20431, "slug": "canvas-tote", "title": "Canvas Tote", "on_hand": 9, "reserved": 4, "available": 5, "tracks_inventory": true, "has_variants": true, "variants": [ { "id": 7741, "title": "Large / Blue", "option_values": { "Size": "Large", "Colour": "Blue" }, "on_hand": 4, "reserved": 1, "available": 3 } ] } ], "has_more": true, "next_cursor": "eyJwX2lkIjoyMDQxOCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-inventory-read.
Lists tracked products whose available stock (on hand minus what open orders hold) is zero, by product id with cursor pagination (limit + starting_after, has_more/next_cursor). A product with variants is judged on the sum of its active tracked variants and lists the variants that are themselves out in variants. Each row carries quantities only: on_hand, reserved, available. An untracked product is listed when the merchant marked it out of stock. The same products the dashboard out-of-stock list shows. threshold is accepted and ignored here. Quantities are the online total, not per location: read per-location levels with GET inventory/levels.
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.
Available stock at or under which a product counts as low (1 to 100000, default 5).
1 <= value <= 100000Header 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/inventory/out-of-stock?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 20418, "slug": "fresh-lemonade", "title": "Fresh Lemonade", "on_hand": 0, "reserved": 0, "available": 0, "tracks_inventory": true, "has_variants": false, "variants": [] }, { "id": 20431, "slug": "canvas-tote", "title": "Canvas Tote", "on_hand": 2, "reserved": 2, "available": 0, "tracks_inventory": true, "has_variants": true, "variants": [ { "id": 7741, "title": "Large / Blue", "option_values": { "Size": "Large", "Colour": "Blue" }, "on_hand": 2, "reserved": 2, "available": 0 } ] } ], "has_more": true, "next_cursor": "eyJwX2lkIjoyMDQxOSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-suppliers-read.
Lists the store’s suppliers A to Z with cursor pagination (limit + starting_after, has_more/next_cursor). q keeps suppliers whose name, contact name or email contains the text, ignoring letter case; percent and underscore match themselves. A supplier has an id, name, contact_name, email, phone, address, is_active and timestamps; the merchant’s notes and custom data are not exposed. Purchase orders name a supplier by this id; create and change suppliers with POST suppliers and PATCH suppliers/{supplier}.
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.
Free-text filter: only suppliers whose name, contact name or email contains this text are returned, ignoring letter case.
length <= 100Header 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/suppliers?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods", "contact_name": "Casey Nguyen", "email": "[email protected]", "phone": "+12025550151", "address": "14 Harbor Industrial Park, Brooklyn", "is_active": true, "created_at": "2026-08-02T10:00:00+01:00", "updated_at": "2026-09-01T09:30:00+01:00" }, { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a02", "name": "Corner Wholesale", "contact_name": null, "email": null, "phone": "+12025550154", "address": null, "is_active": true, "created_at": "2026-08-15T14:20:00+01:00", "updated_at": "2026-08-15T14:20:00+01:00" } ], "has_more": true, "next_cursor": "eyJuYW1lIjoiQ29ybmVyIFdob2xlc2FsZSIsImlkIjoiMDE5YTRjMTAtMmIxMS03ZDkwLWEzYjUtNmM4ZDBlMmY0YTAyIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-suppliers-create.
Creates a supplier of this store: name (required), and optional contact_name, email, phone, address and is_active (default true). The merchant’s notes and custom data on a supplier are theirs and cannot be written. Answers 201 with the supplier, whose id names it on purchase orders.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Creates (POST) or changes (PATCH, only the fields sent) a supplier through the Merchant API. Only the fields every supplier read shows are writable: the merchant's notes and custom data stay theirs.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/suppliers" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Greenmarket Produce", "contact_name": "Sam Rivera", "phone": "+12025550152", "address": "Hunts Point Market, Bronx" }'{ "status": "success", "message": "Supplier created.", "data": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods", "contact_name": "Casey Nguyen", "email": "[email protected]", "phone": "+12025550151", "address": "14 Harbor Industrial Park, Brooklyn", "is_active": true, "created_at": "2026-08-02T10:00:00+01:00", "updated_at": "2026-09-01T09:30:00+01:00" }}Requires scope merchant-suppliers-update.
Changes a supplier of this store: only the fields sent change (name, contact_name, email, phone, address, is_active); the merchant’s notes and custom data are not writable. {supplier} is the supplier id; one of another store reads as not found. Answers the supplier.
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 supplier, 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.
Creates (POST) or changes (PATCH, only the fields sent) a supplier through the Merchant API. Only the fields every supplier read shows are writable: the merchant's notes and custom data stay theirs.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/suppliers/019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "phone": "+12025550153", "is_active": true }'{ "status": "success", "message": "Supplier updated.", "data": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods", "contact_name": "Casey Nguyen", "email": "[email protected]", "phone": "+12025550151", "address": "14 Harbor Industrial Park, Brooklyn", "is_active": true, "created_at": "2026-08-02T10:00:00+01:00", "updated_at": "2026-09-01T09:30:00+01:00" }}Requires scope merchant-purchase_orders-read.
Lists the store’s purchase orders, newest first, with cursor pagination (limit + starting_after, has_more/next_cursor). status keeps one of draft, ordered, partial, received, closed or cancelled. Each order has its id, number, status, supplier, currency, total_cost (a decimal string), dates, notes, ordered and received quantities and its line_items (product id and slug, the variant when the line names one, quantities, unit_cost, total_cost); receipts are on the single-order read.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only items with this status. One of draft, ordered, partial, received, closed, cancelled.
Value in
- "draft"
- "ordered"
- "partial"
- "received"
- "closed"
- "cancelled"
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/purchase-orders?limit=2&status=ordered" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03", "number": "PO-20260924-001", "status": "ordered", "supplier": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods" }, "currency": "USD", "total_cost": "69.60", "expected_date": "2026-09-30", "ordered_at": "2026-09-24T09:10:00+01:00", "notes": "Deliver to the downtown kitchen.", "quantity_ordered": 24, "quantity_received": 0, "line_items": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "product": { "id": 20418, "slug": "fresh-lemonade" }, "variant": null, "quantity_ordered": 24, "quantity_received": 0, "unit_cost": "2.90", "total_cost": "69.60", "notes": "Chilled" } ], "created_at": "2026-09-24T09:10:00+01:00", "updated_at": "2026-09-24T09:10:00+01:00" } ], "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yNCAwOToxMDowMCIsImlkIjoiMDE5YTRjMTAtNGQyMi03ZTAxLWI0YzYtN2Q5ZTFmM2E1YjAzIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-purchase_orders-create.
Creates a purchase order for a supplier of this store: supplier is its id, each items[] line names a product (p_id or slug of this store) and optionally a variant (its p_id, a variant of that product) with quantity_ordered, unit_cost and optional notes. An order has at most 100 lines, each for 1 to 1,000,000 units, and one line per product and variant (the same product and variant twice, as p_id and slug too, answers 422 with the field items.{index}.product). A line without a variant is product-level and names the variant when the goods are received (items[].variant on POST purchase-orders/{po}/receive); a line with a variant receives into that variant. unit_cost may be sent as a decimal string or a number and may be left out: the line then takes the variant’s cost price, else the product’s, else 0; responses carry it as a string. status is ordered (default) or draft (mark it ordered later with POST purchase-orders/{po}/order, or cancel it with POST purchase-orders/{po}/cancel); expected_date must be after today. Creating an order plans a purchase only: no stock or product cost changes until goods are received. A supplier, product or variant not in this store answers 404 or 422. Answers the purchase 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 purchase-orders: the dashboard's request with its gate (purchase orders
on the plan, merchant-purchase_orders-create) and its rules for quantities,
costs, dates and status, but naming the supplier and each line's product the
way the rest of the Merchant API does: supplier is a supplier id of this
store, items[].product a product p_id or slug of this store. Anything not
in this store answers 404, never a 422 that tells a foreign id from a missing
one. An order is bounded the way a stock level is:
at most 100 lines, each for at most the largest stock a level may hold.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/purchase-orders" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "supplier": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "items": [ { "product": "20418", "variant": 51207, "quantity_ordered": 24, "unit_cost": "2.90", "notes": "Chilled" } ], "status": "ordered", "notes": "Deliver to the downtown kitchen." }'{ "status": "success", "message": "Purchase order created.", "data": { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03", "number": "PO-20260924-001", "status": "ordered", "supplier": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods" }, "currency": "USD", "total_cost": "69.60", "expected_date": "2026-09-30", "ordered_at": "2026-09-24T09:10:00+01:00", "notes": "Deliver to the downtown kitchen.", "quantity_ordered": 24, "quantity_received": 0, "line_items": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "product": { "id": 20418, "slug": "fresh-lemonade" }, "variant": null, "quantity_ordered": 24, "quantity_received": 0, "unit_cost": "2.90", "total_cost": "69.60", "notes": "Chilled" } ], "created_at": "2026-09-24T09:10:00+01:00", "updated_at": "2026-09-24T09:10:00+01:00" }}Requires scope merchant-purchase_orders-detail.
Retrieves one purchase order with its line items and its receipts: every receive, with received_at, notes and the quantity and unit_cost received per line. {po} is the order id; an order of another store reads as not found. Who created or received anything is not exposed.
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 purchase 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/purchase-orders/019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Purchase order retrieved.", "data": { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03", "number": "PO-20260924-001", "status": "partial", "supplier": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods" }, "currency": "USD", "total_cost": "69.60", "expected_date": "2026-09-30", "ordered_at": "2026-09-24T09:10:00+01:00", "notes": "Deliver to the downtown kitchen.", "quantity_ordered": 24, "quantity_received": 10, "line_items": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "product": { "id": 20418, "slug": "fresh-lemonade" }, "variant": null, "quantity_ordered": 24, "quantity_received": 10, "unit_cost": "2.90", "total_cost": "69.60", "notes": "Chilled" } ], "created_at": "2026-09-24T09:10:00+01:00", "updated_at": "2026-09-25T11:45:00+01:00", "receipts": [ { "id": "019a4c11-0a33-7f12-b5d7-8e0f2a4b6c21", "received_at": "2026-09-25T11:45:00+01:00", "notes": "First crate; the rest follows Monday.", "line_items": [ { "purchase_order_item": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "variant": null, "quantity_received": 10, "unit_cost": "2.90" } ] } ] }}Requires scope merchant-purchase_orders-update.
Cancels a purchase order that is still a draft: nothing was ordered or received, so only its status changes to cancelled and no stock moves; the cancel is written to the store’s activity log. An order in any other status answers 409 conflict (data.status names it). Send no body. {po} is the order id; an order of another store reads as not found. Answers the cancelled 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 purchase 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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/purchase-orders/019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03/cancel" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Purchase order cancelled.", "data": { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03", "number": "PO-20260924-001", "status": "cancelled", "supplier": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods" }, "currency": "USD", "total_cost": "69.60", "expected_date": "2026-09-30", "ordered_at": "2026-09-24T09:10:00+01:00", "notes": "Deliver to the downtown kitchen.", "quantity_ordered": 24, "quantity_received": 0, "line_items": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "product": { "id": 20418, "slug": "fresh-lemonade" }, "variant": null, "quantity_ordered": 24, "quantity_received": 0, "unit_cost": "2.90", "total_cost": "69.60", "notes": "Chilled" } ], "created_at": "2026-09-24T09:10:00+01:00", "updated_at": "2026-09-24T09:10:00+01:00" }}Requires scope merchant-purchase_orders-update.
Marks a draft purchase order as ordered (sent to the supplier) and sets ordered_at; it cannot be undone, and from then on the order expects its goods. No stock moves until goods are received. An order in any other status answers 409 conflict (data.status names it). Send no body. {po} is the order id; an order of another store reads as not found. The change is written to the store’s activity log. Answers the ordered purchase 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 purchase 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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/purchase-orders/019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03/order" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Purchase order marked as ordered.", "data": { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03", "number": "PO-20260924-001", "status": "ordered", "supplier": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods" }, "currency": "USD", "total_cost": "69.60", "expected_date": "2026-09-30", "ordered_at": "2026-09-24T09:10:00+01:00", "notes": "Deliver to the downtown kitchen.", "quantity_ordered": 24, "quantity_received": 0, "line_items": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "product": { "id": 20418, "slug": "fresh-lemonade" }, "variant": null, "quantity_ordered": 24, "quantity_received": 0, "unit_cost": "2.90", "total_cost": "69.60", "notes": "Chilled" } ], "created_at": "2026-09-24T09:10:00+01:00", "updated_at": "2026-09-24T09:10:00+01:00" }}Requires scope merchant-purchase_orders-update.
Closes an ordered or partial purchase order whose remaining goods are not coming: its status becomes closed, nothing more can be received against it, what was received stays received, and no stock moves (closing an ordered order that received nothing therefore changes stock exactly as cancelling would, while the order keeps its ordered record). An order in any other status answers 409 conflict (data.status names it); a draft is cancelled instead (POST purchase-orders/{po}/cancel). Send no body. {po} is the order id; an order of another store reads as not found. The change is written to the store’s activity log. Answers the closed purchase 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 purchase 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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/purchase-orders/019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03/close" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Purchase order closed.", "data": { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03", "number": "PO-20260924-001", "status": "closed", "supplier": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods" }, "currency": "USD", "total_cost": "69.60", "expected_date": "2026-09-30", "ordered_at": "2026-09-24T09:10:00+01:00", "notes": "Deliver to the downtown kitchen.", "quantity_ordered": 24, "quantity_received": 10, "line_items": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "product": { "id": 20418, "slug": "fresh-lemonade" }, "variant": null, "quantity_ordered": 24, "quantity_received": 10, "unit_cost": "2.90", "total_cost": "69.60", "notes": "Chilled" } ], "created_at": "2026-09-24T09:10:00+01:00", "updated_at": "2026-09-25T11:45:00+01:00", "receipts": [ { "id": "019a4c11-0a33-7f12-b5d7-8e0f2a4b6c21", "received_at": "2026-09-25T11:45:00+01:00", "notes": "First crate; the rest follows Monday.", "line_items": [ { "purchase_order_item": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "variant": null, "quantity_received": 10, "unit_cost": "2.90" } ] } ] }}Requires scope merchant-purchase_orders-update.
Receives goods against a purchase order, in full or in part: each items[] line (at most 100) names a purchase_order_item (a line id) and a quantity_received (1 to 1,000,000), plus the variant (its p_id) the goods are for, which a line ordered for one variant may leave out (naming a different one is a 422); a product-level line for a product with active variants must name one (else 422 variant_required, nothing received), and a variant that is not of that line’s product in this store is a 422. The quantity is added to that variant’s stock (the product’s totals follow), or, for a product without variants, to the product’s stock, with a stock adjustment linked to the receipt, and the receipt records the line’s ordered unit_cost; the product’s own cost price is not changed. The order becomes partial or received; receiving a draft marks it ordered first. An Idempotency-Key header is REQUIRED: a retry with the same key and body replays the first answer instead of receiving the goods twice, and a different body under a used key answers 409. A cancelled, closed or fully received order answers 409 conflict; a line that would take in more than it has left answers 422, and nothing is received at all when any line is refused; 422s name the line (items.{index}.variant or items.{index}.quantity_received in error.errors). Each received line writes a stock adjustment of type purchase_order_received (positive quantity_change, variant scope when a variant was named, reason_code null), readable at GET inventory/adjustments?type=purchase_order_received. A purchase order or line that is not in this store answers 404. Answers the purchase order with its receipts.
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 purchase 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 purchase-orders/{po}/receive: the dashboard's request, gate
and rules (merchant-purchase_orders-update), naming each line the way the
rest of the Merchant API does (items[].purchase_order_item, the line id),
plus one rule of its own: receiving moves stock, so an Idempotency-Key
header is REQUIRED. A retry with the same key and body replays the first
answer instead of receiving the goods twice; a different body under a used
key is the standard 409.
A line may name the variant (its p_id) the goods are for: the quantity is then
added to that variant of the line's product and the product's totals follow.
A line for a product with active variants that names none is refused 422
variant_required and nothing is received.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/purchase-orders/019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03/receive" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "purchase_order_item": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "quantity_received": 10 } ], "received_at": "2026-09-25T11:45:00+01:00", "notes": "First crate; the rest follows Monday." }'{ "status": "success", "message": "Purchase order items received.", "data": { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b03", "number": "PO-20260924-001", "status": "partial", "supplier": { "id": "019a4c10-2b11-7d90-a3b5-6c8d0e2f4a01", "name": "Harbor Fresh Foods" }, "currency": "USD", "total_cost": "69.60", "expected_date": "2026-09-30", "ordered_at": "2026-09-24T09:10:00+01:00", "notes": "Deliver to the downtown kitchen.", "quantity_ordered": 24, "quantity_received": 10, "line_items": [ { "id": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "product": { "id": 20418, "slug": "fresh-lemonade" }, "variant": null, "quantity_ordered": 24, "quantity_received": 10, "unit_cost": "2.90", "total_cost": "69.60", "notes": "Chilled" } ], "created_at": "2026-09-24T09:10:00+01:00", "updated_at": "2026-09-25T11:45:00+01:00", "receipts": [ { "id": "019a4c11-0a33-7f12-b5d7-8e0f2a4b6c21", "received_at": "2026-09-25T11:45:00+01:00", "notes": "First crate; the rest follows Monday.", "line_items": [ { "purchase_order_item": "019a4c10-4d22-7e01-b4c6-7d9e1f3a5b11", "variant": null, "quantity_received": 10, "unit_cost": "2.90" } ] } ] }}