Taxonomy (Categories)

The 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.

Category Management

Retrieve all top-level product categories. This is the starting point for building navigation menus or mega-menus.

const { categories, pagination } = await client.taxonomy.listCategories({
  search: 'audio',
  active: true,
  limit: 50,
  fields: 'id,name,image'
});
// → { id: "c7f18400-eec6-448d-a599-cf871cf80b31", name: "Audio & Headphones",
//     active: true, image: "https://..." }

console.log(`Has more categories: ${pagination.has_more}`);

`getCategory`

Retrieve details for a single category, including its description and metadata.

const category = await client.taxonomy.getCategory({
  id: '28186b12-5790-4a50-ab87-a7b70d301d00', // e.g. "Bags & Accessories"
  fields: 'name,description,image' // Optional
});

console.log(`Category Banner: ${category.image}`);
// → {
//     id: "28186b12-5790-4a50-ab87-a7b70d301d00",
//     name: "Bags & Accessories",
//     description: "Handbags, wallets, belts",
//     active: true,
//     image: "https://images.unsplash.com/photo-1553062407-98eeb64c6a62?w=800&q=80",
//     created_at: "2026-06-19T20:07:35.277495+00:00",
//     updated_at: "2026-06-20T10:11:03.932255+00:00"
//   }

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 a parent_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.

const { subcategories, pagination } = await client.taxonomy.listSubcategories({
  categoryId: 'electronics-uuid',
  active: true,
  search: 'laptops',
  limit: 24,
  fields: 'id,name,category_id,image'
});

Response

{
  "subcategories": [
    {
      "id": "690804ac-0cdc-4d3e-9b84-e18475fe6d16",
      "name": "T-Shirts",
      "description": "Graphic and plain tees",
      "category_id": "de4df100-8080-4a32-9987-8480f0233f1b",
      "active": true,
      "image": "https://images.unsplash.com/...",
      "parent_id": null,
      "created_at": "2026-06-20T10:19:02.864081+00:00",
      "updated_at": "2026-06-20T12:13:59.35115+00:00"
    },
    {
      "id": "58061675-bdbe-4ea7-94e9-8d13b1ac61fa",
      "name": "Graphic Tees",
      "description": "Printed graphic t-shirts",
      "category_id": "de4df100-8080-4a32-9987-8480f0233f1b",
      "active": true,
      "image": null,
      "parent_id": "690804ac-0cdc-4d3e-9b84-e18475fe6d16",
      "created_at": "2026-06-20T10:22:14.206787+00:00",
      "updated_at": "2026-06-20T10:22:14.206787+00:00"
    }
  ],
  "pagination": { "limit": 24, "next_cursor": null, "has_more": false }
}

Working with the hierarchy

Option	Type	Description
`tree`	`boolean`	Return subcategories as a nested hierarchy. Each subcategory includes a `children` array of its nested subcategories. The response is not paginated in this mode — the full tree is returned in one call.
`rootOnly`	`boolean`	Return only top-level subcategories (those with no parent). Ideal for rendering the first level of a category’s menu.
`parentId`	`string`	Return only the direct children of the given subcategory. Pass `"null"` to return only top-level subcategories.

// Fetch the full nested hierarchy for a category
const { subcategories } = await client.taxonomy.listSubcategories({
  categoryId: 'apparel-uuid',
  tree: true,
});
// [
//   { id: 'shoes', name: 'Shoes', parent_id: null, children: [
//       { id: 'mens', name: "Men's", parent_id: 'shoes', children: [
//           { id: 'sneakers', name: 'Sneakers', parent_id: 'mens', children: [] }
//       ] }
//   ] }
// ]

// Or fetch one level at a time, lazy-loading as the shopper drills in:
const roots = await client.taxonomy.listSubcategories({ categoryId: 'apparel-uuid', rootOnly: true });
// → { subcategories: [ { id: 'shoes', name: 'Shoes', parent_id: null, ... } ], pagination: {...} }
const children = await client.taxonomy.listSubcategories({ parentId: 'shoes' });
// → { subcategories: [ { id: 'mens', name: "Men's", parent_id: 'shoes', ... } ], pagination: {...} }

`getSubcategory`

Retrieve details for a specific subcategory.

const sub = await client.taxonomy.getSubcategory({
  id: 'macbooks-uuid',
  fields: 'name,description,image' // Optional
});

Response

{
  "id": "6dbda630-ad89-4659-a5ef-3b0aae0dba7b",
  "name": "Keyboards",
  "description": "Mechanical and compact keyboards",
  "category_id": "7bf671dd-f49e-492c-b89f-a2892931f88f",
  "active": true,
  "image": "https://images.unsplash.com/photo-1587829741301-dc798b83add3?w=800&q=80",
  "parent_id": "c62e2103-7bf1-4dc3-996d-22f937d42147",
  "created_at": "2026-06-20T10:19:02.864081+00:00",
  "updated_at": "2026-06-20T12:13:59.35115+00:00"
}

Include direct children Pass 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.

const computers = await client.taxonomy.getSubcategory({
  id: 'computers-uuid',
  include: 'children',
});

// {
//   id: 'computers-uuid',
//   name: 'Computers',
//   parent_id: null,
//   children: [
//     { id: 'desktops-uuid', name: 'Desktops', parent_id: 'computers-uuid' },
//     { id: 'laptops-uuid',  name: 'Laptops',  parent_id: 'computers-uuid' }
//   ]
// }

include: 'children' returns only the immediate children. To pull a whole multi-level hierarchy in one call, use listSubcategories({ tree: true }) instead.

Include the ancestor breadcrumb chain Pass include: 'ancestors' to receive the chain of parent subcategories from the top-level subcategory down to the immediate parent, as an ancestors array ordered root-first — exactly the shape you need to render a breadcrumb (Home › Computers › Laptops › Gaming Laptops). The array is empty for a top-level subcategory.

const sub = await client.taxonomy.getSubcategory({
  id: 'gaming-laptops-uuid',
  include: 'ancestors',
});

// {
//   id: 'gaming-laptops-uuid',
//   name: 'Gaming Laptops',
//   parent_id: 'laptops-uuid',
//   ancestors: [
//     { id: 'computers-uuid', name: 'Computers', parent_id: null },
//     { id: 'laptops-uuid',   name: 'Laptops',   parent_id: 'computers-uuid' }
//   ]
// }

// Build a breadcrumb: [...sub.ancestors, sub].map(s => s.name).join(' › ')
// → "Computers › Laptops › Gaming Laptops"

You can combine both in one request — 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 the ProductsService.

Filter by Category

// Get products in a specific category (e.g., "Electronics")
const products = await client.products.listProducts({
  categoryId: 'electronics-uuid',
  limit: 24
});
// → { products: [ { product_id, name, category_name: "Electronics", price, stock, ... } ],
//     pagination: { limit: 24, next_cursor, has_more } }  — see ProductsService for the full row shape

Filter by Subcategory

// Get products in a specific subcategory (e.g., "Smartphones")
const smartphones = await client.products.listProducts({
  subcategoryId: 'smartphones-uuid'
});
// → { products: [ { product_id: "2f571a46-e02a-44ea-9a68-0772381e6da2",
//                   name: "Compact Mechanical Keyboard", subcategory_name: "Keyboards",
//                   price: 89, ... } ], pagination: {...} }
//   (a subcategory filter matches its whole subtree)

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

// Precise filtering for nested navigation
const results = await client.products.listProducts({
  categoryId: 'electronics-uuid',
  subcategoryId: 'smartphones-uuid'
});
// → { products: [...], pagination: {...} } — same row shape as above, scoped to both filters

Pro Navigation Tip: Use the image field to build high-performance visual navigation. By fetching categories with their images on initial app load, you can create immersive “Category Grids” or dynamic sidebars that make your store feel modern and alive.

Response Codes

All taxonomy endpoints are GET and accept both publishable and secret keys.

Code	Meaning
`200`	Success.
`400`	Invalid request — malformed UUID, bad query parameters, or invalid `fields` selector.
`401`	Invalid or missing API key.
`404`	Category or subcategory not found (single-resource endpoints only). List endpoints return `200` with an empty array.
`429`	Rate limit exceeded.
`500`	Internal server error.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Category Management

`getCategory`

Subcategory Management

`listSubcategories`

`getSubcategory`

Browsing Products

Filter by Category

Filter by Subcategory

Combined Hierarchical Filter

Response Codes

​Category Management

​listCategories

​getCategory

​Subcategory Management

​listSubcategories

​getSubcategory

​Browsing Products

​Filter by Category

​Filter by Subcategory

​Combined Hierarchical Filter

​Response Codes

Category Management

`listCategories`

`getCategory`

Subcategory Management

`listSubcategories`

`getSubcategory`

Browsing Products

Filter by Category

Filter by Subcategory

Combined Hierarchical Filter

Response Codes