Model product variants

Modeling product variants is a key challenge in Xperience commerce content. Product variants are items that share core product attributes but differ in specific characteristics like size, color, flavor, or material.

A single product, such as a Premium Dog Collar might be available in multiple sizes and colors, creating dozens of purchasable SKUs. Contrary to Kentico Xperience 13, which handles product variants in a dedicated feature, you need to model the product variants in Xperience from scratch.

For Pawsome Pets, product variants are essential:

• Dog collars come in multiple sizes (Small, Medium, Large, X-Large) and colors (Red, Blue, Black, Pink).
• Cat food is available in different flavors (Chicken, Salmon, Tuna) and package sizes (3lb, 7lb, 15lb).
• Bird toys come in sizes appropriate for different bird species.
• Fish tanks are sold in various capacities (10-gallon, 20-gallon, 55-gallon).

How you model variants affects everything, from editor workflows to inventory management and the checkout process. The content modeling agent MCP lacked enough information when designing the model, so we need to address this now.

Xperience by Kentico supports multiple approaches, each with distinct trade-offs.

Understand approaches to modeling product variants

There are three primary approaches to modeling product variants in Xperience:

• Approach 1: Variants in as dedicted content items - Manage product option combinations as separate SKUs with price adjustments. They can exist as reusable items in Content hub or as website pages. (The latter approach is most similar to historical Kentico Xperience <13 implementations.)
• Approach 2: Variants via reusable field schemas - Represent variant attributes as reusable field schemas.

Let’s explore each approach to help you select the right pattern for your implementation.

Approach 1: Variants as dedicated content items

The recommended approach is to treat product variants as “child items” of the parent product. The parent stores shared information, while variants hold unique fields, such as size, color, or other distinguishing attributes, along with variant-specific data like SKU or stock levels.

This parent-child pattern works for both Content hub (reusable content in atomic content model ) and a website channel (page-based content model) with slight implementation differences.

The parent-child content model structure

The key principle is to avoid duplication. Shared details like material, brand, and description reside in the parent product. A variant object stores only size-specific details.

To simplify querying, you can use reusable field schemas for variant fields that repeat across content items. For example, you can use the same size description, such as small, medium, large, for products of different types.

Define ProductSize fields to simplify product data structure, such as:

ProductSize (reusable field schema): - ProductSizeValue (Text or Dropdown): The specific size (S, M, L, XL) - ProductSizeDimensions (Text or Dropdown/Taxonomy): Measurements for this size, dropdown in case of standardized sizes - ProductSizeDescription (Text): Additional explanation

The parent Product content type includes the following fields:

• ProductFields (reusable field schema): Name, descriptions, primary image, gallery, base price, tags
• ProductMaterial (Taxonomy, Text, or Dropdown): Cotton, Polyester, Blend, etc.
• ProductColor (Taxonomy, Text or Dropdown): Color of the shirt
• ProductBrand (Taxonomy or Content items): Reference to Manufacturer
• ProductCareInstructions (Rich text): Washing and care guidance
• ProductVariants (Content items): Combined content selector restricted to ShirtSizeVariant type

Note that the Product content type excludes the SKU fields, ProductStock (stock should be handled through dedicated custom module), and size, as these belong to the variant.

Variant product content type: ProductSizeVariant

This content type contains only variant-specific information:

• ProductSKU (RFS): SKUCode, barcodes, external IDs
• ProductStock (custom module reference or RFS): For example, Available, Reserved, Threshold quantities, ProductVariantDimensions (RFS or Text input): Size value and dimensions
• ProductVariantPriceAdjustment (Decimal, optional): Price modifier if XL costs more (+$2.00)
• ProductVariantImage (Content items, optional): Size-specific product image if needed

Note that the variant does not include:

• ProductFields schema (composed, inherited from parent)
• Material, color, care instructions (all on the parent)
• Brand or manufacturer (on the parent)

Implement product variants in the Content hub

n the Content hub, variants and parent products are stored as reusable content itemsin a flat content list. The Product Variant field in the parent Product establishes the relationship. In a flat structure, editors should use strict naming conventions (e.g., [ParentProductName - Distinguishing Attribute]) to simplify curation.

Content structure in Content hub:

Content Hub:
├── Premium Dog Collar (Parent in Content hub)
├── Premium Dog Collar - Small - Red (variant)
├── Premium Dog Collar - Small - Blue (variant)
├── Premium Dog Collar - Medium - Black (variant)
└── (etc.)

Editor workflow for creating products

Editors create a parent product, such as Premium Dog Collar, and provide shared information. Next, they create product variants, such as Premium Dog Collar - Small - Red, etc.

If they create the variant separately (away from the Product), the need to return to the parent product. They then select all variants in the ProductVariant field using the Combined content selector to establish the relationships. Creating variants directly from the parent via the Create new in the Combined content selector button establishes the relationship automatically. Simplify navigation by grouping products and variants in dedicated Content hub folders.

Implementing variants in the content tree structure

If you have decided to build a page-based content model for the website, you can store product variants in the content tree. A tree structure naturally represents the parent-child relationship between products and variants.

Variants live under their parent product in the tree hierarchy.

Website Channel
└── Products
    └── Dogs
        └── Collars
            ├── Premium Dog Collar (Parent)
            ├── Premium Dog Collar - Small - Red (variant)
            ├── Premium Dog Collar - Small - Blue (variant)
            ├── Premium Dog Collar - Medium - Black (variant)
            └── (etc.)

Depending on your project requirements, you can ensure consistency of your data by disabling routing for the ProductSizeVariant content type to prevent variants from being navigable through their own URLs.

Without routing, variants are automatically excluded from sitemaps, meaning editors don’t need to manually disable each and every one of them. Editors can manage variants in the admin interface, but these variants rely on the parent product page for live site access and do not have individual URLs.

Benefits of the parent-child pattern

• Shared information exists once. Update the shirt’s material on the parent, and it applies to all variants automatically.
• The relationship between parent and variants is explicit and easy to understand.
• Developers can retrieve a single parent product and its variants, rather than running separate queries for each size.
• Editors understand they’re creating variants of an existing product, not entirely new products.

Considerations and limitations of parent-child variants

• Editor workflow can be daunting as editors must create the parent, then add child items for variants, and then ensure they are linked together. This requires more steps than single-item creation but ensures proper structure. Consider implementing a mechanism to import products from an ERP system using the Content API.
• Editors need to consistently name variants, especially when creating them in the Content hub, to ensure efficient management and organization of variant content.
• With the base price stored on the parent product and only adjustments defined on variants, it becomes harder for editors to clearly see, for example, that an XL collar costs $2 more without duplicating the entire product in the Content hub.
• Managing variants becomes increasingly complex if you have multiple varying attributes (size & color & material). For instance, if a product has 5 sizes, 8 colors, and 3 materials, resulting in 120 combinations, evaluate whether all combinations require individual content items. In such cases, you might find the following reusable-field schema-based approach more suitable.

When to use this parent-child pattern

This parent-child pattern for creating product variants works best when:

• You have moderate variant counts per product (typically 2-20 variants).
• Variants differ in only one or two attributes (size, color).
• You want clear, visible variant management in the admin UI.
• Your implementation is website-first (though it works for Content hub, too).
• Editors prefer creating explicit content items for variants.
• You need simple stock tracking per variant.

Approach 2: Dynamic variants via reusable field schemas

You can define variant attributes (Size, Color, Flavor, etc.) as reusable field schemas on the Product content type. Instead of creating a separate content type to store each product variant combination, you store the available options in product-specific fields. Then, you have two options: either create a dedicated content item per variant and allow editors access in the UI, or let the application logic materialize the specific variants. In this approach, developers are responsible for creating the querying logic to dynamically display specific variants based on the defined attributes. If they decide not to provide access to editors in the UI to variant content items, they need to ensure the variant data is properly represented in the product inventory. (The product inventory relies on variants existing as dedicated content items, using the ContentItemId fields to maintain relationship between the variant and its stock. If you decide to build variants dynamically, your developers will need to customize the recommended approach and store the reference between the variant and its in-stock represenation differently.)

To implement this approach, you can create two RFS to define size and color options for products.

ProductSizeOptions RFS:

• ProductSizeAvailableSizes (Multiple choice): Small, Medium, Large, X-Large
• ProductSizeDimensions (Text or Dropdown/Taxonomy): Measurements for this size, dropdown in case of standardized sizes
• ProductSizeDescription (Text): Additional explanation

ProductColorOptions RFS:

• ProductColorAvailableColors (Multiple choice): Red, Blue, Black, Pink, Green
• ProductColorHexCodes (Text): Color values for display (RGB, HEX or other convenient format)

Your custom application code or helper methods generate purchasable variants dynamically, including SKU identifiers. For example, a dog collar with size and color variants can combine taxonomy tags for size and color to produce SKUs.

Dogs
└── Collars
        ├── Premium Dog Collar - Small - Red (SKU: PDC-SM-RED)
        ├── Premium Dog Collar - Small - Blue (SKU: PDC-SM-BLU)
        ├── Premium Dog Collar - Medium - Red (SKU: PDC-MD-RED)
        ├── Premium Dog Collar - Medium - Blue (SKU: PDC-MD-BLU)
        ├── (etc.)

Benefits of the RFS approach

• Ideal for API-driven commerce channels where clients build their own variant selectors on the storefront.
• Variant data is pure structured content, making it reusable across any channel, such as websites, mobile apps, or third-party platforms.
• This approach eliminates the need to create hundreds of content items for every variant combination. Variant options are stored only in the parent, and developers generate combinations as needed.
• Improved variant management where editors can simply change available variant configuration in one place, for example, color, and affect all applicable variants.

Trade-offs of RFS

• More complex implementation requires developers to build variant materialization logic.
• Editors don’t see individual variants as separate content items in the admin UI.
• Stock tracking require a custom implementation that ensures SKU codes are generated into inventory.
• Variants don’t have dedicated pages or URLs (unless you customize how XbyK generates web page routes).

When to use this approach

• You’re building an API-first commerce experience.
• You need to display products across multiple channels, but don’t need their representation in the admin UI.
• You have products with many variant combinations (10+ variants per product).
• Your developers can build variant materialization logic.
• Flexible cross-channel reuse is more important than individual variant pages on the storefront.