Docs: Products & variants

A product is the thing a customer recognises. A variant is the thing you actually ship. Almost every operational field — SKU, barcode, price, weight, stock — lives on the variant, and almost every marketing field — title, description, media, category — lives on the product.

The shape of a product

titlestringrequired: The customer-facing name. Channels may transform it, but they do not own it.
handlestringrequired: URL-safe identifier, unique within the project. Stable across renames.
descriptionrich text: Authored in the editor, stored structured, rendered per channel.
optionsarray: Up to three axes, e.g. size and colour. The cross-product defines the variants.
mediaarray: Images and video, served through the CDN with per-channel derivatives.
status'draft' | 'active' | 'archived'required: Only active products are eligible for listing; archiving never deletes history.

Variants carry the operational truth

Each variant has a SKU, an optional barcode, a base price, dimensions and weight. Two rules save a great deal of pain later:

A SKU is permanent. Reusing a retired SKU for a different product corrupts every historical report and confuses every marketplace that has ever listed it.
A barcode is a fact, not a preference. Where a GTIN exists, put it in. Several marketplaces match on it, and matching beats mapping every time.

Worth knowing

Changing a variant's option values after it has sold rewrites the meaning of past orders. Create a new variant instead and archive the old one — the order history stays honest and the reports keep reconciling.

Categories versus channel taxonomies

Your categories are for your team: they drive navigation, reporting and rules. A marketplace's taxonomy is theirs, and it changes without asking you.

Keep them separate. Map your category to a channel taxonomy node once, and the mapping survives you reorganising your own tree.

Pricing

Prices resolve in a fixed order, first match wins:

Precedence	Source	Typical use
1	Listing override	A one-off marketplace price
2	Channel price list	Retail vs trade vs a specific marketplace
3	Customer group price	B2B account pricing and contract rates
4	Variant base price	Everything else

This is why B2B and B2C can share one catalog: the difference between them is a price list and a set of rules, not a second product record.

Rich content

Descriptions, landing copy and campaign blocks are authored in the block editor and stored as structured content rather than a blob of HTML. That means the same description can render as clean markup on your storefront and as plain text where a marketplace demands it, without a second version to maintain.

Bulk work

Anything you can do to one product you can do to ten thousand: CSV import and export, a bulk edit queue, and the API for everything else. Bulk jobs report per-row, so a failed import tells you which 12 rows failed rather than that it failed.

Next: Inventory, where those variants get quantities and channels start competing for them.