Product Collection
Private Product Collection API endpoints
- GET/products/collections
- POST/products/collections
- GET/products/collections/{collection_id}
- PUT/products/collections/{collection_id}
- POST/products/collections/{collection_id}/publish
- POST/products/collections/{collection_id}/unpublish
- POST/products/collections/{collection_id}/archive
- GET/products/collections/{collection_id}/items
- POST/products/collections/{collection_id}/items
Query parameters
pageoptionalintegerPage number for pagination
per_pageoptionalintegerItems per page
ids[]optionalinteger[]Filter by collection IDs
slugs[]optionalstring[]Filter by collection slugs
publishedoptionalbooleanFilter by published status
typeoptionalstring | nullFilter by collection type
sort[field]optionalstringField to sort by. Required whenever any sort[...] key is sent; passing sort[direction] without sort[field] returns 422.
Possible values: id, name.
sort[direction]optionalstringSort direction; defaults to asc.
Possible values: asc, desc.
Defaults to "asc".
Returnsobject
Product collections list response
Error responses
422objectA query parameter fails validation. ids[] or slugs[] is not an array of unique values (ids[] integers, slugs up to 80 characters); published is not a boolean; type is over 50 characters; page is below 1; per_page is outside 1 to 100; sort is not an object, sort[field] is missing or not id or name, or sort[direction] is not asc or desc; or expand is not an array.
Request body
nameRequiredstringslugRequiredstringMust be unique among the shop's product collections. A slug already in use returns 422.
typeoptionalstring | nullitemsoptionalobject | nullReturnsProductCollection
Product collection created
Error responses
422objectname or slug is missing, name is over 255 characters, slug is over 70 characters or already used by a collection of the shop, type is over 50 characters, or an items.create entry has no integer variant_id or a negative position.
Path parameters
collection_idRequiredintegerCollection ID
ReturnsProductCollection
Product collection response
Error responses
400objectThe collection is archived.
Path parameters
collection_idRequiredintegerCollection ID
Request body
nameoptionalstringslugoptionalstringMust be unique among the shop's product collections, ignoring this collection itself. A slug used by another collection returns 422.
ReturnsProductCollection
Product collection updated
Error responses
400objectThe collection is archived.
Path parameters
collection_idRequiredintegerCollection ID
ReturnsProductCollection
Product collection published
Error responses
400objectThe collection has no items, or the collection is archived.
Path parameters
collection_idRequiredintegerCollection ID
ReturnsProductCollection
Product collection unpublished
Error responses
400objectThe collection is archived.
Path parameters
collection_idRequiredintegerCollection ID
ReturnsProductCollection
Product collection archived
Error responses
400objectThe collection is archived, so archiving is not idempotent.
Lists the collection's groups, each with its items. Returns 400 entity_archived if the collection is archived.
expand[]: List of relations to expand. product expands the group's parent product. items is always returned; use items.variant to expand each item's variant.
Path parameters
collection_idRequiredintegerCollection ID
Query parameters
pageoptionalintegerPage number for pagination
Defaults to 1.
per_pageoptionalintegerGroups per page; each group carries all of its items.
Defaults to 10.
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Returnsobject
Collection groups list response
Error responses
400objectThe collection is archived (entity_archived).
404objectNo collection exists with this ID, or it belongs to another shop.
422objectpage is below 1, per_page is outside 1 to 100, or expand is not an array.
Create, update, and delete collection items in a single request. Operations run in the order delete, update, create. Returns 400 entity_archived if the collection is archived, and collection_empty if the request would leave a published collection with no items. All three arrays are optional; an empty body is a no-op that returns the current groups. Entries whose id is not part of this collection, and create entries whose variant_id does not resolve to a product, are skipped silently and the request still returns 200. Compare the returned groups against what you sent to confirm.
Path parameters
collection_idRequiredintegerCollection ID
Request body
createoptionalobject[]updateoptionalobject[]deleteoptionalobject[]idRequiredintegerReturnsobject
Collection groups with synced items. Always returns the first page of groups (up to 100) with items expanded. The expand parameter is not supported on this operation, so product is never expanded here; call GET /products/collections/{collection_id}/items to expand it.
Error responses
400objectThe collection is archived (entity_archived), or the sync would leave a published collection with no items (collection_empty).
404objectNo collection exists with this ID, or it belongs to another shop.
422objectcreate, update or delete is not an array; a create entry has no integer variant_id; an update or delete entry has no integer id; a group_id is not an integer; or a position is negative.