---
title: Model commerce website pages
---

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

Commerce experiences in Xperience by Kentico often require an architecture that **separates reusable product data from channel-specific presentation**. This material explains how to model **pages** that display product content using the [atomic content model](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/design-atomic-content-model.md). You'll learn how to create scalable, multi-channel architectures that maintain a single source of truth while serving websites and microsites, headless applications, and email marketing activities.

## Understanding wrapper pages in atomic content modeling

A **wrapper page** is a content type that references [reusable content](https://docs.kentico.com/guides/architecture/content-modeling/model-reusable-content.md) from the [Content hub](https://docs.kentico.com/documentation/business-users/content-hub.md) and adds **channel-specific context** like _SEO metadata_, [URLs](https://docs.kentico.com/documentation/business-users/website-content/manage-page-urls.md), and publish dates. This pattern comes from the [atomic content model](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/design-atomic-content-model.md), which separates content into two layers: **reusable core data** that stays consistent across all channels, and **channel-specific context** that varies per website, mobile application, kiosk, or email.

> **Tip:** Editors update product data in the _Content hub_ once, and the changes automatically reflect on every _product page_ and channel that references it.

We recommend using _wrapper pages_ when you:

- Need to support **multi-channel content delivery**.
- Have channel-specific metadata requirements for SEO and social sharing.
- Need to manage URLs and site structure separately from content.
- Require different presentation approaches for the same content across websites, microsites, or different pages.

> **Tip:** If you define a content model for a business that will **display product data only on one website channel**, but plan to expand across other digital channels, such as email, you might consider storing reusable product data as [structured content](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/structured-and-unstructured-content.md). You can then [design widgets and page templates](https://docs.kentico.com/guides/architecture/content-modeling/model-website-presentation-components.md) that editors will use to refer to product data.

For simple, single website-channel projects with no plans for expansion, a [page-based model](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/design-page-based-content-model.md) may be sufficient and simpler to implement.

## The two-layer architecture for commerce content

When you apply the _wrapper page pattern_ to commerce, you split your product content into two distinct layers.

**Layer 1** stores your reusable **Product** content in the [Content hub](https://docs.kentico.com/documentation/business-users/content-hub.md). This is your single source of truth for product data, such as _title_, _description_, _summary_, _features_, _benefits_, _product images_, _specifications_, _taxonomy_, and product _categories_. This data remains consistent regardless of how or where you display the product.

**Layer 2** contains your **Product Page** in the content tree of your website channel. This page references the reusable _Product_ and adds only channel-specific metadata: _SEO fields_ (title, description, canonical URL), _Open Graph tags_ for social sharing, page _URLs_ and routing, _publish dates_ and scheduling, channel-specific _hero banners_ or promotional images, and page-specific content, such as _personalized messages_ or _calls to action_.

![Reusable product and Product wrapper page](https://docs.kentico.com/docsassets/guides/model-commerce-pages/product-wrapper-page.png "Reusable product and Product wrapper page")

> **Info:** **Pattern takeaway:** Keep reusable product data in the _Content hub_ and use wrapper pages only for channel-specific metadata and routing.

This separation gives you several practical advantages for commerce. You maintain a **single source of truth** - when you update a product description or feature list, the change automatically appears on every page and channel that references it. You can deliver the **same product across multiple channels** (websites, microsites, headless applications, email) without duplicating content. Your editors can adjust core product information once, rather than having to update the number of copies across different pages and channels.

In a traditional [page-based content model](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/design-page-based-content-model.md), all product information lives in a single page content type. This works for simple, single-channel websites, but creates duplication and maintenance overhead when you need to present the same product across multiple channels.

> **Tip:** If the content remains the same across all channels, store it in the reusable Product. If it differs by channel (website vs. mobile app vs. email), store it on the _wrapper page_.

For brevity, the rest of the material refers to _wrapper pages_ as _pages_ or _product pages_, unless noted otherwise.

## Model the reusable Product content type

Your reusable **Product** content type stores the core information that defines your product across all channels. Start with essential product fields: product _title_, product _description_, product _summary_ for listings, product _taxonomy_ for categories and tags, and key specifications, such as dimensions, technical details, and other attributes.

If you sell a variety of products that have unique attributes, you should consider creating multiple reusable _product_ content types with shared [reusable field schemas](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/reusable-field-schemas.md) to hold common product data. For example, the **Product core data schema** will hold content that you want to represent this product in listings: _name_, _description_, _price_, _thumbnail image_, and _category_. This schema ensures that every product type, whether it's a book, a piece of clothing, or an article promoting these products, has the same baseline fields for consistent presentation.

### Model modular content using linked content items

In many cases, products share the same features or bring customers similar benefits. For example, a _Fast access to funds_ benefit, or a _Travel insurance_ product feature can be linked to multiple banking products.

To avoid content duplication, you can create a **Product Benefits** content type with fields like _benefit description_, _benefit icon_ or image, and _target audience_. Then, you can create a **Product Features** content type with fields for feature _name_, feature _description_, _options for specialized display cases_ (checkbox), and feature _priority_.

Editors will use [combined content selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#combined-content-selector) in the _Product_ content type to link multiple _features_ and _benefits_.

![Linked product features and benefits in the Advanced account on the Kbank demo site](https://docs.kentico.com/docsassets/guides/model-commerce-pages/advanced_account_product_benefits.png "Linked product features and benefits in the Advanced account on the Kbank demo site")

> **Info:** **Pattern takeaway:** You can model reusable benefits and features as linked content items to avoid duplicating product attributes across products. If your features just contain text and don't need images, consider using taxonomies.

This approach lets the team reuse components across products. When they update, for example, the benefit's description or icon in one place, all products that reference it automatically get the update.

![Content reuse locator displays image reuse](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_shared_product_feature.png "Content reuse locator displays image reuse")

> **Info:** **Pattern takeaway:** Reused linked components allow editors to propagate their update to every product page that references the component.

Editors can display the product data, including _benefits_ and _features_, in widgets when needed, as shown in the following custom _Product comparator_ widget on the Kbank demo site.

![Product comparator widget on Kbank demo site](https://docs.kentico.com/docsassets/guides/model-commerce-pages/product_comparator_feature_display.png "Product comparator widget on Kbank demo site")

> **Info:** **Pattern takeaway:** To improve governance, you can build comparison experiences from structured linked content instead of storing repeated comparison tables per individual products.

Store product images as [Media file content items](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/store-files.md) with proper _alt text_ for accessibility and SEO. Link these media files to your _Product_ using the _Combined content selector_.

Find more details about [modeling reusable product SKUs](https://docs.kentico.com/guides/architecture/content-modeling/model-reusable-content/model-a-reusable-product-sku.md) in a dedicated material.

> **Warning:** **Fields to avoid in your reusable Product content type:**
>
> Never store _SEO metadata_, _Open Graph tags_, page _URLs_, or website publish dates in your reusable _Product_. These fields are channel-specific and belong in your _wrapper page_. Storing them in the reusable _Product_ creates confusion about which metadata applies to which channel and defeats the purpose of the two-layer architecture.

## Model the Product wrapper page content type

Your **Product page** content type provides the browsable URL (or its vanity URLs) and channel-specific context for displaying a product on your website. The most important field in your wrapper is the **Product reference**. Use a [content item selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#combined-content-selector) configured to accept only your _Product_ content type (or specific product variants if you support multiple product types). Set this field as required. To guide the editors, use a clear field label like _Select Product to Display_ with a helpful description: _Choose the reusable product this page will showcase._

![Kbank product page fields](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_account_page_field_descriptions.png "Kbank product page fields")

> **Info:** **Pattern takeaway:** Restrict wrapper page selectors to valid product types and add clear guidance to reduce editor mistakes.

Create or reuse an **SEO metadata schema** for search engine optimization fields. This schema can include, for example:

- _SEO title_ (text field to override the default title for search results),
- _SEO meta description_ (text area for the snippet shown in search results),
- _Canonical URL_ (to handle duplicate content across channels or pages),
- _Sitemap inclusion_ (checkbox to control whether this URL appears in sitemap.xml),
- _No-index directive_ (checkbox to prevent search engines from indexing this page, empty by default to make the page indexable),
- _SEO_ [structured data](https://developers.google.com/search/docs/appearance/structured-data/search-gallery) (structured data that developers generate into the page HTML markup),
- Other project-specific SEO fields.

![Demo SEO fields in the Kbank's Current Account page](https://docs.kentico.com/docsassets/guides/model-commerce-pages/Kbank_current_account_page_SEO_fields.png "Demo SEO fields in the Kbank's Current Account page")

> **Info:** **Pattern takeaway:** Keep _SEO_ and _Open Graph fields_ at the wrapper page layer so channel metadata stays separate from reusable product data.

Create or reuse an **Open Graph metadata schema** for social sharing. Review the Kbank demo site's _Open Graph_ reusable field schema for inspiration. At a minimum, include:

- _OG title_ (may differ from your SEO title, optimized for social networks),
- _OG description_ (optimized for social sharing, may differ from SEO description),
- _OG image_ (optimized for social media dimensions, may differ from your product's primary image),
- _Platform-specific properties_ for Facebook or Twitter cards.

Create dedicated fields or reuse a **Page publishing schema** for content management. You can include fields, such as _Publish date_ (override the default if needed), _last updated date_ (can be system-generated or manually overridden), and _author_ or _owner_ assignment.

Though we recommend using _Page Builder widgets_ to extend or customize the core product data, you might need to, in some cases, add **website-specific presentation fields** to your product page. Editors will use them to customize how the product appears on your website, and you need this data in a structured format. We have seen customers use fields such as the _hero banner_ image (different from the product's main image and specific to your website channel), _featured callout texts_ (promotional text that appears only on this specific page), and _page-specific calls to action_ (custom CTAs for this landing page).

> **Tip:** Use [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.md) widgets to present product data on your _wrapper pages_ rather than adding content fields to the _Content tab_. Using _widgets_ provides editors with more flexibility, supports personalization for different audience segments, and makes the editing experience more intuitive.

## Design Product listing pages

**Product listing pages** display collections of products. You use them for category pages (like _Business Banking Products_ or _Dog Accessories_), search results or filtered views, and department-level pages like _All Products_. Your listing pages can include [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.md) zones to let editors personalize which products appear for different audience segments.

You have two approaches for building product listings. **Approach A** uses query-based listings either through [page template presets](https://docs.kentico.com/documentation/business-users/website-content/page-templates.md#manage-preset-page-templates) with preconfigured widgets (recommended for most scenarios) or list content without the _Page Builder_. **Approach B** uses manual selection (recommended for curated collections).

### Query-based listings (Approach A)

In a **query-based listing**, your listing page does not directly reference individual products. Instead, editors configure filters and criteria, and products are dynamically retrieved based on [taxonomy](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) assignment, _tags_, dedicated _classification_ content types, or [smart folder criteria](https://docs.kentico.com/documentation/business-users/content-hub/content-hub-folders.md#smart-folders) in the _Content hub_.

This approach has clear benefits. Product listings automatically update when editors add new products that match the criteria. Your model reduces editorial maintenance by eliminating the need for editors to manually add products to every relevant listing. The approach scales well for large product catalogs.

For example, a _Business Banking Products_ page configured to filter by the _Business Banking_ taxonomy will automatically show all current and future products tagged with that category.

#### Use Page Builder with page template presets

We recommend using [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.md) to present product listings. This approach provides editors with the most flexibility and the best editing experience. Create a **Product Listing Page** content type with minimal structural fields, then use [page template presets](https://docs.kentico.com/documentation/business-users/website-content/page-templates.md#manage-preset-page-templates) to automatically populate preconfigured widgets when editors create new listing pages.

Your **Product Listing Page** content type can include:

- **Core content schema** (or create individual fields) for the page's _title_, _description_, and _thumbnail_
- **Configuration for filtering criteria**, such as a [taxonomy selector](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md#add-option-to-tag-content) to specify which categories or subcategories to display, tag filters to include or exclude specific tags, and content type filters if you want to show only certain product types.
- **Channel-specific metadata:** _SEO metadata schema_, _Open Graph metadata_, _hero_ or _banner content_ specific to this listing page.

> **Info:** _Pagination settings_ (such as number of products per page), _default sort order_ options, and other similar properties aren't product data. They define how product data, such as individual products or products from a single category, is presented. We recommend configuring data presentation via [page template properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder/page-template-properties.md) or [widget properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md), rather than storing it as part of the product data within the _Product Listing Page_ content type.

**Decide where editors will control presentation settings**

Editors can configure presentation options at the **template level** through [template properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder/page-template-properties.md) (affecting the entire page) or at the **widget level** through [widget properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md) (providing more granular control per widget instance). Template-level properties work well for consistent page-wide settings, such as default sort order or the number of columns, while widget-level properties give editors the flexibility to vary presentation within the same page.

Create _product listing widgets_ that read the filter criteria from your **Product Listing Page** content type and dynamically retrieve matching products. Expose key presentation options, such as _display style_ and _sort order_, through your chosen properties approach. Use [section properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/sections-for-page-builder/section-properties.md) to let editors adjust page layout elements like column count without requiring code changes if they prefer a more granular approach.

For inspiration, you can check the _Articles_ widget on the Kbank demo site. Editors can define subpages within a specific section of the Content tree and then further filter the selected content by tags or by specifying how many articles to include. Your _product listing widgets_ can work similarly.

![Kbank article widget properties](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_article_widget_properties.png "Kbank article widget properties")

> **Info:** **Pattern takeaway:** Use widget and template properties to control listing presentation without changing the underlying product model.

When editors create a new listing page, assign an existing [page template preset](https://docs.kentico.com/documentation/business-users/website-content/page-templates.md#manage-preset-page-templates) to automatically populate preconfigured widgets. This automation works particularly well when you create products and listing pages over [API](https://docs.kentico.com/api/content-management/pages.md).

This approach supports [widget personalization](https://docs.kentico.com/guides/digital-marketing/xperience-essentials/personalize-website-content-essentials.md) for different audience segments, allows editors to customize page layout without developer involvement, and provides the most intuitive editing experience.

> **Tip:** If you don't like the custom _Page Builder_ widgets, you might want to consider adding fields on the page's _Content_ tab where editors configure the listing.

#### Embrace developer-driven page rendering

If you decide to implement product listings programmatically with developers controlling the _presentation layer_ directly (rendering product data without _Page Builder_ widgets), you should still include _Page Builder_ capabilities for content personalization.

At minimum, add a [Page Builder editable area](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder.md#page-builder-components) through your page template properties. This allows editors to add supplementary content sections, such as:

- Personalized _Featured products_ widgets for different audience segments
- Promotional banners or callouts specific to certain visitor types
- Cross-sell or related product sections
- Marketing content that complements the programmatic product listing

This hybrid approach gives developers full control over the core product listing logic while preserving editorial flexibility for personalization and promotional content.

### Manual selection listings (Approach B)

In a **manual selection listing**, the product listing page directly references specific products using _widgets_ or a _content item selector_ configured to allow multiple product selections. Editors manually curate which products appear and control their order by dragging items in the selector.

This approach works well when _editorial curation is important_, especially for featured or curated collections, seasonal promotions that highlight specific products, or any scenario where you need full control over which products appear and in what order.

You can create a **Universal page** (or a dedicated **Product listing page**) content type with the same channel-specific metadata as above: SEO metadata schema, Open Graph metadata, and page-specific hero or banner content. Then define a product listing _page template_ with properties, allowed _sections_, and _Product widgets_ that editors can use to display product data on the website.

The following image shows how you can compare products that share the same modular Featured content properties. Editors select which products to compare, and developers ensure the data is properly displayed. You can use this approach to replace traditional comparisons, which were commonly defined through product comparison tables, meaning the data and features were often stored (and duplicated) within individual products.

![Product comparator widget on Kbank](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_product_comparator_widget.png "Product comparator widget on Kbank")

> **Info:** **Pattern takeaway:** Use manual selection when editorial curation and ordering matter more than automatic, catalog-driven updates.

Optionally, you can create a product listing page with a **Product selection** field. Besides SEO and other fields, it will include a _content item selector_ configured for multiple products, allowing editors to manually reorder selections on the Content tab, rather than using Page Builder widgets.

The following image shows the _Dancing Goat_ website, where editors use the _Event_ field to select events to be promoted on the Home page. The events can then be displayed on the website. In the Dancing Goat website’s case, only the first item is displayed. In real life, selected _events_ (or _products_ in your model) can be displayed through a slideshow widget, or dynamically without the editor’s intervention, based on a configuration prepared by the developers.

![Dancing Goat Event selector on Home page](https://docs.kentico.com/docsassets/guides/model-commerce-pages/dancing_goat_event_selector.png "Dancing Goat Event selector on Home page")

> **Info:** **Pattern takeaway:** Multi-select references on listing pages are effective for curated campaigns and limited spotlight collections.

> **Tip:** Choose **query-based listings** for **large catalogs** that need automatic updates. Choose **manual selection** for curated collections where editors need **control over product order, selection, and content personalization**.

## Design considerations for listing pages

### Consider how products will be filtered

Will you use [taxonomy tags](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/model-taxonomies.md), [content type fields](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md), [price ranges](https://docs.kentico.com/guides/architecture/content-modeling/model-reusable-content/model-a-reusable-product-sku.md#model-price-options-for-variants), or a combination? Decide whether editors need to override the automatic order or if products should always sort by date, popularity, or price. Determine whether featured products should appear first in each listing.

The following product listing allows editors to hand-pick products to display. Using widget [personalization](https://docs.kentico.com/documentation/developers-and-admins/digital-marketing-setup/content-personalization.md), they can easily tailor selected products to different audiences.

![Product listing widget on Kbank demo site](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_product_listing_widget_manual_selection.png "Product listing widget on Kbank demo site")

> **Info:** **Pattern takeaway:** Combine manual selection with personalization to tailor product visibility for different audience segments.

### Plan for listing edge cases

How will you handle empty listing pages when no products match the criteria? Will you show a _No products found_ message, display featured products as a fallback, or automatically redirect to a dedicated page?

### Choose a filtering approach

When modeling a listing page, decide which **filtering strategy** your product listings will use. Although the visitor-facing experience may look similar, the underlying implementation differs significantly and affects your content model.

**Search index-based filtering** uses a search engine (such as [Lucene or Azure AI Search](https://docs.kentico.com/documentation/developers-and-admins/third-party-integrations.md) integration) to filter products by facets included in the search index. With this approach, the search engine handles filtering logic, supports full-text search alongside faceted navigation, and performs well with large catalogs. However, you need to maintain a _search index_ that stays synchronized with your content, and your _filterable attributes must be explicitly mapped_ to the index. This approach is best suited for catalogs where visitors need to combine multiple filter criteria, such as _price_, _category_, _rating_, and _availability_, or when full-text search is a requirement.

**Direct content filtering** queries content items or pages directly based on their content type _field values_, _taxonomy_ assignments, or _content tree position_. This approach requires no additional infrastructure beyond your Xperience instance and gives you real-time access to the latest published content without index synchronization delays. However, _complex multi-facet filtering_ can become resource-intensive on large catalogs, and you may need to carefully optimize queries.

| Consideration             | Search index-based                        | Direct content filtering              |
| ------------------------- | ----------------------------------------- | ------------------------------------- |
| **Content freshness**     | Might be affected by index rebuild timing | Immediately after publishing          |
| **Performance at scale**  | Optimized for large catalogs              | Best for smaller to mid-size catalogs |
| **Infrastructure**        | Requires a search index                   | No additional setup                   |
| **Multi-facet filtering** | Handles complex combinations efficiently  | Can become costly with many facets    |

Your filtering strategy influences your content model. For **search index-based filtering**, ensure the product fields you want to filter by are structured and indexable (avoid storing filterable attributes in rich text fields). For **direct content filtering**, consider using [taxonomy tags](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/model-taxonomies.md), dedicated classification fields in a content type, or dedicated _categorization_ content types that support efficient querying.

Also consider whether you'll use _pagination_, infinite scroll, or _Load more_ buttons for long product lists. These decisions influence which _template properties_, custom _Page Builder_ widgets, or dedicated _fields_ on the _Content tab_ your listing pages will require.

The following image comes from the Khealth demo site which has since been retired and is no longer publicly available. It shows a location page where users can filter locations based on their preferences.

![Legacy Khealth demo - Location filtering](https://docs.kentico.com/docsassets/guides/model-commerce-pages/khealth_demo_site_facet_filtering.png "Legacy Khealth demo - Location filtering")

> **Info:** **Pattern takeaway:** Faceted filtering works best when filter dimensions are modeled as structured classification data rather than free text.

This legacy Khealth example implements filtering (and facets) using the content tree structure, where individual items represent filter options for services and locations, as shown in the following image.

![Legacy Khealth filtering based on the content tree](https://docs.kentico.com/docsassets/guides/model-commerce-pages/khealth_demo_site_facets_in_content_tree.png "Legacy Khealth filtering based on the content tree")

> **Info:** **Pattern takeaway:** Content tree-driven facets are viable when you model filter options as content items.

## Content governance considerations

When you configure your [content item selectors](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#combined-content-selector), limit the allowed content types to only the content types that should be referenced. For your _Product page_, configure the _Product_ selector to accept only _Product_ content types (or specific product variants). This prevents editors from accidentally selecting the wrong content type.

For example, the following image shows that Kbank's editors can select only product-specific content types, such as _Loan_, _Account_, _Card_, or _Insurance_, into the _Product_ page thanks to the selector's configuration.

![Product content item selector on Kbank demo site](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_product_content_item_selector_product_page.png "Product content item selector on Kbank demo site")

> **Info:** **Pattern takeaway:** Prevent invalid relationships at authoring time by defining constraints on the content item selector.

### Provide clear guidance for editors

Use descriptive field captions, like _Select product_, rather than just _Product_. Add helpful descriptions below the selector, such as _Choose the reusable product this page will showcase_. Include explanations about the content and its format to guide proper usage in all other fields.

The following image shows the product selector on the Kbank demo site. The page selector's additional description tells editors to _Select reusable Product item (Account, Loan, or Card) to display on your website._, leaving little room for doubt.

![Guidance below a selector in the Kbank's product page](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_account_page_selector_editor_guidance.png "Guidance below a selector in the Kbank's product page")

> **Info:** **Pattern takeaway:** Strong field captions and helper text improve editorial consistency and reduce training overhead.

> **Tip:** You can use the Xperience [Content modeling MCP server](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-mcp.md) to generate clear, editor-friendly labels and descriptions that your UX team can iterate over and improve.

### Establish ownership and [workflows](https://docs.kentico.com/guides/digital-marketing/work-with-workflows/workflows.md) before you start building content

Decide who manages the reusable _Product_ content items. Typically, this is a _product team_ or _merchandising team_ that owns the core product information, or _data entry specialists_ who work closely with the _product team_. Decide who manages _product wrapper pages_. This is usually your _marketing team_ or _web content editors_ who control channel presentation and SEO.

The following image shows a product page approval workflow with three steps. Different stakeholders, such as content editors, product managers, and administrators, need to approve the page content before it's published to the live site.

![Demo workflow created on Kbank website](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_product_page_workflow.png "Demo workflow created on Kbank website")

> **Info:** **Pattern takeaway:** You can separate ownership and approval workflows for reusable product data versus wrapper pages to reduce publishing risk.

### Plan your permissions and access structure

Use [workspaces](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/workspaces.md) to organize content by team or business unit. For example, you can configure role permissions for each content type so the _product team_ can edit _Products_ but only view _website pages_, and the marketing team can edit _wrapper pages_ but only view _Products_. To manage access to website pages, use the [page level permissions](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/page-permission-management.md).

As shown in the following image, editors on the _Business Banking_ team can work only with content items that target their customer persona: _B2B representatives_. All products, product components, and articles filtered in the _Content hub_ view fall under their business domain.

![Business Banking workspace on Kbank demo site](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_workspace_config_business_items.png "Business Banking workspace on Kbank demo site")

> **Info:** **Pattern takeaway:** Use workspaces and role-scoped access to align content ownership with business domains and editorial responsibilities.

> **Tip:** Test your permissions structure early by having team members from different roles create sample content items. This helps you identify permission gaps or workflow issues before you roll out the model to your full content team.

### Understand publishing dependencies

When you publish a wrapper page that references an unpublished _Product_, you may need [cascade publishing](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#cascade-publishing) to publish all items together. When you update a reusable _Product_, remember that the changes will appear on every wrapper page that references it. Establish a [notification process](https://docs.kentico.com/guides/digital-marketing/work-with-email/notifications-basics.md) so teams know when shared content changes.

The following image shows a product page with all the unpublished content items this page references. Xperience [cascade publishing](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#publish-content-items) allows publishing of all related content at once.

![Kbank product page with linked items shows publishing cascade](https://docs.kentico.com/docsassets/guides/model-commerce-pages/kbank_publish_cascade_product_page.png "Kbank product page with linked items shows publishing cascade")

## Multilingual considerations

When working with multilingual content, you need to decide what to translate and what to keep language-neutral. You can use [AIRA translations](https://docs.kentico.com/guides/digital-marketing/work-with-multilingual/optimize-aira-translation-prompts.md) to prepare content in different languages and then hand off different parts of the _wrapper page_ to different editor teams via [workflows](https://docs.kentico.com/guides/digital-marketing/work-with-workflows/workflows.md).

One editor team might need to validate SEO metadata (_title_ and _description_) for each language to ensure search results display correctly across markets. Social media managers might need to review translated Open Graph metadata to ensure social sharing displays properly in each language. Editors might need to customize the translation of language-specific CTAs and promotional text that appear only on that channel. Additionally, a product team might want to verify the translated _product data_ in the _Content hub_.

Some content typically stays language-neutral. Core product data may or may not require translation depending on your markets and products. Product specifications often remain universal across languages. Product SKUs, prices, and technical specifications usually don't need translation unless you have market-specific products.

Use Xperience's [language fallback](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md#language-fallbacks) feature appropriately. When a linked content item doesn't have a translation in the target language, Xperience shows a yellow border warning in the editing interface. Decide whether to use the fallback language for untranslated linked items or require full translation before publishing in each language.

## Naming conventions and organization

### Organize your content tree thoughtfully

Place _wrapper pages_ in a logical site structure such as `/products/[category]/[product-name]`. Use folders to group related products. In the _Content hub_, organize products using [content folders](https://docs.kentico.com/documentation/business-users/content-hub/content-hub-folders.md), [smart folders](https://docs.kentico.com/guides/development/advanced-content/deliver-content-dynamically-with-smart-folders.md) that automatically organize items by criteria, or [workspaces](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/workspaces.md) to separate products by business unit or team.

### Establish consistent URL patterns

Use a predictable structure like `/products/[category]/[product-slug]` so visitors and search engines can understand your site hierarchy. Use the [alternative URLs](https://docs.kentico.com/documentation/business-users/website-content/manage-page-urls.md) feature to handle redirects when you reorganize content. Use the canonicalization feature to indicate the primary URL when the same product appears on multiple pages or channels.

### Follow clear naming conventions for content items

Establish clear naming patterns for the editor teams.

Editors need to name their products clearly and descriptively to help with discovery across the system, especially if different teams manage different presentation layers: _Business Checking Account_, _Striped Grey T-shirt_, and _Professional Dog Grooming Kit._

Name _product (wrapper) pages_ to match the product name or add channel context: _Business Checking Account - Website_, or just _Business Checking Account_. When you have product variants, include a distinguishing suffix in the content item name: _Striped Grey T-shirt - S_, _Striped Grey T-shirt - M_.

## Avoid common modeling mistakes

Don't create overly complex _wrapper pages_ by adding too many fields, and keep your wrapper focused on channel-specific needs.

### Plan for future channels from the start

Design your reusable _Product_ content type with multi-channel delivery in mind, even if your project needs only a website today. We recommend avoiding channel-specific assumptions when modeling the core product data. This makes it easier to add mobile apps, microsites, or email campaigns later.

### Never duplicate data between your reusable content and wrapper

Apply this rule: if data is universal and describes the product itself, it belongs in the reusable _Product_ only. Developers need to ensure that the data is properly displayed across different channels.

We've seen a common mistake where editors added the same _product description_ to the _product_ and then to a _product page_ (and to _emails_) using a _widget_. We recommend avoiding this data duplication. When editors copy some information from the _Product_ content type to the wrapper, you're defeating the purpose of the two-layer architecture. It creates confusion about which description is authoritative and makes content updates difficult.

Provide editors with a widget to display core product data, and introduce [widget properties](https://docs.kentico.com/guides/architecture/content-modeling/model-website-presentation-components.md) so editors can use the properties strategically to override or even personalize the product data when needed.

### Use Page Builder to present product data

Use _Page Builder_ widgets and templates for presenting product data on _wrapper pages_ rather than adding presentation fields to the _Content tab_. Widgets provide greater flexibility, support personalization for different audience segments, and enhance the editing experience. You can [create page templates](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/design-website-content.md#design-content-using-templates) with pre-configured widget zones to speed up content creation, even if you create content through API.

### Establish governance rules for shared content from the start

Define clear ownership of _Product_ vs. _page content_. Set up [workflows](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md) and [permissions](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/page-permission-management.md) before you build a large amount of content. It's much harder to retrofit governance onto an existing content model than to build it in from the beginning.

> **Warning:** **Test the editing experience early.** Have developers or solution architects create sample content items using your proposed model. If the initial workflow passes, validate that the model makes sense from the editors' perspective. Ask editors to create a few products with real data and display this data on _website pages_ to identify any friction in the workflow. Iterate on the page model before you roll it out to your full team.

## Next steps

You've learned the architecture and modeling principles for commerce pages using the wrapper pattern, and you can implement it in your Xperience project.

Once your content model is in place, work with your development team to build the page templates and widgets that will present this product data on your website. As your content library grows, revisit your [folder organization](https://docs.kentico.com/documentation/business-users/content-hub/content-hub-folders.md), [workflows](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md), and [permissions](https://docs.kentico.com/documentation/developers-and-admins/configuration/users/role-management/page-permission-management.md) to ensure your governance structure scales effectively with your expanding product catalog.