Variant-Level References in Commercetools

Modeling product relationships in Commercetools is straightforward when the connection is at the product level, but things become more complex when those relationships need to exist between product variants.

Many commerce implementations eventually encounter this challenge, for example, when spare parts, compatible accessories, or configuration rules apply to specific product variants rather than to all variants of a product. Commercetools’ flexible data model makes it possible to represent these relationships in several ways, but each approach comes with its own trade-offs in terms of data integrity, authoring experience, and search performance.

This post walks through the problem, explains why it matters, and outlines a few practical modeling strategies that teams can use today within Commercetools , along with some thoughts on how the platform could evolve to support variant-level references more natively in the future.

Problem Statement

Commercetools currently allows product-level references through the Reference(Product) type but does not support references to product variants.

This limitation becomes a challenge in cases where relationships need to be defined at the variant level, such as compatibility or configuration links.

For example, a product line might have multiple variants designed for different material compositions or technical configurations, and certain replacement parts or accessories may only be compatible with one of those variants.

When a user views or searches for a specific variant, the system should display only the associated compatible items. Achieving this requires modeling and querying variant-to-product relationships with:

• Strong data integrity (no broken or mismatched references)
• Efficient search performance through Commercetools Product Search
• Usable authoring and management within Commercetools

Constraints

• The solution should preferably work entirely within Commercetools, without external databases or services managing the relationships.
• It must remain compatible with Commercetools Product Search, without relying on an external search provider.
• Ideally, the solution should maintain referential integrity similar to how product references work.
• Each entity may reference around 10–20 variants on average, staying within the limits of product modelling best practices.

Potential Solution Patterns

Option 1: Set of Nested Objects

How it works:

• Define a nested product type to represent a product–variant pair:

{   
  "product": { "type": "reference", "referenceTypeId": "product" },   
  "variantKey": { "type": "text" } 
}

• On the main product type, create an attribute fitForVariants of type Set<Nested>.
• Optionally include a denormalized field (fitForVariantKeysof type Set<Text>) that stores a token like "<productKey>#<variantKey>" for search queries.

Why it’s good:

• Captures both product and variant context in a single, structured object.
• Product references ensure partial data integrity.
• Compatible with Commercetools Product Search.
• Can be validated through an API Extension to ensure referenced variants exist.

Limitations:

• Merchant Center provides limited usability for sets of nested objects.
• Requires an API Extension for validation and denormalization.

Poor Merchant Center UX

Option 2: Simple Set of Strings (Variant Keys or SKUs)

How it works:

• Use a single attribute like fitForVariantKeys of type Set<Text>.
• Store variant keys or SKUs directly as strings.
• Optionally validate through an API Extension.

Why it’s good:

• Simple to implement and easy to query.
• Compatible with Product Search.

Limitations:

• No built-in referential integrity:
• The system doesn’t validate that the key or SKU exists.
• SKUs can be renamed; keys are immutable but still unvalidated.
• No protection against deleted or reassigned variants.

Option 3: Custom Objects with a Custom Admin View

How it works:

• Store compatibility data in Custom Objects, for example:

{
  "container": "variant-compatibility",
  "key": "part-123",
  "value": [
    { "productKey": "productA", "variantKey": "variant1" },
    { "productKey": "productA", "variantKey": "variant2" }
  ]
}

• Manage these relationships through a custom admin UI built as a Merchant Center Custom Application.
• Sync the data into product attributes for search indexing.

Why it’s good:

• Fully flexible model and validation rules.
• Custom UI can provide a better authoring experience.
• Clean separation between catalog data and relationship logic.

Limitations:

• Relationships are not visible directly in the product data by default.
• Requires synchronization to product attributes for search.
• Higher development and maintenance effort.
• Still no protection against deleted or reassigned variants.

Option 5: Flatten Variants into Products with a Grouping Key

How it works:

• Represent each variant as an individual product.
• Use a shared key or attribute (e.g. modelKey) to group products belonging to the same family.
• Spare parts or accessories reference products directly using standard Reference(Product) attributes.

Why it’s good:

• Uses native product references with full data integrity.
• Works seamlessly with Product Search and Merchant Center.

Limitations:

• Increases catalog size significantly.
• Complicates product grouping, pricing, and presentation logic.
• Not practical if variants differ only slightly.

Option 5: External PIM or Master Data System as Source of Truth

How it works:

• Manage all variant relationships in an external PIM or master data system.
• Synchronize a simplified version into Commercetools for search and display.

Why it’s good:

• Centralized data governance and validation.
• Simplifies data maintenance at scale.

Limitations:

• Requires integration pipelines and synchronization jobs.
• Data in Commercetools becomes a read-only projection.
• Out of scope if Commercetools is the only system in use.

Conclusion

Variant-level relationships are a common but subtle challenge in headless commerce architectures. While Commercetools offers powerful flexibility for modeling products and attributes, its current focus on product-level references means that variant-specific links still require custom solutions or validation logic.

The approaches outlined here show that it’s possible to achieve reliable and searchable variant relationships entirely within Commercetools — though each comes with trade-offs between simplicity, integrity, and scalability. As Commercetools continues to evolve, native support for variant-level references would be a valuable addition, helping teams reduce complexity and keep their data models both clean and future-proof.