Catalog products and variant selection

A catalog product groups concrete product variants into one buyer-facing presentation. A blue T-shirt can therefore offer four sizes on one detail page while price, availability, and the cart continue to use the selected variant.

Keep the concepts separate

Concept	Owns	Does not own
Product family	Technical attribute schema and variant axes	Buyer-facing grouping, URL, and publication
Product variant	SKU, price target, stock target, and cart item	Shared product-detail identity
Catalog product	Buyer-facing identity, shared product number, and allowed variants	Variant SKU, price, stock, and checkout decisions
Catalog product publication	Channel visibility, search visibility, and presentation variant	Variant publication or lifecycle
Catalog product site route	Canonical URL and presentation context per site and locale	Product identity or a forced purchase variant
Product collection	Curated or dynamic merchandising selection	Variant-family rules
Bundle	A sellable composition of several items	Buyer-facing variant family

Example: a T-shirt with colors and sizes

Create every purchasable combination as a product variant. A blue T-shirt in S, M, L, and XL therefore consists of four variants. The catalog product connects those variants with any other colors that should be selectable on the same detail page.

The family_axes selection mode requires all members to belong to one product family. That family defines the variant axes, such as color and size.

Distinguish product number, key, and SKU

The optional product number identifies the shared catalog product, for example TSHIRT-BLUE. It is unique within a tenant and can be used in administration and public catalog product searches. Each purchasable size keeps its own SKU, such as TSHIRT-BLUE-M.

The technical key is generated from the name when the catalog product is created and remains immutable. It supports internal contracts and is neither the product number nor the URL. You can add or change the product number later, while the site route controls the URL independently for each site and locale.

Which variant is shown first

Workspace evaluates selection input in this order:

explicit URL options,
proven search, filter, or collection context,
site-route presentation context,
the catalog product publication's presentation variant,
the first public purchasable variant, followed by the first public variant in deterministic order.

A search for red T-shirts may therefore present the red option. A size is carried from context only when its axis is explicitly configured as contextual. Otherwise explicit_only applies and the visitor must choose a size.

If the configured presentation variant is no longer public, Workspace uses the next allowed variant in the fixed order. An explicitly selected combination that remains public but is unavailable stays visible; Workspace does not silently replace its color or size.

Presentation is not a purchase decision

The public response separates two fields:

presentationVariantId controls the initial presentation, such as imagery and the preliminary pricing request.
resolvedVariantId is present only when the selection identifies exactly one concrete variant.

selectionStatus is one of none, partial, resolved, invalid, or unavailable. missingAxes identifies choices that are still required. Only a fully resolved variant may be added to the cart together with the current server pricing revision.

URLs per site and locale

Catalog product identity is independent of a URL. Each site and locale may therefore have its own catalog product site route. The canonical URL has no option parameters; color and size are presentation state and are not included in the sitemap.

An active route must be unique per site and locale. If Workspace detects multiple active targets for the same normalized path, it serves none of them. Resolve the conflicting routes in administration.

Managing files and assets

The Files tab manages files uploaded for the catalog product. Workspace binds them to the current catalog product so that they are not accidentally offered for selection on another product.

The Assets tab links one of these files to PIM metadata such as purpose, status, ordering, and translated alternative text. Media purposes are maintained separately as master data. If files, purposes, or other required master data are missing, the relevant tab shows a readiness notice with a link to the appropriate next step.

Linking a file does not publish it. Only the explicit asset publication action marks it as released; unpublishing returns it to draft. Both actions are audited. The asset is delivered publicly only while the linked storage object is public and the catalog product remains approved in the current sales channel.

Collections and search results

Lists and Site components separate their result target from their link target. resultMode chooses whether an item represents a catalog product or a product variant. linkMode chooses whether the link opens the shared catalog product page or a concrete variant. A catalog product link carries proven axis context into the shared selection page.

Check publication readiness

A catalog product publication does not publish its members. Every variant still needs a valid variant publication and must satisfy the existing lifecycle, content, price, media, and availability contracts.

Before approval, Workspace checks at least that members exist, family_axes uses one family, the presentation variant is a member, member variants are public in the selected channel, no approved listed catalog product overlaps in that channel, and released catalog product content exists.

Removed, hidden, or unpublished variants are never returned as candidates or diagnostic details by the public API.

While any catalog product publication is approved, its member set is locked. Unpublish every approved channel publication before adding, changing, or removing variants.