Skip to main content
A category is where a product lives in the catalog — Men → Kaftan. The taxonomy is one level deep: a top-level category may have children, and a child never has children of its own. Every category has a workspace-unique slug (like kaftan) that you can use anywhere an id is accepted. Categories ride the product scope, since they’re product metadata.
Categories differ from the other two ways to group products. A category is taxonomy (where a product belongs), a tag is a free-form label, and a collection is merchandising (a storefront grouping, hand-picked or rule-driven).

​
Reading the taxonomy

The list is not paginated — a taxonomy is small and meant to be fetched whole:
Build the tree client-side: a category with parent: null is a root, and every other category is a child of the parent id (parent_slug is there so you can render a breadcrumb without a second lookup).

​
product_count

product_count rolls up the category and its children, counting each product once. A product filed under both Men and Kaftan adds 1 to Men, not 2. It counts raw membership, so it includes products a storefront wouldn’t show (drafts, hidden). For a buyable count, filter the products endpoint instead — see below.

​
Filtering products by category

Pass slugs (or ids) to GET /products:
Multiple terms AND together, and each term rolls up to include its children. GET /products defaults to status=ACTIVE, so this is also how you get a storefront-accurate count — read total from the page. An unrecognized term yields an empty page, never an error.

​
Filing a product

There are no category write endpoints on the public API — categories are managed in the dashboard. You assign them when you write a product, by slug or id, with the first entry as the primary category:
categories replaces the product’s whole category set ([] clears it). An unknown slug or id fails the write with 422 unprocessable and nothing is applied — so read the taxonomy first when you’re mapping an external catalog onto it.

​
Good to know

  • Slugs are stable addresses; names are not. Address categories by slug (or id) in stored mappings — a merchant renaming a category doesn’t change its slug.
  • A UUID in the path wins. If a path segment is a UUID, it’s matched as an id first, then as a slug.
  • One level, always. If you’re modelling a deeper tree from another platform, flatten it — a child category can’t take children.
See the Commerce API reference for every field and status code.