Queek docs
Merchant endpoint reference

Collections

GET
/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
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 <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

collection_mode?|

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.

search?|

Free-text filter: only items matching this text are returned.

Lengthlength <= 255
sort_by?|

Field to sort the list by.

sort_order?|

Sort direction. One of asc, desc.

Value in

  • "asc"
  • "desc"
  • null
publication?|

Only collections published to this sales channel: a channel id, or an app key's own channel key. Unknown channel 404, archived 410.

Lengthlength <= 255

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/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"}
GET
/collections/{collection}

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

collection*string

Identifier of the collection, 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/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"  }}
PUT
/collections/{collection}

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

collection*string

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

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"  }}
POST
/collections/bulk

Requires scope merchant-collections-create.

Creates several collections in one call; each may carry a seo listing, {title, description}.

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.

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"}
POST
/collections/{collection}/products/pin

Requires scope merchant-collections-update.

Pins a product to the top of a manual collection.

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

collection*string

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

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  }}
POST
/collections/{collection}/products/reorder

Requires scope merchant-collections-update.

Reorders the products of a manual collection.

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

collection*string

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

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