> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantops.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Products & variants

> How products and their buyable variants are modeled in MerchantOps.

The catalog is built from two related entities: a **product** (the item you sell)
and its **variants** (the individual buyable versions of it). This page explains
what each holds and how they relate. For the vocabulary used across the docs,
see [Core concepts](/getting-started/concepts).

## Product

A product represents a single sellable item — a shoe model, a jacket, a bag. It
carries a name, a brand, a [product type](/catalog/product-types-properties), and
a set of attributes. Every product is scoped to your organization, so you only
ever see and edit your own catalog.

<ResponseField name="key" type="stable identifier">
  A machine-readable identifier that stays the same across every
  [version](/catalog/versioning) of the product. Two records with the same key
  are versions of the same product.
</ResponseField>

<ResponseField name="source" type="provenance">
  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](/getting-started/concepts) merges data when several sources
  describe the same product (brand site > lakehouse > merchant input >
  AI-generated).
</ResponseField>

<ResponseField name="name / brand / product type" type="core fields">
  The display name, the [brand](/catalog/brands) it belongs to, and the
  [product type](/catalog/product-types-properties) whose properties it is
  validated against.
</ResponseField>

<ResponseField name="attributes" type="the property values">
  Product-level attribute values (description, materials, care, and so on), keyed
  by the [property definitions](/catalog/product-types-properties) its product
  type declares.
</ResponseField>

<ResponseField name="enrichment status & score" type="completeness signals">
  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.
</ResponseField>

<ResponseField name="publish status" type="where it stands vs. targets">
  A computed summary of the product relative to the
  [publishing targets](/getting-started/concepts) 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.
</ResponseField>

<Note>
  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](/catalog/versioning).
</Note>

## 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.

<ResponseField name="variant key" type="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.
</ResponseField>

<ResponseField name="properties" type="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](/catalog/product-types-properties).
</ResponseField>

### 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                   |

<Tip>
  Configure `size`, `color`, and `width` as **combination-unique** and the barcode
  (`upc_code`) as **unique**. That lets one product carry every size/color/width
  buyable version without collisions, while keeping barcodes one-to-one.
</Tip>

## 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.

<CardGroup cols={2}>
  <Card title="Product types & properties" icon="sitemap" href="/catalog/product-types-properties">
    The templates and attribute schema that products and variants validate against.
  </Card>

  <Card title="Versioning" icon="code-branch" href="/catalog/versioning">
    How versions, labels, and the production version work.
  </Card>
</CardGroup>