Entities

Product

Product entity - components, queries, links, and related actions

Your storefront encounters the Product entity when fetching catalog data: category listings, search results, and product detail pages. A Product holds general information about a buyable good or service. It is not buyable by itself; instead, each Product links to one or more ProductVariant entities that represent the actual purchasable SKUs.

Components

Base

ProductBase

base

Product name and URL slug.

Schema

name

stringrequired

Name of the base-product. Variants may also have names for further description.

slug

stringrequired

Slug for usage in URLs.

customFields

Record<string, unknown>

Custom fields are a way for implementations to pass arbitrary data to actions, queries, etc.

Description

ProductDescription

description

Full HTML-formatted product description.

Schema

html

stringrequired

Specifications

ProductSpecifications

specifications

Ordered list of technical specification rows (schema.org PropertyValue). Each row pairs a canonical wellKnownName with a locale-resolved display name and a typed value (string | number | boolean | Measurement | Money) the frontend formats per locale, plus optional per-row section grouping. Rendered by TableProductSpecifications. Detail-only — resolve on the product detail page, not in listings.

Schema

properties

{ wellKnownName, name, value, 2 more }[]

Ordered specification rows. Absent ⇒ no specifications table is rendered.

Flags

ProductFlags

flags

Marketing labels like "New", "Sale", or "Bestseller".

Schema

array

variant

stringrequired

Style of the flag.

label

stringrequired

Text of the flag.

Info

ProductInfo

info

Cover image, short description, and brand reference. Used on product tiles and listing pages.

Schema

cover

Mediarequired

A Media object describes a media asset to be displayed or played in the browser. Currently supported are images, videos, and audio. Future support for 3D, 360° images, and other media types is planned. You can use type for type-narrowing.

shortDescription

string

Short product description. This may be used as subtitle on product-tiles. Not to be confused with the description-component which is the full html-description of a product.

brand

string

Brand of the product. Can also be used for manufacturer or vendor name.

brandLink

Link

A link to an internal or external page. Links can be of different types for different link-targets.

Media

ProductMedia

media

All product images and videos, including the cover image at index 0.

Schema

images

MediaImage[] { type, sources, alt, 2 more }required

All images of a product, including the cover-image on index 0.

media

Media[]required

All media: images, videos, 3d models and other media.

Prices

ProductPrices

prices

Aggregate pricing across all variants: selling price, strikethrough price, sale indicators, and unit pricing.

Schema

price

Money { amount, currency }required

strikethroughPrice

Money { amount, currency }

isOnSale

booleanrequired

If true, indicates that the product is discounted from its original price. See strikethroughPrice for the original price and savingsPercent for the percentage of discount.

savingsPercent

number

Percentage of discount from the strikethroughPrice.

isStartingFrom

booleanrequired

If true, indicates that there are multiple variants with different prices. Can be used in the frontend to indicate a starting-from price, e.g. "from 100 EUR".

unitPrice

UnitPrice { price, quantity, reference }

Rating

ProductRating

rating

Average review score (1-5) and total review count.

Schema

average

numberrequired

A rating between 1 and 5. That's the most common rating scale. No other scale is supported at the moment. Decimals are allowed.

min1max5

count

numberrequired

Number of ratings.

SEO

ProductSeo

seo

Meta title, description, and robots directive for the product detail page.

Schema

title

string

description

string

robots

string

E.g. "index, follow", "noindex, nofollow", etc.

Analytics

ProductAnalytics

analytics

Query parameters for PDP links and custom tracking fields.

Schema

pdpLinkQuery

Record<string, string>

Query parameters to be added to the product detail page link.

custom

Record<string, unknown>

Custom fields are a way for implementations to pass arbitrary data to actions, queries, etc.

Brand

ProductBrand

brand

Brand or manufacturer name with an optional link to the brand page.

Schema

name

string

Name of the brand.

link

Link

A link to an internal or external page. Links can be of different types for different link-targets.

Default Variant

ProductDefaultVariant

defaultVariant

Preferred variant ID or option values to preselect on the product detail page.

Schema

string

Some products may have a default variant or prefer showing a specific color-variant by default. Respecting this property is up to the frontend components.

options

string[]

A default variant can also be specified by a list of option values instead of a single id. E.g. ["clay", "small"] or ["red", "2xl", "cotton"] Respecting this property is up to the frontend components.

Option Groups

ProductOptionGroups

optionGroups

The product's variant-selection axes and all possible values, such as Size → S, M, L and Color → Red, Blue. Available combinations are derived from the linked variants.

Schema

groups

{ wellKnownName, name, values }[]required

Queries

ProductBySlug - Retrieve a single product by its slug.
ProductsByCategoryId - Retrieve multiple products by a category ID.
ProductsByCategorySlug - Retrieve multiple products by a category slug.
ProductSearch - Search for products using a query string.