Products and variants

A product holds the information shared by a merchandise concept. A product variant represents one sellable choice and owns its SKU, barcode, weight, selected attribute values, media, prices, inventory relationship, status, and publications.

Decide what belongs at each level

Put names, descriptions, vendor, tags, categories, collections, and product-wide metafields on the product. Put a value on the variant when it changes what the buyer selects or what operations fulfill, such as size, color, material, SKU, barcode, weight, price, or stock.

For a product with no meaningful options, create one variant. Storefront cart line items still point to a variant rather than directly to a product.

Attributes describe selectable differences

Create reusable attributes and their allowed values before assigning them to products. Product attribute assignments define which dimensions apply; each variant then selects the relevant values.

Use attributes for structured merchandising data that drives selection or discovery. Use tags for lightweight product labels, and use metafields for project-specific structured data that does not belong in the core catalog model.

For example, a lamp product can hold the shared name, description, vendor, and collection. Two variants—black and white—each hold their own SKU, color attribute value, gallery, price records, and inventory entries. Changing the selected color in the storefront changes the variant and its commercial data without duplicating the product description.

Lifecycle and publication are separate

Products and variants each have DRAFT and ACTIVE states. They also have their own channel publications. A resource must have the correct state and publication context before it can participate in a Storefront catalog.

Create content as a draft while required data is incomplete. Activate and publish deliberately after variants, prices, and inventory are ready. The full decision is described in Catalog visibility.

Prices and inventory are independent records

Do not put a display price or stock count in metadata. Variant prices are dedicated records that can vary by channel, country, customer group, currency, and validity window. Inventory entries connect the variant SKU to a supply channel and define an allocation strategy.

See Prices and Inventory.

Media and the hero variant

Media can be attached to variants and ordered for display. The product exposes a heroVariant for featured product presentation. Keep variant-specific imagery on the corresponding variant so option changes can update the gallery correctly. Use the image optimization parameters when rendering responsive assets.

  1. Create reusable attributes and attribute values.
  2. Create the product with a stable slug and its shared content.
  3. Add variants with unique SKUs and selected attribute values.
  4. Attach and order variant media.
  5. Create price records for each required market context.
  6. Create inventory entries for tracked SKUs and supply channels.
  7. Activate and publish the product and sellable variants.

Use bulk variant, price, and inventory mutations for larger imports, but follow the documented transaction behavior of each operation. Inventory bulk creation, for example, is transactional and accepts at most 100 entries. See Bulk operations and sync jobs.

API reference