Menu

Product Categories API Routes

Products can be categorized into categories.

These API routes allow customers to browse categories and their products.

GET /store/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: none.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

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 -.
qstringOptional
Search term to filter the product category's properties.
idstring | string[]Optional
Filter by a product category's ID.
descriptionstring | string[]Optional
Filter by a description. This only matches categories with the exact description. To search by a term or keyword, use the q query parameter instead.
handlestring | string[]Optional
Filter by a category's handle.
parent_category_idstring | string[]Optional
The ID of a category to retrieve its child categories.
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.
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.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
The product category's $or.
namestring | string[]Optional
Filter by a product category name.
with_deletedbooleanOptional
Whether to include deleted records in the result.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US
external_idstring | string[]Optional
Filter by a product category's 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.

GET /store/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: none.

Path parameters

idstring
The product category's ID.

Header parameters

x-publishable-api-keystring
Publishable API Key created in the Medusa Admin.
x-medusa-localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

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.
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.
localestringOptional
The locale in BCP 47 format to retrieve localized content.
Example: en-US

Request examples

Responses

200 OK

product_categoryobject
The category's details.

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

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page