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.

The well-known vocabulary

wellKnownName and wellKnownSectionName are what make a row portable between connectors: the frontend maps a well-known name to a localized label, so a connector can emit its own upstream naming in name and still get a translated heading. Both fields are optional, and both accept a string outside the union, which passes through unmapped rather than failing.

WellKnownPropertyName identifies the row:

material, weight, dimensions, width, height, depth, length, circumference, diameter, volume, area, surface, warranty, countryOfOrigin, careInstructions, color, capacity

WellKnownSectionName groups rows under a heading:

general, dimensions, materials, care, technical, warranty, connectivity

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, 3 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

origin

"authored" | "derived"

Whether the backend chose this variant, or only named a candidate. authored — a merchant or a search result points at this variant on purpose. A consumer may surface that choice: preselect a swatch, call the variant out. derived — the connector had to name some variant and picked one, such as the first in stock or the first in the configurator. Use it as a target for add-to-cart, for sku in analytics, or for status. Never read it as a statement about what the shopper should see, because it moves as stock moves. An absent value means derived. A connector that declares no intent has none.

string

The variant this product opens on. An authored origin makes it a merchant's preference, a derived origin makes it a candidate only. 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.

sku

string

Stock-keeping unit of the named variant. Analytics destinations key an item on it, so a listing can report one without resolving any variant entity.

status

"inStock" | "outOfStock" | "backorder" | "preorder"

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.