> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Category Taxonomy
> TWICE classifies products with the standardized Shopify Product Taxonomy — a single, hierarchical category tree shared across all accounts.
export const categoryTaxonomyDefinition = "A standardized hierarchical product classification system that organizes inventory into categories and subcategories. TWICE uses the Shopify Product Taxonomy standard to ensure consistent categorization across your catalog and integrations.";
## Definition
Category Taxonomy is the hierarchical classification TWICE uses to describe what a product *is*. TWICE adopts the **[Shopify Product Taxonomy](https://help.shopify.com/en/manual/products/details/product-category)** verbatim — every category, ID, and parent-child relationship matches the Shopify standard.
Standardizing on Shopify's taxonomy means your categorization is portable, reportable, and immediately compatible with marketplaces, ad platforms, and integrations that already speak the same language.
## How categories are structured
Each taxonomy category in TWICE carries:
| Field | Description |
| :------------ | :--------------------------------------------------------------------------------------- |
| **ID** | Shopify GID — stable, never changes |
| **Name** | Local name at this level (e.g. "Bicycles") |
| **Full name** | Full hierarchical path (e.g. "Sporting Goods > Outdoor Recreation > Cycling > Bicycles") |
| **Level** | Depth in the tree (0 = top-level, 1 = subcategory, etc.) |
| **Parent** | Reference to the parent category — or `null` for top-level |
| **Is leaf** | Whether this is a terminal node (no children) |
Categories can be many levels deep. Leaf categories are the ones you typically assign to products — non-leaf categories exist for browsing the tree.
## Where categories apply
In TWICE, a category can be assigned to:
| Entity | When you'd assign it |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **SKU** | The default category for the product type — cascades to Stock Items and Listings unless overridden |
| **Listing** | The category as presented to the storefront — can differ from the SKU's category if you want a Listing in a marketing-specific category |
| **Stock Item** | Inherited from the SKU; rarely overridden |
Categories are assigned through the **TaxonomyCategorySearch** picker — start typing and the picker suggests matches based on the full hierarchical name. Vector-based search also surfaces close matches even when wording doesn't match exactly.
Read more: [SKUs](/docs/concepts/inventory/skus) · [Listings](/docs/concepts/catalog/listings)
## Categories vs. attributes vs. collections
Three concepts often get confused — here's how they differ in TWICE:
| Concept | Purpose | Cardinality | Example |
| :-------------- | :----------------------------- | :-------------- | :------------------------------- |
| **Category** | What the product *is* | One per entity | "Bicycles" |
| **Attributes** | Specific characteristics | Many per entity | Frame: Aluminum, Wheel size: 29" |
| **Collections** | Marketing/merchandising groups | Many per entity | "Summer Sale", "Staff Picks" |
Each layer answers a different question. Category answers "what kind of thing"; Attributes answer "what are its properties"; Collections answer "where do we want to promote it".
Read more: [Attributes](/docs/concepts/admin/attributes) · [Collections](/docs/concepts/catalog/collections)
## Category-linked attributes
Some categories in the Shopify taxonomy come with **suggested attributes** — for example, the "Bicycles" category suggests `Frame material`, `Wheel size`, `Brake type`. TWICE stores these mappings (`taxonomy_category_attributes`) and uses them to:
* Prefill the attribute list on a SKU when you pick a category
* Suggest attribute values from the standardized value set (e.g. "Aluminum", "Carbon", "Steel" for Frame material)
* Power smart matching when bulk-importing products
You can always add your own custom attributes on top of the suggested set.
## Category-based reporting
Because every account uses the same category tree, reports group cleanly:
* **Sales by category** — compare performance across product types without a custom mapping
* **Inventory utilization by category** — see which segments of the catalog drive rentals or sales
* **Cross-account benchmarking** — internal benchmarking across stores or regions stays apples-to-apples
Reports include a category filter and grouping option by default.
## Storefront navigation
Categories assigned to Listings flow through to your online store. Depending on the theme, this can drive:
* **Category browse pages** — landing pages per category
* **Faceted search** — filter products by category or subcategory
* **Breadcrumb navigation** — surface the category hierarchy on Listing pages
* **Sitemaps and structured data** — SEO-friendly category metadata
The actual presentation depends on your storefront theme. The category data itself is identical across themes.
Read more: [Online Store](/docs/concepts/sales-channels/online-store)
## API access
The taxonomy is read-only — you can browse and assign categories, but you can't modify the tree itself. Query the taxonomy via the API:
Useful query parameters: `parentId`, `parentIds`, `level`, `isLeaf`, `ids`.
## Updates to the taxonomy
Shopify revises the Product Taxonomy periodically. TWICE imports updates so your categorization stays in sync with the upstream standard. When a category is renamed or restructured, the underlying ID remains stable so existing assignments don't break.
## Relationships
```mermaid theme={null}
%%{init: {'flowchart': {'nodeSpacing': 20, 'rankSpacing': 20}}}%%
flowchart TB
subgraph ConceptBox["Admin & System"]
direction TB
Attributes["Attributes"]
CategoryTaxonomy["**[Category Taxonomy]**"]
Attributes ~~~ CategoryTaxonomy
end
SKU["SKU"]
StockItem["Stock Item"]
Listing["Listing"]
subgraph RelatedBox["Powers"]
direction TB
Reporting["Reporting"]
Storefront["Storefront navigation"]
Integrations["Integrations & feeds"]
Reporting ~~~ Storefront ~~~ Integrations
end
CategoryTaxonomy -->|classifies| SKU
CategoryTaxonomy -->|classifies| Listing
SKU -->|inherited by| StockItem
CategoryTaxonomy -.->|suggests| Attributes
CategoryTaxonomy -.->|feeds| RelatedBox
style ConceptBox fill:#0000000d,stroke:#888,stroke-width:2px
style CategoryTaxonomy fill:#3b82f633,stroke:#3b82f6,stroke-width:3px,font-weight:bold
style Attributes fill:#0000000a,stroke:#999,stroke-width:1px
style SKU fill:#10b98133,stroke:#10b981,stroke-width:2px
style Listing fill:#10b98133,stroke:#10b981,stroke-width:2px
style StockItem fill:#10b98133,stroke:#10b981,stroke-width:2px
style RelatedBox fill:#f59e0b1a,stroke:#f59e0b,stroke-width:2px
style Reporting fill:#f59e0b1a,stroke:#f59e0b,stroke-width:1px
style Storefront fill:#f59e0b1a,stroke:#f59e0b,stroke-width:1px
style Integrations fill:#f59e0b1a,stroke:#f59e0b,stroke-width:1px
```
## FAQs
Standardization keeps your data portable. Reports compare cleanly across stores, integrations with Shopify or marketplaces don't need a mapping layer, and your catalog is immediately legible to anyone who has worked with e-commerce. Custom categories would re-fragment all of that.
The Shopify taxonomy is broad — most product types resolve to a leaf within a few clicks. When nothing fits exactly, pick the closest broader category and use Attributes to express the specifics. If a whole class of products is missing, Shopify takes community proposals for new categories.
No — each entity (SKU or Listing) gets one category. Use Collections to group products across categories for marketing.
By default, a Listing inherits its category from the SKU. You can override the Listing's category for storefront purposes without changing the SKU's underlying classification.
No. Orders capture the category at the time of purchase. Changing a SKU's category later updates current and future displays but doesn't rewrite the order history.
Yes. Workflows can match on category — for example, automatically apply a "Needs annual service" task to all Stock Items in the Bicycles category. See [Workflows](/docs/workflows).
## Developer Reference
The category taxonomy is exposed as `taxonomy` in the API.
Open the endpoint in the API reference.
## Related
Custom data fields that complement category classification
Marketing groups that span multiple categories
Where the primary category assignment lives
The upstream standard TWICE follows