--- title: Model product variants --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). ## 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](https://docs.kentico.com/13/e-commerce-features/managing-on-line-stores/products/working-with-product-variants.md), you need to model the [product variants](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog.md#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_. > **Tip:** If you need different display listing of different product variants, especially in larger stores, you might benefit from including the _CoreContentSchema_ also into the _product variant content type_ as it will allow editors to create variant-specific content. This parent-child pattern works for both _Content hub_ (reusable content in [atomic content model](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/design-atomic-content-model.md) ) and a _website channel_ ([page-based content model](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/design-page-based-content-model.md)) 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](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog/model-product-stock.md)), 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) > **Tip:** Consider wrapping each _taxonomy collection_ into a dedicated schema to improve developer experience. Dedicated column names simplify product queries for developers. Reusable field schema column names are always present. This eliminates the need for complex tag mapping in search facets and advanced filtering. #### Implement product variants in the Content hub n the _Content hub_, variants and parent products are stored as [reusable content items](https://docs.kentico.com/documentation/business-users/content-hub.md)in 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: ```markdown title="Taxonomy tags in Products category" 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. > **Tip:** Consider improving editor workflow with [visibility conditions](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/ui-form-component-visibility-conditions.md) to display different _content type fields_ depending on the selected configuration. #### 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. ```markdown title="Taxonomy tags in Products category" 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](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api.md). - 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](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md) 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](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog/model-product-stock.md). (The [product inventory](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog/model-product-stock.md) 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. ```markdown title="Example of product variants generated from reusable field schemas " 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.