Documentation

Product data modeling

Elevate, May 20-22-2025, Miami Beach, Florida

Having the right data model is crucial for both delivering excellent user experiences in the storefront and ensuring seamless integrations. This guide provides an overview of product data modeling in commercetools Composable Commerce. We'll explore the critical phases and considerations to help you make informed decisions for an optimal data model.

Evaluate your requirements

As a first step in the data modeling process, it is important to clarify the necessary commerce integrations and their requirements. Pay close attention to any systems that produce or enrich product information, as they may impose certain constraints (such as specific required fields or text-length restrictions).

Next, evaluate additional requirements that can influence the product data model. Think about search functionality, promotions, and pricing considerations. For example, promotions may require specific product attributes to define product discounts accurately.

Consider where product data is maintained

The system where product information is maintained or enriched has a significant impact on the product data model.

You can use the Merchant Center to define your initial Product Types, as well as to maintain Product data. You can view Product lists, as well as view and modify Product details.

If you choose to manage products in the Merchant Center, build a model that allows for easy product edits and supports robust data governance. Set up attributes as enums or booleans, or group attributes for intuitive UI navigation.

If product details are managed outside of Composable Commerce, then you can skip such considerations and simply proceed with the primary commerce requirements in mind.

Before you begin the modeling process, decide on the data necessary for Composable Commerce. As a general guideline, only include data essential for commerce operations, though exceptions exist when additional product data benefits downstream integrations.

Data modeling foundations

Identify the Product Types

Start the data modeling process by identifying core product types and their required attributes.

Product Types serve as the templates for product information, determining the Product Attributes for Products of that type. Every product belongs to exactly one Product Type.
product type to product relationship
While Products within the same type might have differences, they should have a significant overlap in their Product Attributes. If Products within the same type don't share many attributes, this creates a set-up where many attributes are not applicable or remain empty for many Products.

This leads to a higher number of total attributes, making the product data management process more difficult, especially if this data is maintained manually.

For example, while not every attribute might be shared among clothing items such as shirts, pants, and dresses, their significant attribute overlap supports grouping them under the same Product Type.

As a general guideline, products within a Product Type should share about 80% of their attributes.

The primary challenge at this stage is identifying the best model that suits your requirements. While there are numerous strategies and considerations to explore, a good starting point is often focusing on shared attributes, such as size, color, and material. If a significant number of products within a group of products share these attributes, it is usually indicative that they belong to the same cluster.

When creating product types, the aim is to strike a balance between generic and specific Product Types.

  • Specific Product Types: these have fewer Product Attributes, making them more specific and relevant to each Product. However, too many granular Product Types can complicate maintenance and integration.
  • Generic Product Types: these encompass a wide range of Products with many Product Attributes, but often result in some unused fields for each Product.

Where you manage product data significantly influences the choice between specific and generic Product Types:

  • When managing data in Composable Commerce: opt for multiple specific Product Types. This ensures only relevant Product Attributes are displayed in the Merchant Center, streamlining product management.
  • When managing data in PIM system or elsewhere: generic Product Types are more efficient. Here, the goal is to reduce the number of Product Types and Product Attributes to synchronize. For example, you can choose a single generic Product Type that combines a set of Product Attributes—such as a JSON-formatted field that stores essential commerce product information.
Find more information and insights in the Product data modeling module.

Define the Product Variants

The next step in the process is to distinguish between high-level products and their specific variants. In Composable Commerce, Product Variants represent distinct SKUs or sellable items, whereas Products function as their overarching structure.

Consider this scenario: an apparel retailer offers a specific T-shirt model available in various colors and sizes. While some information remains consistent across all variations, other details might change based on the color-size combination. In this case, the T-shirt represents the Product, which is not directly for sale. However, each unique color and size combination constitutes a Product Variant—the actual item you can purchase.

Product Attributes, their characteristics, and their constraints play a vital role in the modeling process. Let's look at some of the validations we can apply:
  • Same For All: ensures consistency across all Product Variants, as it is determined and maintained at a Product level.
  • Combination Unique: guarantees no two Product Variants share the exact same specifications. Using the previous T-shirt example, both color and size would act as variant dimensions. With this constraint, there would only be one variant for a small, green T-shirt.
  • Unique: ensures Product Attribute values remain distinct within the same Product.
  • Searchable: enables the Product Attribute for search and filtering. Use it sparingly to ensure relevant search results and efficient indexing.
  • Required: ensures that a Product Attribute is always present.

Effectively modeling products and variants is shaped by factors like search capabilities, product data management, storefront needs, and integration constraints.

The relationship between a product and its variants can be straightforward with a one-to-one relationship or more complex with a product having multiple variants.

  1. One-to-one relationship: this approach is ideal when a product is unique and doesn't have variations in attributes like size, color, or material. For instance, home appliances might fit this model if they don't have typical variant attributes.
  2. One-to-many relationship: if multiple attributes share the same value, this typically indicates that they are variants of a product. For instance, products to be displayed on the same product detail page, like T-shirts available in different colors and sizes, should be grouped as variants of a single product.
If managing products within the Merchant Center, it's beneficial to specify attributes that define the variant and ensure they use a CombinationUnique constraint.
Keep in mind that the Product resource in each API response includes all Product Variants and their Product Attributes. If there are many Product Variants with numerous Product Attributes, the response size is larger, which affects loading and rendering times on the storefront. For such cases, we recommend using the GraphQL API.

Categorize the Products

Categories offer a systematic way to organize products within hierarchical frameworks. They serve multiple purposes, including facilitating navigation, promotions, grouping products, and maintaining product data. A Product can belong to multiple Categories based on specific requirements.
Let's consider two category trees as an example: a navigation category tree and a promotions category tree. Both navigation trees contain two sub-categories: Women and Men.
Product type to product relationship
In this example, the navigation tree is the primary category tree, where the Women category contains all clothing items for women. In the promotions tree, the Women category only contains clothing items that are on sale. Although the sub-categories have the same label in the different category trees, they represent distinct categories that may contain different items.

Start by defining your primary category tree, such as the one used for navigation. Then, construct each hierarchical framework within this primary tree. Following this process, you can begin to map out additional category trees, for example, for promotions.

Additional product modeling considerations

Pricing and inventory

While pricing decisions don't have a significant impact on product modeling, it is important to ensure that each Product Variant can be priced. Otherwise, they cannot be added to a Cart. Composable Commerce can either manage prices internally or rely on an external pricing system. When using an external system, it is accessed whenever prices are required, like when a Product is added to a Cart.

Within Composable Commerce, two options exist for storing prices:

Each method has its advantages and disadvantages. Every price, regardless of the method, correlates with a specific Product Variant or SKU. It's possible for a single SKU to have multiple Prices based on variations in currencies, countries, Customer Groups, Channels, or validity periods.
The Inventory API in Composable Commerce enables tracking of stock quantities for each Product Variant or SKU and supply Channel. While inventory records may not drastically impact product modeling, you should ensure that Product Variants meet inventory prerequisites when monitoring stock in Composable Commerce.

Product Selections

Product Selections provide a way to manage individual store assortments or collections of products, such as seasonal products or products for a marketing campaign. A Product Selection specifies a Product set, either including or excluding Products, linked to one or more Stores.

Including a Product in a given Product Selection ensures that the Product is accessible in a particular Store while excluding it makes the Product unavailable.

If using Product Selections, keep in mind that they are managed at the Product level. This will impact how you define Products and Product Variants based on your requirements for Product Selections.

As Product Projection Search does not support Product Selections, use Product Selections with external search.

B2B specifics B2B

For B2B implementations, it's common to use the Stores API with supply and distribution channels in conjunction with Business Units to define customer-specific Products and Prices. Although these APIs are pivotal for B2B, they seldom influence product modeling.

Ensure repeatability

Product modeling elements, such as Product Types, Product Attributes, and Categories, will likely span multiple Projects including development, QA, and staging. Set keys on all entities to ensure that you can replicate the data in different environments.

After establishing the foundational structure, we suggest employing an infrastructure-as-code tool, for example, Terraform with the ready-to-use commercetools Terraform provider. This tool can streamline the setup of Product Types, Attributes, Categories, and more. It's also effective for other resources, like Channels and Stores.