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.

const { categories, pagination } = await client.taxonomy.listCategories({
  search: 'clothes',
  active: true,
  limit: 50,
  fields: 'id,name,image'
});

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: 'electronics-uuid',
  fields: 'name,description,image' // Optional
});

console.log(`Category Banner: ${category.image}`);

Subcategory Management

Subcategories allow for more granular organization within a parent category (e.g., “Laptops” inside “Electronics”).

listSubcategories

Retrieve a paginated list of subcategories. You can scope this to a specific 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'
});

---

getSubcategory

Retrieve details for a specific subcategory.

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

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
});

Filter by Subcategory

// Get products in a specific subcategory (e.g., "Smartphones")
const smartphones = await client.products.listProducts({
  subcategoryId: 'smartphones-uuid'
});

Combined Hierarchical Filter

// Precise filtering for nested navigation
const results = await client.products.listProducts({
  categoryId: 'electronics-uuid',
  subcategoryId: 'smartphones-uuid'
});

---

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.