GET /taxonomy/categories walks StoreRouter’s canonical product taxonomy, the category tree that enrichment assigns every indexed product to. Without parent, it returns the root categories. With parent, it returns that category’s direct children.
Each category includes the facets that select it. Send them unchanged in facets on POST /products/search, or as a category on POST /products/facet-counts.
These are canonical definitions, not inventory. A category listed here may hold no products in your catalog scope. Use
POST /products/facet-counts to count matching products./v1 route.
Request
Query parameters
The category whose children to list. Omit it to list root categories. Accepts any of these forms:
- A category UUID, such as
9af8b8a5-b1d0-48a1-9d30-93c2877d2621. - A section handle:
apparel,beauty,furniture,home_garden, ormedia. - A category path, root first and separated by
>, in any letter case, such asApparel & Accessories > Clothing.
category_path.depth_N values joined with > also name their category.Response
Offset of the next page. Repeat the request with it as
offset. null on the last page.Example response
Errors
See the overview for authentication and rate-limit errors.
Next steps
- List a category’s attributes with
GET /taxonomy/attributes. - Count the products in each category with
POST /products/facet-counts.
listTaxonomyCategories. SDK methods: Python list_taxonomy_categories(parent=..., offset=..., limit=...); TypeScript listTaxonomyCategories({ parent, offset, limit }). The MCP equivalent is taxonomy_tree.