Entities

ProductVariant

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

Your storefront encounters the ProductVariant entity when displaying a specific purchasable SKU within a Product. Each variant represents a distinct combination of option selections (such as size or color) with its own SKU, pricing, availability, and shipping details. A Product links to its variants through the ProductVariants link; a ProductVariant does not exist independently of its parent Product.

Components

Base

ProductVariantBase

base

Variant SKU, name, and optional GTIN identifier.

Schema

sku

stringrequired

The merchants internal stock keeping unit (SKU) of the product variant.

name

stringrequired

The variant-specific name. Complements the product name.

gtin

string

The external product identifier (GTIN, EAN, etc.) of the product variant.

Availability

ProductVariantAvailability

availability

Stock status, inventory quantity, and optional restock date.

Schema

status

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

quantity

numberrequired

The current approximate inventory level for the variant.

availabilityDate

unknown

Date when the product is available again.

Prices

ProductVariantPrices

prices

Selling price, strikethrough price, sale indicators, unit pricing, and lowest prior price for regulatory compliance.

Schema

price

{ amount, currency }required

strikethroughPrice

{ amount, currency }

isOnSale

booleanrequired

If true, indicates that the product variant 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.

unitPrice

{ price, quantity, reference }

lowestPriorPrice

{ amount, currency }

Info

ProductVariantInfo

info

Variant-specific image.

Schema

image

{ type, sources, alt, 2 more }

Shipping

ProductVariantShipping

shipping

Shipping cost, whether shipping is required, and delivery time forecast with optional cutoff time.

Schema

rate

{ amount, currency }

required

booleanrequired

If true, the product variant requires shipping. E.g. it is a physical good.

forecast

{ minDays, maxDays, cutoffTime }

Quantity Prices

ProductVariantQuantityPrices

quantityPrices

Tiered pricing tiers based on purchase quantity; each tier specifies a minimum quantity, the applicable price, and the savings percentage.

Schema

array

quantity

numberrequired

The quantity above which the price is applicable.

price

{ amount, currency }required

savingsPercent

numberrequired

The amount of savings compared to the price without quantity discount. In percent.

Quantity Rule

ProductVariantQuantityRule

quantityRule

Minimum and maximum order quantities along with a quantity increment constraint.

Schema

increment

numberrequired

The quantity increment between min and max. All valid quantities must be divisible by this value. Must be less than or equal to min and max.

max

number

If set, must be lower than or equal to the minimum. Must be a multiple of the increment.

min

numberrequired

Minimum quantity a user has to purchase. Must be a multiple of the increment.

Options

ProductVariantOptions

options

Selected option values (e.g. color, size) for this variant, with optional swatch and preview image.

Schema

selected

{ wellKnownName, name, value }[]required

List of product options applied to the variant.

swatch

["color", string] | ["colors", string[]] | ["gradient", string[]] | ["image", object]

image

{ type, sources, alt, 2 more }

Product - The parent product this variant belongs to.
CartItem - A line item in the cart that references this variant.

Edit this pageorReport an issue

Comment

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