Queek docs
Merchant endpoint reference

Variants

GET
/products/{product}/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
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.

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/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"}
POST
/products/{product}/variants

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
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.

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.

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"  }}
PATCH
/products/{product}/variants/{variant}

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
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.

variant*string

Identifier of the variant, 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.

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"  }}
DELETE
/products/{product}/variants/{variant}

Requires scope merchant-items-update.

Deletes a variant. A product’s last variant cannot be deleted.

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.

variant*string

Identifier of the variant, 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 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  }}
PATCH
/products/{product}/variants/{variant}/metafields

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
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.

variant*string

Identifier of the variant, 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.

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  }}