Menu

Collections API Routes

A product collection organizes products into a collection for marketing purposes. For example, a summer collection.

These API routes allow admin users to manage collections and the products in them.

GET /admin/collections#

List Collections

Retrieve a list of collections. The collections can be filtered by fields such as id. The collections can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
deleted_atobjectOptional
Filter by the collection's deletion date. Accepts the filter operators.
qstringOptional
Search term to filter the collection's searchable properties by.
idstring | string[]Optional
Filter by a collection's ID.
handlestring | string[]Optional
Filter by a collection's handle.
titlestring | string[]Optional
Filter by a collection's title.
created_atobjectOptional
Filter by the collection's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the collection's update date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.
external_idstring | string[]Optional
Filter by an external ID.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned results.
countnumber
The total number of items.
collectionsobject[]
The list of product collections.
estimate_countnumberOptional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/collections#

Create Collection

Create a collection.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

titlestring
The collection's title.
handlestringOptional
The collection's handle.
metadataobjectOptional
The collection's metadata. Can hold custom key-value pairs.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

collectionobject
The product collection's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-collection.created: Emitted when product collections are created.

GET /admin/collections/{id}#

Get a Collection

Retrieve a collection by its ID. You can expand the collection's relations or select the fields that should be returned using the query parameters.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The collection's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

collectionobject
The product collection's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/collections/{id}#

Update a Collection

Update a collection's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The collection's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

titlestringOptional
The collection's title.
handlestringOptional
The collection's handle.
metadataobjectOptional
The collection's metadata.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

collectionobject
The product collection's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-collection.updated: Emitted when product collections are updated.

DELETE /admin/collections/{id}#

Delete a Collection

Delete a product collection.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The collection's ID.

Request examples

Responses

200 OK

idstring
The collection's ID.
objectstring
The name of the deleted object.

Default: "collection"

deletedboolean
Whether the collection was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-collection.deleted: Emitted when product collections are deleted.

POST /admin/collections/{id}/products#

Manage Products of a Collection

Manage the products of a collection by adding or removing them from the collection.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The collection's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

addstring[]Optional
The IDs of an entity to add to the other.
removestring[]Optional
The IDs of an entity to remove from the other.

Request examples

Responses

200 OK

collectionobject
The product collection's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product.updated: Emitted when products are updated.
Found a problem with this page?Report Issue
Edited Nov 14·Edit this page