---
title: Example - product catalog
related:
  - https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog/model-product-stock.md
---

> 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).

> **License:** Advanced license required.
>
> Features described on this page require the Xperience by Kentico **Advanced** license tier.

This page demonstrates a practical implementation of a product catalog using the [content hub](https://docs.kentico.com/documentation/business-users/content-hub.md) to store products as [reusable content items](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md). The example follows the [product catalog modeling recommendations](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/model-product-catalog.md) and showcases how to:

- Define a [reusable field schema](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md) for common product fields
- Create a product [content type](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md) that implements the schema
- Use [taxonomies](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) for product categorization
- Retrieve and display products using the [content retriever API](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api.md)

## Content model overview

The example catalog uses the following content model structure:

- **ProductFields** – a [reusable field schema](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md) containing common product properties (name, description, price, category).
- **ProductSKU** – a [content type](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md) that implements the `ProductFields` schema and represents individual products.
- **ProductCategory** – a [taxonomy](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) for organizing products into categories.

![Product catalog content model structure](https://docs.kentico.com/docsassets/documentation/example-product-catalog/content-model-structure.drawio.svg "Product catalog content model structure")

This structure allows you to:

- Reuse the `ProductFields` schema across multiple product types if needed.
- Query products by their shared fields using the schema interface.
- Filter products by category using taxonomy tags.

## Reusable field schema

The `ProductFields` reusable field schema defines the common fields shared by all products. When you [generate code for the schema](https://docs.kentico.com/documentation/developers-and-admins/api/generate-code-files-for-system-objects.md), you get an interface that content types can implement:

```csharp title="Generated ProductFields interface"
/// <summary>
/// Defines a contract for content types with the <see cref="ICodesamplesProductFields"/> reusable schema assigned.
/// </summary>
public interface ICodesamplesProductFields
{
    /// <summary>
    /// Code name of the reusable field schema.
    /// </summary>
    public const string REUSABLE_FIELD_SCHEMA_NAME = "Codesamples.ProductFields";


    /// <summary>
    /// ProductFieldsName.
    /// </summary>
    public string ProductFieldsName { get; set; }


    /// <summary>
    /// ProductFieldsDescription.
    /// </summary>
    public string ProductFieldsDescription { get; set; }


    /// <summary>
    /// ProductFieldsPrice.
    /// </summary>
    public decimal ProductFieldsPrice { get; set; }


    /// <summary>
    /// ProductFieldCategory.
    /// </summary>
    public IEnumerable<TagReference> ProductFieldCategory { get; set; }
}
```

The schema includes:

- `ProductFieldsName` – the display name of the product
- `ProductFieldsDescription` – a detailed product description
- `ProductFieldsPrice` – the base price of the product
- `ProductFieldCategory` – taxonomy tags for categorization

## Product content type

The `ProductSKU` content type implements the generated interface for the `ProductFields` schema, inheriting all fields. The generated code provides a strongly-typed class for working with product data:

```csharp title="Generated ProductSKU class"
using System;
using System.Collections.Generic;

using CMS.ContentEngine;

/// <summary>
/// Represents a content item of type <see cref="ProductSKU"/>.
/// </summary>
[RegisterContentTypeMapping(CONTENT_TYPE_NAME)]
public partial class ProductSKU : IContentItemFieldsSource, ICodesamplesProductFields
{
    /// <summary>
    /// Code name of the content type.
    /// </summary>
    public const string CONTENT_TYPE_NAME = "Codesamples.ProductSKU";


    /// <summary>
    /// Represents system properties for a content item.
    /// </summary>
    [SystemField]
    public ContentItemFields SystemFields { get; set; }


    /// <summary>
    /// ProductFieldsName.
    /// </summary>
    public string ProductFieldsName { get; set; }


    /// <summary>
    /// ProductFieldsDescription.
    /// </summary>
    public string ProductFieldsDescription { get; set; }


    /// <summary>
    /// ProductFieldsPrice.
    /// </summary>
    public decimal ProductFieldsPrice { get; set; }


    /// <summary>
    /// ProductFieldCategory.
    /// </summary>
    public IEnumerable<TagReference> ProductFieldCategory { get; set; }
}
```

> **Info:** The `[RegisterContentTypeMapping]` attribute automatically registers the class with the [content retriever](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api/content-retriever-api.md), enabling you to query products using the strongly-typed `ProductSKU` class.

## Retrieve products

Use the `IContentRetriever` service to query products from the content hub. The following examples demonstrate common retrieval patterns. For a comprehensive overview of all available retrieval options, parameters, and caching configuration, see [Reference - ContentRetriever API](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api/reference-content-retriever-api.md).

### Retrieve all products

```csharp title="Retrieve all products"
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

using CMS.Commerce;
using CMS.ContentEngine;

using Kentico.Content.Web.Mvc;

// ...

/// <summary>
/// Retrieves all products from the content hub.
/// </summary>
public async Task<List<ProductModel>> GetAllProductsAsync()
{
    var products = await contentRetriever.RetrieveContent<ProductSKU, ProductModel>(
        GetContentParameters(),
        additionalQueryConfiguration: null,
        new RetrievalCacheSettings(cacheItemNameSuffix: "AllProducts"),
        configureModel: async (container, productSKU) => await MapToProductModelAsync(productSKU)
    );

    return products.ToList();
}
```

The `RetrieveContent` method:

- Accepts the content type (`ProductSKU`) and a target model type (`ProductModel`) as generic parameters
- Uses `RetrieveContentParameters` to specify the language and preview mode
- Supports caching through `RetrievalCacheSettings`
- Transforms content items to view models using the `configureModel` delegate

### Retrieve a single product

```csharp title="Retrieve product by GUID"
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

using CMS.Commerce;
using CMS.ContentEngine;

using Kentico.Content.Web.Mvc;

// ...

/// <summary>
/// Retrieves a product by its content item GUID.
/// </summary>
public async Task<ProductModel?> GetProductByGuidAsync(Guid contentItemGuid)
{
    var products = await contentRetriever.RetrieveContentByGuids<ProductSKU, ProductModel>(
        [contentItemGuid],
        GetContentParameters(),
        additionalQueryConfiguration: null,
        new RetrievalCacheSettings(cacheItemNameSuffix: $"ByGuid|{contentItemGuid}"),
        configureModel: async (container, productSKU) => await MapToProductModelAsync(productSKU)
    );

    return products.FirstOrDefault();
}
```

Use `RetrieveContentByGuids` when you have the content item's GUID, which is useful for product detail pages or when working with URL-based routing.

### Filter products by category

```csharp title="Retrieve products by category"
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

using CMS.Commerce;
using CMS.ContentEngine;

using Kentico.Content.Web.Mvc;

// ...

/// <summary>
/// Retrieves products by category using taxonomy tag GUID.
/// </summary>
public async Task<List<ProductModel>> GetProductsByCategoryAsync(Guid categoryTagGuid)
{
    var products = await contentRetriever.RetrieveContent<ProductSKU, ProductModel>(
        GetContentParameters(),
        query => query.Where(where => where
            .WhereContainsTags(
                nameof(ICodesamplesProductFields.ProductFieldCategory),
                [categoryTagGuid])),
        new RetrievalCacheSettings(cacheItemNameSuffix: $"ByCategory|{categoryTagGuid}"),
        configureModel: async (container, productSKU) => await MapToProductModelAsync(productSKU)
    );

    return products.ToList();
}
```

The `WhereContainsTags` method filters products that have a specific taxonomy tag assigned. Pass the field name and an array of tag GUIDs to match.

## Retrieve categories

Use the `ITaxonomyRetriever` service to retrieve category tags for navigation and filtering:

```csharp title="Retrieve product categories"
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

using CMS.ContentEngine;
using CMS.DataEngine;
using CMS.Helpers;

/// <summary>
/// Service for retrieving product categories from the ProductCategory taxonomy.
/// </summary>
public class CategoryService : CachedServiceBase
{
    public const string PRODUCT_CATEGORY_TAXONOMY = "Codesamples.ProductCategory";

    private readonly ITaxonomyRetriever taxonomyRetriever;
    private readonly ICacheDependencyBuilderFactory cacheDependencyBuilderFactory;

    public CategoryService(
        ITaxonomyRetriever taxonomyRetriever,
        IProgressiveCache progressiveCache,
        ICacheDependencyBuilderFactory cacheDependencyBuilderFactory)
        : base(progressiveCache)
    {
        this.taxonomyRetriever = taxonomyRetriever;
        this.cacheDependencyBuilderFactory = cacheDependencyBuilderFactory;
    }

    /// <summary>
    /// Retrieves all product categories from the ProductCategory taxonomy with caching.
    /// </summary>
    public async Task<List<CategoryModel>> GetCategoriesAsync()
    {
        return await LoadWithCacheAndDependency(async (cacheSettings) =>
        {
            // Loads taxonomy data
            var taxonomyData = await taxonomyRetriever.RetrieveTaxonomy(PRODUCT_CATEGORY_TAXONOMY, "en");

            var result = taxonomyData.Tags
                .Select(tag => new CategoryModel
                {
                    TagGuid = tag.Identifier,
                    Name = tag.Title
                })
                .OrderBy(n => n.Name)
                .ToList();

            // Set cache dependency - clear cache when the taxonomy changes
            var dependencyBuilder = cacheDependencyBuilderFactory.Create();
            cacheSettings.CacheDependency = dependencyBuilder
                .ForInfoObjects<TaxonomyInfo>()
                    .ByCodeName(PRODUCT_CATEGORY_TAXONOMY)
                    .Builder()
                .Build();

            return result;
        },
        cacheMinutes: CacheConstants.LongCacheDurationMinutes,
        cacheItemNameParts: ["commerce", "categories", PRODUCT_CATEGORY_TAXONOMY]);
    }
}
```

The taxonomy retriever returns all tags within the specified taxonomy, which you can use to build category menus or filter controls.

## Map products to view models

When displaying products, map the content item data to a view model that includes calculated fields such as discounted prices. The following example integrates with the [price calculation service](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation.md) to apply [catalog promotions](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/catalog-discounts.md):

```csharp title="Map product to view model"
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

using CMS.Commerce;
using CMS.ContentEngine;

using Kentico.Content.Web.Mvc;

// ...

/// <summary>
/// Maps a ProductSKU content item to a ProductModel using price calculation service to determine discounts.
/// </summary>
private async Task<ProductModel> MapToProductModelAsync(ProductSKU productSKU)
{
    var basePrice = productSKU.ProductFieldsPrice;
    
    // Use price calculation service in Catalog mode to check for catalog promotions
    var calculationRequest = new CodesamplesPriceCalculationRequest
    {
        Items = [new CodeSamplesPriceCalculationRequestItem
        {
            ProductIdentifier = new ProductIdentifier { Identifier = productSKU.SystemFields.ContentItemID },
            Quantity = 1
        }],
        LanguageName = "en",
        Mode = PriceCalculationMode.Catalog
    };

    var calculationResult = await priceCalculationService.Calculate(calculationRequest);
    var resultItem = calculationResult.Items.FirstOrDefault();
    
    // Check if a catalog promotion was applied by looking at PromotionData
    var appliedPromotion = resultItem?.PromotionData?.CatalogPromotionCandidates
        ?.FirstOrDefault(c => c.Applied);
    bool isDiscounted = appliedPromotion != null;
    
    // Get the final price after any catalog discounts
    decimal finalPrice = resultItem?.LineSubtotalAfterLineDiscount ?? basePrice;
    
    return new ProductModel
    {
        ContentItemGuid = productSKU.SystemFields.ContentItemGUID,
        Id = productSKU.SystemFields.ContentItemID,
        Name = productSKU.ProductFieldsName,
        Description = productSKU.ProductFieldsDescription,
        Price = finalPrice,
        ListPrice = isDiscounted ? basePrice : null,
        Category = productSKU.ProductFieldCategory?.FirstOrDefault()?.Identifier.ToString() ?? string.Empty
    };
}
```

This approach:

- Calculates the [final catalog price](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/price-calculation/implementation.md#catalog-price-calculation) after applying any active [catalog discounts](https://docs.kentico.com/documentation/developers-and-admins/digital-commerce-setup/promotions/catalog-discounts.md).
- Preserves the original list price for display (e.g., for showing strikethrough pricing).
- Extracts category information from taxonomy tags.

> **Tip:** For better performance in product listings, consider [caching](https://docs.kentico.com/documentation/developers-and-admins/development/caching/data-caching.md) the price calculation results or performing bulk calculations for multiple products at once.