Queek docs
Merchant endpoint reference

Inventory

GET
/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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

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  }}
GET
/inventory/levels

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

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

product?string

Only this product: its integer id or its slug. A UUID is not accepted.

Lengthlength <= 255
barcode?string

Only products whose own barcode, or one of their variants' barcodes, equals this value exactly (surrounding spaces are trimmed).

Lengthlength <= 100

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"}
POST
/inventory/levels/adjustments

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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"    }  }}
GET
/inventory/products/{product}/history

Requires scope merchant-inventory-detail.

Retrieves the stock-movement history for one product.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

product*string

Identifier of the product, as returned by the Merchant API.

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

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

type?|

Only movements of these kinds, one or a comma list: initial, restock, sale, adjustment, damage, return or purchase_order_received.

Lengthlength <= 255
location_id?|

Only movements made at this location (its number); one that is not the store's matches nothing. Older movements belong to the default location.

Range1 <= value

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

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"}
GET
/inventory/adjustments

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

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

type?|

Only movements of these kinds, comma-separated (sale,return): initial, restock, sale, adjustment, damage, return or purchase_order_received.

Lengthlength <= 255
product_id?|

Only movements of this product: its id (the product.id on each movement), slug or uid.

Lengthlength <= 255
location_id?|

Only movements made at this location (its number); one that is not the store's matches nothing. Older movements belong to the default location.

Range1 <= value
date_from?|

Only movements recorded on or after this day (the date part of an ISO-8601 date or timestamp is used).

Formatdate-time
date_to?|

Only movements recorded on or before this day, inclusive (the date part of an ISO-8601 date or timestamp is used).

Formatdate-time

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"}
POST
/inventory/adjustments

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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"  }}
GET
/inventory/low-stock

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

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

threshold?integer

Available stock at or under which a product counts as low (1 to 100000, default 5).

Range1 <= value <= 100000

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"}
GET
/inventory/out-of-stock

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

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

threshold?integer

Available stock at or under which a product counts as low (1 to 100000, default 5).

Range1 <= value <= 100000

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"}
GET
/suppliers

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

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

q?string

Free-text filter: only suppliers whose name, contact name or email contains this text are returned, ignoring letter case.

Lengthlength <= 100

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"}
POST
/suppliers

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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"  }}
PATCH
/suppliers/{supplier}

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

supplier*string

Identifier of the supplier, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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"  }}
GET
/purchase-orders

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

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

status?string

Only items with this status. One of draft, ordered, partial, received, closed, cancelled.

Value in

  • "draft"
  • "ordered"
  • "partial"
  • "received"
  • "closed"
  • "cancelled"

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"}
POST
/purchase-orders

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST 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"  }}
GET
/purchase-orders/{po}

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

po*string

Identifier of the purchase order, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

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"          }        ]      }    ]  }}
POST
/purchase-orders/{po}/cancel

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

po*string

Identifier of the purchase order, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

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"  }}
POST
/purchase-orders/{po}/order

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

po*string

Identifier of the purchase order, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

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"  }}
POST
/purchase-orders/{po}/close

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

po*string

Identifier of the purchase order, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

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"          }        ]      }    ]  }}
POST
/purchase-orders/{po}/receive

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
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

po*string

Identifier of the purchase order, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST 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"          }        ]      }    ]  }}