Understanding the Tweakwise catalog domain model is essential for designing robust backend integrations, feed pipelines, and storefront query workflows. This document explains the underlying domain model concepts of Tweakwise catalog structures, including parent-child variant relationships, attribute ingestion and data types, and category taxonomies.

By following this guide, you will understand:

• The primary entity hierarchy that structures product catalogs in Tweakwise.
• How attributes are discovered from feeds and referenced in the API.
• How parent-child variant grouping works in search and lister pages.
• How category taxonomies and multi-tree structures are configured and served.

Implementation & Domain Model Overview

Entity Hierarchy

The Tweakwise catalog domain model structures e-commerce data into three core layers:

• Product Entities: Master product records containing core properties such as unique identifier (id), title, deep link, price, and image URL.
• Attributes: Metadata properties attached to products that enable dynamic filtering, sorting, merchandising, and search field indexation.
• Category Taxonomies: Hierarchical trees that organize product entities into navigable storefront categories.

Attribute Ingestion and Data Types

Tweakwise handles attributes through feed-driven discovery rather than manual REST API schema definition:

• Automatic Discovery: Attributes are created automatically when the product feed (Source: "Feed") is imported. Tweakwise treats the feed as the authoritative source for attribute definitions.
• Data Types: Tweakwise detects property formats automatically during ingestion, classifying string values into Text attributes and numerical fields into Number attributes.
• Canonical Field Mapping: Core properties required for storefront capabilities (such as Image, URL, SKU, Brand, and ItemType) are mapped from feed attributes to platform configuration settings.

Parent-child variant grouping

Unlike traditional e-commerce platforms, Tweakwise does not rely on strict hierarchical parent-child variant structures. Instead, products are grouped dynamically using custom attribute group keys (such as groupcode):

• Attribute-Based Grouping: Individual items or SKUs share a common attribute value (e.g., groupcode = "ult-12") to link related product variants together seamlessly.
• Flexible Aggregation: Merchandisers can configure how storefront search and lister pages combine items sharing the same group key, providing flexible control without rigid parent entity definitions.
• XML Feed Structure: In the product feed XML, each item explicitly defines its shared group key attribute:
  XML

  <items>
    <item>
      <id>101</id>
      <name>Running Shoes - Red - Size 42</name>
      <groupcode>ult-12</groupcode>
    </item>
    <item>
      <id>102</id>
      <name>Running Shoes - Blue - Size 44</name>
      <groupcode>ult-12</groupcode>
    </item>
  </items>

Category Taxonomies

Taxonomies structure products into logical navigation trees:

• Multi-Tree Indexing: Tweakwise allows you to index multiple distinct category trees within a single instance. This supports scenario-specific structures such as B2C vs. B2B catalogs or regional taxonomies.
• Contextual Querying: Your storefront application selects which category tree to request by passing taxonomy parameters in Delivery API requests.

FAQ

How do I create new custom attributes via the Tweakwise API?
Custom attributes can be created by doing a PATCH on a product. Add the new field to your product feed, execute a feed import, and retrieve the newly generated integer AttributeId via GET /attribute.

How does parent-child grouping affect product search results?
Tweakwise provides metadata for both total variant counts and representative SKU properties, allowing storefronts to render aggregated tiles or detailed variant selectors. There are separate endpoints with different behavior: grouped endpoints return results grouped, while regular endpoints return results exploded.

Can I serve different category taxonomies for B2B and B2C channels?
Yes. Tweakwise supports multi-tree category indexing. You can define multiple category structures in your feed and pass context parameters in your Delivery API queries to retrieve the appropriate taxonomy tree for each customer segment.