Skip to main content
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.
This endpoint is not billed. It is rate limited like every /v1 route.

Request

Query parameters

string
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, or media.
  • A category path, root first and separated by >, in any letter case, such as Apparel & Accessories > Clothing.
The lowercase category_path.depth_N values joined with > also name their category.
integer
default:"0"
Number of categories to skip. Use the previous page’s nextOffset.
integer
default:"25"
Categories per page, from 1 to 50.

Response

string
required
Canonical taxonomy version name, such as v4.
TaxonomyCategory | null
required
The requested parent category. null when listing root categories.
TaxonomyCategory[]
required
This page of categories.
integer
required
Number of categories across all pages.
integer | null
required
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

Operation ID: listTaxonomyCategories. SDK methods: Python list_taxonomy_categories(parent=..., offset=..., limit=...); TypeScript listTaxonomyCategories({ parent, offset, limit }). The MCP equivalent is taxonomy_tree.