Collections
Requires scope merchant-collections-read.
Lists the store’s collections. publication scopes the list to one of the calling installation’s channel publications (p_id or key; human keys use p_id and need the publications-read permission, without it the filter answers 404): the walk returns published collections as roots with published descendants in children; a published child of an unpublished parent is a root — re-list to reconcile removals. The product ∩ contract (collection_category_id with GET products?publication=) covers MANUAL collections only — a smart collection’s rule-computed membership is not listable through the Merchant API.
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.
Narrow the list to hand-picked (manual) or rule-driven (smart) collections. Omit it, or send any other value such as all, to list both.
Free-text filter: only items matching this text are returned.
length <= 255Field to sort the list by.
Sort direction. One of asc, desc.
Value in
- "asc"
- "desc"
- null
Only collections published to this sales channel: a channel id, or an app key's own channel key. Unknown channel 404, archived 410.
length <= 255Header 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/collections?limit=2&starting_after=eyJpZCI6MzEwOSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ&collection_mode=all" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 3108, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "name": "Party Packs", "slug": "party-packs", "description": "Trays that feed a crowd.", "seo": null, "image": "https://media.usequeek.com/uploads/stores/1095/collections/party-packs.jpg", "logo": null, "featured": true, "position": 1, "collection_mode": "manual", "parent_uid": null, "products_count": 6, "metafields": {}, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-09-20T09:15:00+01:00" }, { "id": 3109, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b22", "name": "Drinks", "slug": "drinks", "description": "Lemonade, iced tea and fresh juices.", "seo": null, "image": null, "logo": null, "featured": false, "position": 2, "collection_mode": "smart", "parent_uid": null, "products_count": 3, "metafields": {}, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-09-20T09:15:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6MzEwOSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-collections-detail.
Retrieves one of the store’s collections — the same object collections list returns, with its metafields (the store’s custom fields on it, every definition) and without the smart-collection rule set. {collection} is a p_id, UUID or slug of this store.
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 collection, 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/collections/3108" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "collection", "data": { "id": 3108, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "name": "Party Packs", "slug": "party-packs", "description": "Trays that feed a crowd.", "seo": null, "image": "https://media.usequeek.com/uploads/stores/1095/collections/party-packs.jpg", "logo": null, "featured": true, "position": 1, "collection_mode": "manual", "parent_uid": null, "products_count": 6, "metafields": {}, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-09-20T09:15:00+01:00" }}Requires scope merchant-collections-update.
Replaces a collection’s fields; name is required. Renaming never changes the collection’s URL: slug is the URL handle (lowercase letters, digits and hyphens, up to 100, unique in the store), 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 name and the description. metafields is a list of {namespace, key, value} checked against the store’s collection definitions: a null value clears one, a key left out keeps its value, and an undefined handle answers 422. Answers the updated collection — the same object GET collections/{collection} returns.
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 collection, 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.
Create or update ONE of the store's collections (dashboard vendor/categories, Merchant API
PUT collections/{collection}). metafields are the collection's typed custom fields, checked
against the store's collection definitions and saved together with the collection.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/collections/3108" \ -H "X-Client-Key: {{merchantKey}}" \ -F name="Party Packs" \ -F description="Trays that feed a crowd." \ -F featured="true" \ -F metafields="[ { \"namespace\": \"custom\", \"key\": \"banner_text\", \"value\": \"Feeds 10 or more\" } ]"{ "status": "success", "message": "collection updated", "data": { "id": 3108, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "name": "Party Packs", "slug": "party-packs", "description": "Trays that feed a crowd.", "seo": null, "image": "https://media.usequeek.com/uploads/stores/1095/collections/party-packs.jpg", "logo": null, "featured": true, "position": 1, "collection_mode": "manual", "parent_uid": null, "products_count": 6, "metafields": {}, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-09-20T09:15:00+01:00" }}Requires scope merchant-collections-create.
Creates several collections in one call; each may carry a seo listing, {title, description}.
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.
A bulk create makes bare collections: custom fields (metafields) are NOT part of it and are
refused, not silently dropped. Set them with PUT collections/{collection} once the row exists.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/collections/bulk" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "collections": [ { "name": "On sale", "description": "Products currently on sale.", "collection_mode": "smart", "collection_rules": { "match": "all", "conditions": [ { "field": "compare_at_price", "operator": "gt", "value": 0 }, { "field": "on_sale", "operator": "eq", "value": true } ], "sort": "price_low", "limit": 50 } } ] }'{ "data": [ { "id": 3109, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b22", "name": "Drinks", "slug": "drinks", "description": "Lemonade, iced tea and fresh juices.", "seo": null, "image": null, "logo": null, "featured": false, "position": 2, "collection_mode": "smart", "parent_uid": null, "products_count": 3, "metafields": {}, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-07-01T12:00:00+01:00" } ], "success": true, "message": "Collections created successfully"}Requires scope merchant-collections-update.
Pins a product to the top of a manual collection.
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 collection, 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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/collections/3108/products/pin" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "product_id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "pinned": true }'{ "status": "success", "message": "Product pinned in collection.", "data": { "collection_id": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "product_id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "pinned": true }}Requires scope merchant-collections-update.
Reorders the products of a manual collection.
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 collection, 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.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/collections/3108/products/reorder" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "product_ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b23" ] }'{ "status": "success", "message": "Collection products reordered successfully.", "data": { "collection_id": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "ordered_count": 2 }}