Menu

Product Categories API Routes

Products can be categorized into categories.

Categories are nested and their heirarchy can be managed, giving admin users flexibility in how they categorize their products.

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

GET /admin/product-categories#

List Product Categories

Retrieve a list of product categories. The product categories can be filtered by fields such as id. The product categories 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. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
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 -.
qstringOptional
Search term to filter on the product category's searchable properties.
idstring | string[]Optional
Filter by a product category's ID.
descriptionstring | string[]Optional
Filter by the category's description. This performs a full-text search. To do keyword search, use the q parameter instead.
handlestring | string[]Optional
Filter by a category's handle.
parent_category_idstring | string[]Optional
Filter by a parent category's ID to retrieve its child categories.
include_ancestors_treebooleanOptional
Whether to include the parent category of each category. If you enable this, add to the fields query parameter parent_category to set the parent of a category in this field. You can either pass *parent_category to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, fields=parent_category.id,parent_category.name.
include_descendants_treebooleanOptional
Whether to include the child categories of each category. If you enable this, add to the fields query parameter category_children to set the children of a category in this field. You can either pass *category_children to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, fields=category_children.id,category_children.name.
is_internalbooleanOptional
Filter by whether the category is internal.
is_activebooleanOptional
Filter by whether the category is active.
created_atobjectOptional
Filter by the category's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the category's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by the category's deletion 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 items.
countnumber
The total number of items.
product_categoriesobject[]
The list of product categories.
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/product-categories#

Create Product Category

Create a product category.

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. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
include_ancestors_treebooleanOptional
Whether to retrieve the category's parent. If you enable this, add to the fields query parameter parent_category to set the parent of a category in this field. You can either pass *parent_category to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, fields=parent_category.id,parent_category.name.
include_descendants_treebooleanOptional
Whether to retrieve a list of child categories. If you enable this, add to the fields query parameter category_children to set the child of a category in this field. You can either pass *category_children to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, fields=category_children.id,category_children.name.

Request body (application/json)

namestring
The product category's name.
descriptionstringOptional
The product category's description.
handlestringOptional
The product category's handle.
is_internalbooleanOptional
Whether the product category is only used and seen by admin users.
is_activebooleanOptional
Whether the product category is active.
parent_category_idstringOptional
The ID of a category that's the parent of this one.
ranknumberOptional
The sorting order of the product category among sibling categories.
metadataobjectOptional
The product category's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.
external_idstringOptional
The ID of the product category in an external or third-party system.

Request examples

Responses

200 OK

product_categoryobject
The product category's details.

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

Emitted events

  • product-category.created: Emitted when product categories are created.

GET /admin/product-categories/{id}#

Get a Product Category

Retrieve a product category by its ID. You can expand the product category's relations or select the fields that should be returned.

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

Path parameters

idstring
The product category'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. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
include_ancestors_treebooleanOptional
Whether to retrieve the category's parent. If you enable this, add to the fields query parameter parent_category to set the parent of a category in this field. You can either pass *parent_category to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, fields=parent_category.id,parent_category.name.
include_descendants_treebooleanOptional
Whether to retrieve a list of child categories. If you enable this, add to the fields query parameter category_children to set the children of a category in this field. You can either pass *category_children to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, fields=category_children.id,category_children.name.
is_internalbooleanOptional
Filter by whether the product category is internal.
is_activebooleanOptional
Filter by whether the product category is active.
qstringOptional
Apply a search query to the product category's searchable properties.
idstring | string[]Optional
Filter by the product category's ID.
descriptionstring | string[]Optional
Filter by the product category's description.
parent_category_idstring | string[]Optional
Retrieve the categories of a given parent category's ID.
handlestring | string[]Optional
Filter by the product category's handle.
created_atobjectOptional
Filter by the category's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the category's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by the category's deletion date. Accepts the filter operators.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a 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 -.
with_deletedbooleanOptional
The product category's with deleted.
$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.
external_idstring | string[]Optional
Filter by an external ID.

Request examples

Responses

200 OK

product_categoryobject
The product category's details.

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

POST /admin/product-categories/{id}#

Update a Product Category

Update a product category's details.

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

Path parameters

idstring
The product category'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. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
include_ancestors_treebooleanOptional
Whether to retrieve the category's parent. If you enable this, add to the fields query parameter parent_category to set the parent of a category in this field. You can either pass *parent_category to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, fields=parent_category.id,parent_category.name.
include_descendants_treebooleanOptional
Whether to retrieve a list of child categories. If you enable this, add to the fields query parameter category_children to set the child of a category in this field. You can either pass *category_children to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, fields=category_children.id,category_children.name.

Request body (application/json)

namestringOptional
The product category's name.
descriptionstringOptional
The product category's description.
handlestringOptional
The product category's handle. Must be a unique value.
is_internalbooleanOptional
Whether the product category is only used for internal purposes and shouldn't be shown the customer.
is_activebooleanOptional
Whether the product category is active.
parent_category_idstringOptional
The ID of a parent category.
metadataobjectOptional
The product category's metadata. Can hold custom key-value pairs. Learn more in the Manage Metadata section.
ranknumberOptional
The product category's rank among other categories.
external_idstringOptional
The product category's external ID used to link it with external systems.

Request examples

Responses

200 OK

product_categoryobject
The product category's details.

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

Emitted events

  • product-category.updated: Emitted when product categories are updated.

DELETE /admin/product-categories/{id}#

Delete a Product Category

Delete a product category. This doesn't delete the products in that category. A product category that has child categories can't be deleted, so you must delete its child categories first.

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

Path parameters

idstring
The product category's ID.

Request examples

Responses

200 OK

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

Default: "product_category"

deletedboolean
Whether the product category was deleted.

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

Emitted events

  • product-category.deleted: Emitted when product categories are deleted.

POST /admin/product-categories/{id}/products#

Manage Products in Product Category

Manage products of a category to add or remove them.

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

Path parameters

idstring
The product category'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. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the Retrieve Custom Links documentation.
include_ancestors_treebooleanOptional
Whether to retrieve the category's parent. If you enable this, add to the fields query parameter parent_category to set the parent of a category in this field. You can either pass *parent_category to retreieve the fields of all parent categories, or select specific fields to make the response size smaller. For example, fields=parent_category.id,parent_category.name.
include_descendants_treebooleanOptional
Whether to retrieve a list of child categories. If you enable this, add to the fields query parameter category_children to set the child of a category in this field. You can either pass *category_children to retreieve the fields of all child categories, or select specific fields to make the response size smaller. For example, fields=category_children.id,category_children.name.

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

product_categoryobject
The product category'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