TaxonomyService class (accessed via client.taxonomy) allows you to browse and retrieve the hierarchical structure of your store’s product catalog. Each resource supports an image field for building visual navigation menus and category-based landing pages, and a slug for addressing it in a URL.
Slugs
Every category and subcategory carries aslug alongside its id — a lowercase, URL-safe
identifier such as electronics, audio-headphones or computer-peripherals. A slug is
stable across renames: editing a category’s display name leaves its slug untouched, so a
category-page URL built from a slug keeps resolving and keeps its search ranking.
Categories are a fixed, platform-wide set, so a given category slug identifies the same category
in every store — electronics means the same thing everywhere, which makes it safe to hard-code
in routes or share across storefronts. Subcategory slugs are unique within their store, category
and parent; where two names in that scope would reduce to the same slug, a numeric suffix
distinguishes them.
Slugs address a resource; id remains the value the filter and lookup parameters take.
Category Management
listCategories
Retrieve all top-level product categories. This is the starting point for building navigation menus or mega-menus.
Response
getCategory
Retrieve details for a single category, including its description and metadata.
Response
Subcategory Management
Subcategories allow for more granular organization within a parent category (e.g., “Laptops” inside “Electronics”). Subcategories can be nested to arbitrary depth. Each subcategory has aparent_id:
null means it sits directly under its category, while a non-null parent_id points to
another subcategory — letting you model hierarchies like Shoes → Men's → Sneakers.
listSubcategories
Retrieve subcategories. By default this returns a flat, paginated list, which you can scope
to a parent category and include images for each.
Response
Response
tree marker confirms the hierarchy was returned. Because nesting is opt-in and a flat list
arrives as the same subcategories array, a bare array is ambiguous: a first page of flat results
is indistinguishable from a complete forest, and a navigation menu built from one silently omits
most of the catalog. Checking tree === true before rendering a hierarchy rules that out. A tree
response carries no pagination object.
Fetching one level at a time lazy-loads the hierarchy as the shopper drills in:
Response
getSubcategory
Retrieve details for a specific subcategory.
Response
"type": "category" and an empty ancestors
array. An ID that matches neither returns 404.
One call therefore resolves an ID at either level, which is what a breadcrumb walk needs: following
parent_id upward eventually arrives at a category, and the same lookup handles that final hop.
Response
include: 'children' to receive the subcategory’s direct child subcategories
(one level down) nested under a children array — handy for lazily expanding a single node
as the shopper drills into your navigation. The array is empty for a leaf subcategory.
Response
include: 'children' returns only the immediate children. To pull a whole multi-level
hierarchy in one call, use listSubcategories({ tree: true }) instead.include: 'ancestors' to receive the full trail above a subcategory as an ancestors array
ordered root-first: the owning category comes first, followed by the subcategory chain down to
the immediate parent. That is the complete shape a breadcrumb needs
(Home › Wearables › Clothing › Hoodies), with the category included so the trail reaches the top
of the hierarchy. A top-level subcategory returns a single entry — its category.
Each entry carries a type of either "category" or "subcategory". The two are separate
resources served by separate endpoints (/v1/categories and /v1/subcategories), so a client
turning a crumb into a link or a follow-up lookup reads type to know which it holds.
Response
The first
ancestors entry is always the owning category, so a breadcrumb rendered from
[...node.ancestors, node] starts at the top of the catalog rather than at the node’s
top-level subcategory.include: 'ancestors,children' returns the node with
both its breadcrumb trail and its direct children, enough to render a full category page
(breadcrumb + sub-navigation) from a single call.
Browsing Products
Once you have a category or subcategory ID, you can use it to filter products using theProductsService.
Filter by Category
ProductsService for the full product row shape.
Filter by Subcategory
Filtering products by a subcategory automatically includes products in all of its nested
subcategories. Requesting products for
Shoes returns everything filed under
Shoes → Men's → Sneakers as well, so a single call powers a parent-category landing page.Combined Hierarchical Filter
Response Codes
All taxonomy endpoints areGET and accept both publishable and secret keys.