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 properties. 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 a value your feed or import supplied.A product property you change by hand is additionally marked as a manual
edit, which no automated run overwrites — on any property, including those
three — until you Reset to feed. A variant property you edit by hand
now carries the same mark, but with a narrower guarantee: it protects the value
from feed imports, not from every automated write.core fields
The display name, the brand it belongs to, and the
product type whose properties it is
validated against.
product-level values
Property values shared across all the product’s variants (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
Where the product stands relative to each
publishing target. The products table shows one
pill per enabled target: live, modified, failed, scheduled,
publishing, or never published, and hovering a pill shows the
version, when, who, the batch, and the job. This is computed, not a manual
flag. A summary is still kept for filtering: Draft (never published
anywhere), Published (in sync with every target), or Modified (edited
since it was last pushed to at least one target), which the API reports as
draft / live / changed. 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
Property 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.
Editing variants in bulk
Select variants in the variants table and open Mass Update to change a property across all of them in one action. The dialog has two modes.- Set value
- Find & replace
Choose a property and a single value, and every selected variant gets that
value. This is the mode to use for a value that is genuinely the same on all
of them.System properties — Variant Name among them — are not offered here.
Assigning one name to hundreds of variants is almost always a mistake, so
those properties are reachable only in Find & replace.For an enum property, the value control is a searchable list of the
property’s allowed values. If the value you need isn’t there yet, Add to
master list creates it on the property
definition and selects it, without
leaving the dialog. That affordance appears only if you hold the
property-definition write permission.
Matching is literal, never a pattern. The find string is taken exactly as
typed — no wildcards, no regular expressions — every occurrence within a value
is replaced, and the replacement is inserted verbatim. A case-insensitive match
leaves the surrounding text exactly as it was stored.
Preview before you replace
Find & replace previews the whole change server-side before anything is written. The preview reports:
Up to ten before/after samples are shown so you can see the shape of the edit.
The preview refreshes as you type, and confirming is blocked while a preview is
stale or reports zero changes.
Both modes are all-or-nothing: MerchantOps validates the resulting values
against the product’s variant constraints — including collisions the edit would
create within the batch itself — and if any variant would violate one, nothing
is written and the offending variants are named.
Selecting across pages
The header checkbox selects the current page; Select all N matching extends the selection to every variant matching your current search and filters, not just the visible rows, and the banner then reads “All N matching variants selected”. Changing the search or a filter clears the selection, since it no longer describes what you picked. Very large result sets are capped — you are told how many were selected out of how many matched, and asked to narrow the filter to select more.Values you set through Mass Update are marked as manual edits, so the next feed
import keeps them instead of overwriting them. See
Manual edits.
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 properties (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 property 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 per-target publish pills and publishing history mean.