Queek docs
Merchant endpoint reference

Add ons

GET
/addon-groups

Requires scope merchant-options-read.

Lists this store’s add-on groups with cursor pagination (limit + starting_after, has_more/next_cursor; at most 25 per page). Each group carries at most 20 items with items_count/items_truncated beside them — read the group itself for the full member list before patching it. Only the store’s own groups ever list: a shared group is attach-only by ref and never appears here.

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 <= 25
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

curl -X GET "https://example.com/addon-groups?limit=2" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "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    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6OTEwMiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}
POST
/addon-groups

Requires scope merchant-options-create.

Creates an add-on group with 1–200 item definitions (whole-number prices); answers the created group with a 201. min/max/required/multiple_selection must cohere and max is at least 1.

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.

The single add-on group rows (retrieve/create/update/delete). {group} is this store's p_id or UUID, resolved in authorize() — after the scope gate, before any rule — so a foreign, global or missing id is the standard 404 and never learns what the body would have failed. No route where: a non-numeric ref resolves to nothing (never a Postgres cast 500).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/addon-groups" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "title": "Extra Toppings",    "required": true,    "min": 1,    "max": 3,    "multiple_selection": true,    "items": [      {        "name": "Extra Chicken",        "price": 3      },      {        "name": "Cornbread",        "price": 2      }    ]  }'
{  "status": "success",  "message": "Add-on group created",  "data": {    "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  }}
GET
/addon-groups/{group}

Requires scope merchant-options-detail.

Retrieves one add-on group with every member item — the read-before-PATCH source of member ids. {group} is this store’s p_id or UUID; a foreign, shared or missing id is 404.

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

group*string

Identifier of the add-on group, 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/addon-groups/9101" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Add-on group",  "data": {    "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  }}
PATCH
/addon-groups/{group}

Requires scope merchant-options-update.

Patches an add-on group’s scalars and member items: id entries keep members, definition entries create them, omitted members detach (shared members pass through) and an empty items array echoes. Only carried scalars are re-validated, merged over the stored values.

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

group*string

Identifier of the add-on group, 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.

The single add-on group rows (retrieve/create/update/delete). {group} is this store's p_id or UUID, resolved in authorize() — after the scope gate, before any rule — so a foreign, global or missing id is the standard 404 and never learns what the body would have failed. No route where: a non-numeric ref resolves to nothing (never a Postgres cast 500).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/addon-groups/9101" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "title": "Extra Toppings and Sides",    "items": [      {        "id": 44101      },      {        "name": "Coleslaw",        "price": 1      }    ]  }'
{  "status": "success",  "message": "Add-on group updated",  "data": {    "id": 9101,    "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77",    "title": "Extra Toppings and Sides",    "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  }}
DELETE
/addon-groups/{group}

Requires scope merchant-options-delete.

Deletes an add-on group; answers its ids with deleted: true. Item rows survive.

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

group*string

Identifier of the add-on group, 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/addon-groups/9101" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Add-on group deleted",  "data": {    "id": 9101,    "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b77",    "deleted": true  }}
POST
/products/{product}/addons

Requires scope merchant-options-update.

Hangs up to 200 of this store’s (or shared) add-on groups on a product without detaching what is there; a product that sells through variants is refused with 422. Answers the product’s ids plus its add-ons. A shared group’s p_id arrives outside the API (shared groups never list or retrieve) — hang it by ref.

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.

Attach (POST) and detach (DELETE) add-on groups on one product. {product} is this store's p_id, UUID or slug; the detach {group} must already hang on the product — anything else is the standard 404. Attach refs resolve to this store's groups or shared (global) ones; unresolvable refs and a variant product fail the body with 422, never a 500.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/products/20417/addons" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "groups": [      9101    ]  }'
{  "status": "success",  "message": "Add-ons attached",  "data": {    "id": 20417,    "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",    "addons": [      {        "id": 9102,        "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b88",        "title": "Festival Gift Wrap",        "type": "single",        "required": false,        "min": 0,        "max": 1,        "multiple_selection": false,        "is_pack_group": false,        "is_global": true,        "items": [          {            "id": 44201,            "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4c11",            "name": "Gift Box",            "currency": "USD",            "price": "5.00",            "in_stock": true,            "is_pack": false,            "is_global": false          }        ],        "items_count": 1,        "items_truncated": false      }    ]  }}
DELETE
/products/{product}/addons/{group}

Requires scope merchant-options-update.

Unhangs one add-on group from a product; a group that is not on the product is 404. Answers the product’s ids plus its remaining add-ons.

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.

group*string

Identifier of the add-on group, 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/20417/addons/9101" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Add-ons detached",  "data": {    "id": 20417,    "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",    "addons": []  }}