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.stable identifier
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.
provenance
Where a given version’s data came from — for example merchant input, the brand
site, the lakehouse, or generated content. Source is provenance, not identity:
it also drives how enrichment resolves a field that
several sources describe. Each property carries its own preferred order
(
source_priority), so the brand site can win a product’s name while generated
copy wins its description.Merchant-entered values aren’t protected by ranking — they’re protected by a
separate per-property guard, overwrite_merchant_input, which is off by
default. It ships on for exactly three fields — description, features, and
meta title — where enrichment may replace text you typed.core fields
The display name, the brand it belongs to, and the
product type whose properties it is
validated against.
the property values
Product-level attribute values (description, materials, care, and so on), keyed
by the property definitions its product
type declares.
completeness signals
Enrichment records a status for each product — for example pending, in
progress, complete, or failed — and a completeness score indicating how much of the
expected data is filled in. Use these to spot products that still need work.“Needs review” is not one of them: review is tracked on the
Job, which reports a needs-review count and can end in an
Awaiting review state, rather than on the individual product.
where it stands vs. targets
A computed summary of the product relative to the
publishing targets it has been sent to:
Draft (never published anywhere), Published (in sync with every
target), or Modified (edited since it was last pushed to at least one
target). This is the signal the catalog uses — not a manual flag; the API
reports these values as
draft / live / changed. The products table
shows the pill and a chip per target alongside it — see
reading publish status.Products are versioned. Enrichment creates new versions rather than
overwriting; ordinary edits update the latest version in place. 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.identifier within a product
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.
variant-level values
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:Creating variants in bulk
Nobody types fifteen variants by hand. Two tools create them for you.- Matrix generator
- Variant CSV upload
Give it the axes — the colors, the sizes, the widths — and it builds every
combination for you. It runs in three steps:
1
Choose the axes
Pick the values on each axis. Only variant-level properties that are
combination-unique or unique are offered, because those are the
ones that legitimately vary from one buyable version to the next. Enum
properties offer their allowed values; free-text ones take a
comma-separated list.
2
Preview the cross-product
MerchantOps shows you the full set of combinations, with a count, before
anything is saved. Three colors × five sizes previews fifteen rows.
Nothing has been written yet — go back and adjust an axis if the count
looks wrong.
3
Confirm
Confirming persists the previewed variants against the product in one
operation, and reports how many were created plus any rows that errored.
A third path exists if you’re already working in a spreadsheet: the
round-trip export writes variant rows alongside their
products, and the Excel importer reads them back. That’s the one to use when
you’re editing existing variants rather than creating a new set.
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.
Exporting products
Pull products and variants back out, with your columns or as a round-trip file.
Reading publish status
What the Draft / Published / Modified pill and per-target chips mean.