> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tybritelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Taxonomy (Categories)
> Reference for the TaxonomyService class in the Tybrite SDK.
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
### `listCategories`
Retrieve all top-level product categories. This is the starting point for building navigation menus or mega-menus.
```typescript theme={null}
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.
```typescript theme={null}
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.
```typescript theme={null}
const { subcategories, pagination } = await client.taxonomy.listSubcategories({
categoryId: 'electronics-uuid',
active: true,
search: 'laptops',
limit: 24,
fields: 'id,name,category_id,image'
});
```
```json Response theme={null}
{
"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. |
```typescript theme={null}
// 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.
```typescript theme={null}
const sub = await client.taxonomy.getSubcategory({
id: 'macbooks-uuid',
fields: 'name,description,image' // Optional
});
```
```json Response theme={null}
{
"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.
```typescript theme={null}
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.
```typescript theme={null}
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
```typescript theme={null}
// 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
```typescript theme={null}
// 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
```typescript theme={null}
// 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. |