Product
A product represents a single sellable item — a shoe model, a jacket, a bag. It carries a name, a brand, a product type, and a set of attributes. Every product is scoped to your organization, so you only ever see and edit your own catalog.A machine-readable identifier that stays the same across every
version of the product. Two records with the same key
are versions of the same product.
Where a given version’s data came from — for example merchant input, the brand
site, or AI-generated. Source is provenance, not identity: it also drives how
enrichment merges data when several sources
describe the same product (brand site > lakehouse > merchant input >
AI-generated).
The display name, the brand it belongs to, and the
product type whose properties it is
validated against.
Product-level attribute values (description, materials, care, and so on), keyed
by the property definitions its product
type declares.
Enrichment records a status for each product (for example pending, in progress,
complete, or needs review) and a completeness score indicating how much of the
expected data is filled in. Use these to spot products that still need work.
A computed summary of the product relative to the
publishing targets it has been sent to: draft
(never published anywhere), live (in sync with every target), or
changed (edited since it was last pushed to at least one target). This is
the signal the catalog uses — not a manual flag.
Products are versioned. Enrichment and edits create new versions rather than
overwriting, and the latest (or production-labeled) version usually holds the
richest data. See Versioning.
Variant
A variant is a specific buyable version of a product — a size / color / width combination, each typically with its own barcode. A product with three colors in five sizes has fifteen variants. Each variant belongs to exactly one parent product and carries its own variant-level property values.Unique within its parent product. Variant keys accept the formats merchants
already use — dots, spaces, and slashes are all allowed. The only rules are
that a key must be non-empty and contain no control characters, so you rarely
need to reformat an existing SKU or style code to load it.
Attribute values that vary per buyable version, such as size, color, width, and
barcode. Which properties live at the variant level (versus the product level)
is set on each property definition.
How variant properties are constrained
Property definitions carry a constraint that controls how a value may repeat across a product’s variants. The distinctions that matter most for variants:| Constraint | Meaning | Typical use |
|---|---|---|
combination_unique | The combination of these properties must be unique across the product’s variants | size, color, width — together they identify one variant |
unique | The value must be unique across all variants | upc_code (barcode) — no two variants share one |
same_for_all | Every variant shares the same value | Properties that never vary by size or color |
How they relate
A product is the shared identity and content; its variants are the individually buyable versions beneath it. Product-level attributes (description, features) describe the item as a whole; variant-level properties (size, color, barcode) distinguish one purchasable version from another. When you publish a product, its variants travel with it as the individual buyable versions (SKUs) at the target.Product types & properties
The templates and attribute schema that products and variants validate against.
Versioning
How versions, labels, and the production version work.