Add ons
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 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 <= 25Cursor 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
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"}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 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.
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 }}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 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 add-on group, 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/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 }}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 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 add-on group, 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.
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 }}Requires scope merchant-options-delete.
Deletes an add-on group; answers its ids with deleted: true. Item rows survive.
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 add-on group, 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/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 }}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 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.
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 } ] }}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 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 add-on group, 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/addons/9101" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Add-ons detached", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "addons": [] }}