Products
Requires scope merchant-items-read.
Lists the store’s products — the same object products/* webhooks send, with variants, images, the canonical URL, the storefront price, storefront_available (what the storefront shows as available, never the raw in_stock), is_online (the Website switch), min_qty, service_type and per image a channel_image (the JPEG, with its size, the chat channels use). Same filtering as the dashboard table with cursor pagination (limit + starting_after, has_more/next_cursor); sorts limited to public fields. Optional updated_after walks product rows changed after a timestamp, oldest change first; start each poll five minutes before the previous poll start, deduplicate ids, keep filters fixed and walk sequentially. With updated_after, sort_by, sort_order, page and per_page return 422; a cursor is bound to the same timestamp and filters. Variant, image, metafield, stock, region, price, discount, bulk publish, unpublish, archive status or inventory-tracking changes and deleted products may be missed; long-running changes may appear late. The filter time is not returned and may differ from updated_at; this is not a snapshot or deletion feed. publication scopes the list to one of the calling installation channel publications (p_id or key; human keys use p_id and need the publications-read permission, without it the filter answers 404): with updated_after it returns additions and content changes, while a removed product surfaces only in the full reconcile walk, never as a delta. cost_price (the unit cost, a money string or null when none was ever set) is present, on the product and on each variant, only with the protected merchant-items-cost-read scope. A variant has its own cost and a variant without one reads null, never the product’s. Costs older products had copied from the selling price were cleared where they could be identified.
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.
Field to sort the list by. One of created_at, updated_at, title, price, stock, published.
Value in
- "created_at"
- "updated_at"
- "title"
- "price"
- "stock"
- "published"
- null
Sort direction.
Free-text filter: only items matching this text are returned.
Filter by one of the store's own collections (UUID). A global taxonomy id resolves to this store's owned copy of it, when that copy exists; a foreign, unknown or not-yet-copied id matches nothing, never an error.
uuidAlias of category_id, kept so older keys keep working: it resolves to the store's owned collection the same way.
uuidFilter by a manual collection owned by this store (UUID). A foreign or unknown id matches nothing, never an error.
uuidin_stock or out_of_stock; any other value applies no filter. A product that tracks stock counts as in stock while it has units left; one that does not follows its own in-stock switch.
Only products created by one bulk import run (the import's UUID).
uuidOnly products created together in one bulk save (the batch's UUID).
uuidOnly products switched on for this sales channel: marketplace, storefront, inboxes, instore_qr or pos. api and third_party follow the storefront switch. An unknown value applies no filter.
Only products published to this sales channel: a channel id, or an app key's own channel key. Unknown channel 404, archived 410.
length <= 255One of 0, 1, true, false.
Value in
- "0"
- "1"
- "true"
- "false"
- null
One of 0, 1, true, false.
Value in
- "0"
- "1"
- "true"
- "false"
- null
Exact-match filter on a product metafield the store has defined, typed by its definition: metafield[custom.fabric]=cotton. Several handles are ANDed. An undefined handle answers 422 metafield_definition_missing; a value the definition cannot hold, 422 metafield_value_invalid.
Only items changed after this ISO-8601 timestamp.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/products?limit=2&stock_status=in_stock&updated_after=2026-10-03T11%3A55%3A00Z" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Fresh Lemonade", "slug": "fresh-lemonade", "excerpt": "Fresh lemonade with mint and lemon slices.", "description": "Our house lemonade, mixed fresh every morning. Served chilled.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "5.00", "storefront_price": "5.00", "storefront_compare_at_price": null, "url": "https://northwindgoods.example/products/fresh-lemonade", "currency": "USD", "sku": "NWG-LEM-000", "barcode": null, "stock": 60, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": true, "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "variants": [ { "id": 7731, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "sku": "NWG-LEM-16OZ", "barcode": "0012345137001", "title": "16 oz", "option_values": { "Size": "16 oz" }, "currency": "USD", "price": "5.00", "storefront_price": "5.00", "storefront_compare_at_price": null, "url": "https://northwindgoods.example/products/fresh-lemonade?variant=7731", "compare_at_price": null, "stock": 36, "track_inventory": true, "is_digital": false, "storefront_available": true, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 0.55, "position": 0, "metafields": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" }, { "id": 7732, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "NWG-LEM-32OZ", "barcode": "0012345137002", "title": "32 oz", "option_values": { "Size": "32 oz" }, "currency": "USD", "price": "8.40", "storefront_price": "8.40", "storefront_compare_at_price": null, "url": "https://northwindgoods.example/products/fresh-lemonade?variant=7732", "compare_at_price": null, "stock": 24, "track_inventory": true, "is_digital": false, "storefront_available": true, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 1.05, "position": 1, "metafields": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" } ], "options": [ { "name": "Size", "position": 0, "values": [ "16 oz", "32 oz" ] } ], "addons": [], "has_required_addon": false, "requires_packaging": false, "images": [ { "id": 88220, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "alt": "Two bottles of chilled lemonade with lemon slices", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg", "width": null, "height": null } } ], "publications": [], "metafields": {}, "metadata": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null }, { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack", "excerpt": "Hickory-smoked chicken for 10, with cornbread and slaw.", "description": "Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "37.00", "storefront_price": "33.30", "storefront_compare_at_price": "37.00", "url": "https://northwindgoods.example/products/smokehouse-party-pack", "currency": "USD", "sku": "NWG-SPP-001", "barcode": "0012345102417", "stock": 42, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "variants": [], "options": [], "addons": [ { "id": 9101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77", "title": "Extra Toppings", "type": "multi", "required": true, "min": 1, "max": 3, "multiple_selection": true, "is_pack_group": false, "is_global": false, "items": [ { "id": 44101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c01", "name": "Extra Chicken", "currency": "USD", "price": "3.00", "in_stock": true, "is_pack": false, "is_global": false }, { "id": 44102, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c02", "name": "Cornbread", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": false, "is_global": false } ], "items_count": 2, "items_truncated": false }, { "id": 9103, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b99", "title": "Takeaway Pack", "type": "single", "required": true, "min": 1, "max": 1, "multiple_selection": false, "is_pack_group": true, "is_global": false, "items": [ { "id": 44301, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c21", "name": "Standard Pack", "currency": "USD", "price": "1.00", "in_stock": true, "is_pack": true, "is_global": false }, { "id": 44302, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c22", "name": "Large Pack", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": true, "is_global": false } ], "items_count": 2, "items_truncated": false } ], "has_required_addon": true, "requires_packaging": true, "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } } ], "publications": [ { "id": 1001, "key": "kiosk-downtown", "name": "Downtown kiosk" } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null } ], "has_more": true, "next_cursor": "eyJpZCI6MjA0MTcsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-items-create.
Creates a product with variants, images, categories and metafields. seo is the search listing, {title, description} (plain text, up to 255 and 1000 characters): leave the key out to keep it, send an object to replace it, send null or blank values to clear it; the storefront then falls back to the title and the excerpt. Answers the created product — the same object GET products/{product} and products/* webhooks send.
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
multipart/form-data
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/products" \ -H "X-Client-Key: {{merchantKey}}" \ -F title="Smokehouse Party Pack" \ -F price="37.00" \ -F excerpt="Hickory-smoked chicken for 10, with cornbread and slaw." \ -F description="Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10." \ -F barcode="0012345102417" \ -F stock="42" \ -F track_inventory="true" \ -F taxable="true" \ -F metadata="{ \"erp_id\": \"ERP-20417\" }" \ -F image_url="https://northwindgoods.example/images/smokehouse-party-pack.jpg"{ "status": "success", "message": "product updated", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack", "excerpt": "Hickory-smoked chicken for 10, with cornbread and slaw.", "description": "Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "37.00", "storefront_price": "33.30", "storefront_compare_at_price": "37.00", "url": "https://northwindgoods.example/products/smokehouse-party-pack", "currency": "USD", "sku": "NWG-SPP-001", "barcode": "0012345102417", "stock": 42, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "variants": [], "options": [], "addons": [ { "id": 9101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77", "title": "Extra Toppings", "type": "multi", "required": true, "min": 1, "max": 3, "multiple_selection": true, "is_pack_group": false, "is_global": false, "items": [ { "id": 44101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c01", "name": "Extra Chicken", "currency": "USD", "price": "3.00", "in_stock": true, "is_pack": false, "is_global": false }, { "id": 44102, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c02", "name": "Cornbread", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": false, "is_global": false } ], "items_count": 2, "items_truncated": false }, { "id": 9103, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b99", "title": "Takeaway Pack", "type": "single", "required": true, "min": 1, "max": 1, "multiple_selection": false, "is_pack_group": true, "is_global": false, "items": [ { "id": 44301, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c21", "name": "Standard Pack", "currency": "USD", "price": "1.00", "in_stock": true, "is_pack": true, "is_global": false }, { "id": 44302, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c22", "name": "Large Pack", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": true, "is_global": false } ], "items_count": 2, "items_truncated": false } ], "has_required_addon": true, "requires_packaging": true, "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } } ], "publications": [], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-07-14T10:20:00+01:00", "deleted_at": null }}Requires scope merchant-items-read.
Searches this store’s shopper-visible products by keyword, availability or metafields. Results use storefront prices and cursor pagination. Keyword matching ignores letter case, and percent and underscore match themselves. publication narrows the search to one of the calling installation channel publications (p_id or key; human keys use p_id and need the publications-read permission, without it the filter answers 404; unknown or another app channel 404, archived 410), and a cursor is bound to that channel.
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
Match a shopper-visible product title, description or SKU (2 to 100 characters). Matching ignores letter case, and percent and underscore match themselves. Results use the selected sort, not relevance ranking.
2 <= length <= 100When true, include products with available inventory, including active variants. False or omitted leaves the full result set. The returned in_stock field is the stored product value and can differ from the variant-aware filter.
Value in
- "0"
- "1"
- "true"
- "false"
- null
Exact-match filter on metafields this store has defined, one namespace.key handle per entry: metafield[custom.fabric]=cotton. Up to 5 handles, each value at most 255 characters.
items <= 5Only products published to one of the calling installation's sales channels: its p_id or key. Another installation's or an unknown channel answers 404, an archived one 410. Without it the search is unchanged.
length <= 255Order of the results: latest (default), popular, price_low or price_high.
Value in
- "latest"
- "popular"
- "price_low"
- "price_high"
- null
Number of products per page, from 1 to 100 (default 50).
1 <= value <= 100Pass the previous page next_cursor unchanged to continue. A cursor from another filter or list is refused.
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/storefront/search?keyword=smokehouse&in_stock=1&sort=latest&limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Fresh Lemonade", "slug": "fresh-lemonade", "excerpt": "Fresh lemonade with mint and lemon slices.", "description": "Our house lemonade, mixed fresh every morning. Served chilled.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "5.00", "storefront_price": "5.00", "storefront_compare_at_price": null, "url": "https://northwindgoods.example/products/fresh-lemonade", "currency": "USD", "sku": "NWG-LEM-000", "barcode": null, "stock": 60, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": true, "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "variants": [ { "id": 7731, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "sku": "NWG-LEM-16OZ", "barcode": "0012345137001", "title": "16 oz", "option_values": { "Size": "16 oz" }, "currency": "USD", "price": "5.00", "storefront_price": "5.00", "storefront_compare_at_price": null, "url": "https://northwindgoods.example/products/fresh-lemonade?variant=7731", "compare_at_price": null, "stock": 36, "track_inventory": true, "is_digital": false, "storefront_available": true, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 0.55, "position": 0, "metafields": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" }, { "id": 7732, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "NWG-LEM-32OZ", "barcode": "0012345137002", "title": "32 oz", "option_values": { "Size": "32 oz" }, "currency": "USD", "price": "8.40", "storefront_price": "8.40", "storefront_compare_at_price": null, "url": "https://northwindgoods.example/products/fresh-lemonade?variant=7732", "compare_at_price": null, "stock": 24, "track_inventory": true, "is_digital": false, "storefront_available": true, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 1.05, "position": 1, "metafields": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" } ], "options": [ { "name": "Size", "position": 0, "values": [ "16 oz", "32 oz" ] } ], "addons": [], "has_required_addon": false, "requires_packaging": false, "images": [ { "id": 88220, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "alt": "Two bottles of chilled lemonade with lemon slices", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg", "width": null, "height": null } } ], "metafields": {}, "metadata": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null }, { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack", "excerpt": "Hickory-smoked chicken for 10, with cornbread and slaw.", "description": "Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "37.00", "storefront_price": "33.30", "storefront_compare_at_price": "37.00", "url": "https://northwindgoods.example/products/smokehouse-party-pack", "currency": "USD", "sku": "NWG-SPP-001", "barcode": "0012345102417", "stock": 42, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "variants": [], "options": [], "addons": [ { "id": 9101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77", "title": "Extra Toppings", "type": "multi", "required": true, "min": 1, "max": 3, "multiple_selection": true, "is_pack_group": false, "is_global": false, "items": [ { "id": 44101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c01", "name": "Extra Chicken", "currency": "USD", "price": "3.00", "in_stock": true, "is_pack": false, "is_global": false }, { "id": 44102, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c02", "name": "Cornbread", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": false, "is_global": false } ], "items_count": 2, "items_truncated": false }, { "id": 9103, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b99", "title": "Takeaway Pack", "type": "single", "required": true, "min": 1, "max": 1, "multiple_selection": false, "is_pack_group": true, "is_global": false, "items": [ { "id": 44301, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c21", "name": "Standard Pack", "currency": "USD", "price": "1.00", "in_stock": true, "is_pack": true, "is_global": false }, { "id": 44302, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c22", "name": "Large Pack", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": true, "is_global": false } ], "items_count": 2, "items_truncated": false } ], "has_required_addon": true, "requires_packaging": true, "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null } ], "has_more": true, "next_cursor": "WzEsIjhhNjI5NWU5MjA2MGZlZDBlZDhhYTI1M2ZhZWU4MjI2YmJhMWFhZWY4MmVlNDdmZDlhNjU2YjI0MWFjZGFlMDAiLCJleUp3Y205a2RXTjBjeTVqY21WaGRHVmtYMkYwSWpvaU1qQXlOaTB3TnkweE5DQXhNRG95TURvd01DSXNJbkJ5YjJSMVkzUnpMbWxrSWpvaU1ERTVZVEZrTlRJdE0yTTRaUzAzWmpReExXSXdaREl0Tm1FelpUbGpNV1kwWWpJeElpd2lYM0J2YVc1MGMxUnZUbVY0ZEVsMFpXMXpJanAwY25WbGZRIl0"}Requires scope merchant-items-detail.
Retrieves one product — the same object products/* webhooks send, with variants, images, the canonical URL and the storefront price. {product} is a p_id, UUID or slug of this store. cost_price (the unit cost, a money string or null when none was ever set) is present, on the product and on each variant, only with the protected merchant-items-cost-read scope. A variant has its own cost and a variant without one reads null, never the product’s. Costs older products had copied from the selling price were cleared where they could be identified.
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.
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/products/20417" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "product", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack", "excerpt": "Hickory-smoked chicken for 10, with cornbread and slaw.", "description": "Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "37.00", "storefront_price": "33.30", "storefront_compare_at_price": "37.00", "url": "https://northwindgoods.example/products/smokehouse-party-pack", "currency": "USD", "sku": "NWG-SPP-001", "barcode": "0012345102417", "stock": 42, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "variants": [], "options": [], "addons": [ { "id": 9101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77", "title": "Extra Toppings", "type": "multi", "required": true, "min": 1, "max": 3, "multiple_selection": true, "is_pack_group": false, "is_global": false, "items": [ { "id": 44101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c01", "name": "Extra Chicken", "currency": "USD", "price": "3.00", "in_stock": true, "is_pack": false, "is_global": false }, { "id": 44102, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c02", "name": "Cornbread", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": false, "is_global": false } ], "items_count": 2, "items_truncated": false }, { "id": 9103, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b99", "title": "Takeaway Pack", "type": "single", "required": true, "min": 1, "max": 1, "multiple_selection": false, "is_pack_group": true, "is_global": false, "items": [ { "id": 44301, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c21", "name": "Standard Pack", "currency": "USD", "price": "1.00", "in_stock": true, "is_pack": true, "is_global": false }, { "id": 44302, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c22", "name": "Large Pack", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": true, "is_global": false } ], "items_count": 2, "items_truncated": false } ], "has_required_addon": true, "requires_packaging": true, "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } } ], "publications": [ { "id": 1001, "key": "kiosk-downtown", "name": "Downtown kiosk" } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null }}Requires scope merchant-items-delete.
Deletes a 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.
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 DELETE "https://example.com/products/20417" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Product deleted successfully", "data": { "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "p_id": 20417, "deleted": true }}Requires scope merchant-items-update.
Replaces a product’s fields; title and the core attributes are required. Renaming never changes the product’s URL: slug is the URL handle (lowercase letters, digits and hyphens, up to 100, unique), send it only to change the address, and the old address then redirects to the new one automatically. seo is the search listing, {title, description} (plain text, up to 255 and 1000 characters): leave the key out to keep it, send an object to replace it, send null or blank values to clear it; the storefront then falls back to the title and the excerpt. Answers the updated product — the same object GET products/{product} and products/* webhooks send.
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.
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
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/products/20417" \ -H "X-Client-Key: {{merchantKey}}" \ -F title="Smokehouse Party Pack" \ -F price="37.00" \ -F excerpt="Hickory-smoked chicken for 10, with cornbread and slaw." \ -F description="Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10." \ -F barcode="0012345102417" \ -F stock="42" \ -F track_inventory="true" \ -F taxable="true" \ -F metadata="{ \"erp_id\": \"ERP-20417\" }"{ "status": "success", "message": "product updated", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack", "excerpt": "Hickory-smoked chicken for 10, with cornbread and slaw.", "description": "Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "37.00", "storefront_price": "33.30", "storefront_compare_at_price": "37.00", "url": "https://northwindgoods.example/products/smokehouse-party-pack", "currency": "USD", "sku": "NWG-SPP-001", "barcode": "0012345102417", "stock": 42, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "variants": [], "options": [], "addons": [ { "id": 9101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77", "title": "Extra Toppings", "type": "multi", "required": true, "min": 1, "max": 3, "multiple_selection": true, "is_pack_group": false, "is_global": false, "items": [ { "id": 44101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c01", "name": "Extra Chicken", "currency": "USD", "price": "3.00", "in_stock": true, "is_pack": false, "is_global": false }, { "id": 44102, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c02", "name": "Cornbread", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": false, "is_global": false } ], "items_count": 2, "items_truncated": false }, { "id": 9103, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b99", "title": "Takeaway Pack", "type": "single", "required": true, "min": 1, "max": 1, "multiple_selection": false, "is_pack_group": true, "is_global": false, "items": [ { "id": 44301, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c21", "name": "Standard Pack", "currency": "USD", "price": "1.00", "in_stock": true, "is_pack": true, "is_global": false }, { "id": 44302, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c22", "name": "Large Pack", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": true, "is_global": false } ], "items_count": 2, "items_truncated": false } ], "has_required_addon": true, "requires_packaging": true, "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } } ], "publications": [ { "id": 1001, "key": "kiosk-downtown", "name": "Downtown kiosk" } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null }}Requires scope merchant-metafields-update.
Writes metafield values on one product without resending the product: metafields is a list of {namespace, key, value}. Each handle needs a product metafield definition (create it with POST metafield-definitions first), values are type-checked, a handle you leave out keeps its value and "value": null deletes one. The platform namespaces app.* and queek.* are refused; an app-owned definition’s values (its app_{slug} namespace, see POST metafield-definitions) are written only by that app. Answers the updated product — the same object GET products/{product} sends; storefront-hidden merchant values appear in it only with merchant-metafields-read, and an app always reads its own app-owned values. Variant values have their own route, PATCH products/{product}/variants/{variant}/metafields, under the same scope. Does not move updated_at; sends one products/update webhook.
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.
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.
Metafield values of one product, or of one of its variants
(products/{product}/variants/{variant}/metafields), and nothing else, so an app
never resends (or overwrites) the rest of the product, and never needs the broad
item-update scope, to change its own fields. Each handle must have a definition
for that owner type and its value is type-checked; a handle you leave out keeps
its value and "value": null deletes one. The platform's dotted namespaces
(app.*, queek.*) are refused; an app-owned app_{slug} value is written only
by its app (MetafieldAccess). Any other field is rejected by name rather than ignored.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/products/20417/metafields" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "metafields": [ { "namespace": "custom", "key": "spice_level", "value": "Medium" }, { "namespace": "custom", "key": "allergen_note", "value": null } ] }'{ "status": "success", "message": "product updated", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Smokehouse Party Pack", "slug": "smokehouse-party-pack", "excerpt": "Hickory-smoked chicken for 10, with cornbread and slaw.", "description": "Hickory-smoked chicken cooked to order, served with cornbread and a tub of slaw. Feeds 10.", "seo": null, "status": "active", "published": true, "in_stock": true, "price": "37.00", "storefront_price": "33.30", "storefront_compare_at_price": "37.00", "url": "https://northwindgoods.example/products/smokehouse-party-pack", "currency": "USD", "sku": "NWG-SPP-001", "barcode": "0012345102417", "stock": 42, "track_inventory": true, "storefront_available": true, "is_online": false, "min_qty": null, "service_type": null, "is_digital": false, "taxable": true, "purchase_mode": "buy", "negotiable": false, "price_per": null, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "variants": [], "options": [], "addons": [ { "id": 9101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77", "title": "Extra Toppings", "type": "multi", "required": true, "min": 1, "max": 3, "multiple_selection": true, "is_pack_group": false, "is_global": false, "items": [ { "id": 44101, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c01", "name": "Extra Chicken", "currency": "USD", "price": "3.00", "in_stock": true, "is_pack": false, "is_global": false }, { "id": 44102, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c02", "name": "Cornbread", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": false, "is_global": false } ], "items_count": 2, "items_truncated": false }, { "id": 9103, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b99", "title": "Takeaway Pack", "type": "single", "required": true, "min": 1, "max": 1, "multiple_selection": false, "is_pack_group": true, "is_global": false, "items": [ { "id": 44301, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c21", "name": "Standard Pack", "currency": "USD", "price": "1.00", "in_stock": true, "is_pack": true, "is_global": false }, { "id": 44302, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c22", "name": "Large Pack", "currency": "USD", "price": "2.00", "in_stock": true, "is_pack": true, "is_global": false } ], "items_count": 2, "items_truncated": false } ], "has_required_addon": true, "requires_packaging": true, "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } } ], "publications": [ { "id": 1001, "key": "kiosk-downtown", "name": "Downtown kiosk" } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null }}Requires scope merchant-items-update.
Publishes or unpublishes a list of products in one call.
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
application/json
curl -X POST "https://example.com/products/publish" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22" ], "published": true }'{ "status": "success", "message": "2 products published successfully", "data": { "count": 2, "published": true }}