Variants
Requires scope merchant-items-detail.
Lists one product’s variants with the merchant price, the storefront price pair, and the canonical product URL.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product, as returned by the Merchant API.
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/products/20418/variants?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "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" } ], "has_more": true, "next_cursor": "eyJpZCI6NzczMiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-items-update.
Creates a variant on a product; answers the variant with the merchant price, the storefront price pair, and the canonical product URL.
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.
One variant of a shop product. title is not accepted: it is derived from the
option values ("Large / Red") by the variant service, as on every other writer.
metafields are the variant's typed custom fields, checked against the store's variant
definitions and saved with the variant: a key left out keeps its value, a null value clears it.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/products/20418/variants" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "option_values": { "Size": "32 oz" }, "sku": "NWG-LEM-32OZ", "barcode": "0012345137002", "price": "8.40", "stock": 24, "weight": 1.05, "position": 1 }'{ "status": "success", "message": "Variant created", "data": { "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-07-15T11:30:00+01:00" }}Requires scope merchant-items-update.
Updates a variant’s price, stock and attributes; answers the variant with the merchant price, the storefront price pair, and the canonical product URL.
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.
Identifier of the variant, 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.
Same fields as a new variant, every one optional: only what is sent changes.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/products/20418/variants/7732" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "price": "8.40", "stock": 24, "metafields": [ { "namespace": "custom", "key": "finish", "value": "matte" } ] }'{ "status": "success", "message": "Variant updated", "data": { "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" }}Requires scope merchant-items-update.
Deletes a variant. A product’s last variant cannot be deleted.
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.
Identifier of the variant, 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/20418/variants/7731" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Variant deleted", "data": { "id": 7731, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "deleted": true }}Requires scope merchant-metafields-update.
Writes metafield values on one variant without resending the variant, under the metafields scope (merchant-items-update is not needed): metafields is a list of {namespace, key, value}. Each handle needs a variant metafield definition (create it with POST metafield-definitions, owner_type variant), 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. {variant} is a variant p_id or UUID of {product}. Answers the updated product — the same object GET products/{product} sends, with the values on the variant in variants[]: a variant carries every merchant value (storefront_visible governs the storefront only) and, of app-owned values, only the calling app’s. 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.
Identifier of the variant, 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/20418/variants/7732/metafields" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "metafields": [ { "namespace": "custom", "key": "finish", "value": "matte" }, { "namespace": "custom", "key": "pack_note", "value": null } ] }'{ "status": "success", "message": "product updated", "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 }}