Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 33 ยท Commerce Modules and the Data Model

Products, Variants and Options

Model products in Medusa 2: options, variants, SKUs, handles, collections, categories, tags and metadata, plus the admin and store views of a product.

The Product module is the heart of the catalog. A T-shirt that comes in three sizes and two colors is one product with two options and up to six variants. Getting this model right early saves painful migrations later, and it determines how prices, stock and search behave.

This lesson explains the product model, how options and variants relate, the organizing tools (collections, categories, tags, metadata), and what the admin and the storefront each see. The general theory is in Variants and Options and Product Catalog Design; here we focus on Medusa's shape of it. Real Medusa code is read-only; the stand-ins generate variants and check SKUs so you can test the rules.

The product model

A product is the thing shoppers browse. A variant is the thing they buy. Each variant is one specific combination of option values.

flowchart TD
    P["Product<br/>Classic Tee"] --> O1["Option: Size<br/>S, M, L"]
    P --> O2["Option: Color<br/>Black, White"]
    P --> V1["Variant<br/>S / Black, SKU TEE-S-BLK"]
    P --> V2["Variant<br/>S / White, SKU TEE-S-WHT"]
    P --> V3["Variant<br/>M / Black, ..."]
    V1 -.-> PR["Price set (Pricing module)"]
    V1 -.-> IN["Inventory item (Inventory module)"]

Options define the choices; each variant picks one value per option. Prices and stock attach to variants, not products.

Important fields on a product include title, handle, description, status (for example draft or published), thumbnail, images, options, variants, collection_id, categories, tags and metadata. On a variant, the useful ones are title, sku, barcode, ean, upc, options (the chosen value per option), manage_inventory, allow_backorder and metadata. Exact fields can differ by version.

Why attach price and stock to variants? A large size can cost more than a small one, and a black shirt can sell out while the white one does not. The product is only the grouping.

Handles

The handle is a URL-friendly, unique identifier such as classic-tee. Storefronts use it for pages (/products/classic-tee). If you do not supply one, it is usually derived from the title. Treat handles as stable once published, because changing one breaks links and search rankings (E-commerce SEO).

SKUs

A SKU (stock keeping unit) is your internal code for a variant. It should be unique per variant, human-readable and stable. It is the bridge to warehouses and ERP systems, so duplicate or reused SKUs cause stock mix-ups. The Inventory module links variants to inventory items through their SKU-like identity (Inventory, Stock Locations and Sales Channels).

Organizing products

Tool Relationship Use for
Collection A product belongs to one collection Merchandising groups such as "Summer Drop"
Category A product can be in many; categories form a tree Navigation such as Clothing > T-shirts
Tag Many to many, flat labels Filters and quick grouping such as "organic"
Type One per product Broad kind such as "Apparel"
Metadata Free-form key/value JSON Your own extra fields

Use metadata for small, unstructured extras (a care instruction, an external ID). If the data needs validation, its own table, or heavy querying, create a custom module and link it instead (Custom Modules and Data Models).

Admin view versus store view

The same product has two audiences.

  • The Admin API shows everything, including drafts, internal metadata, every variant and inventory details.
  • The Store API shows only what a shopper may see: published products, in the requested sales channel, with prices calculated for a region or currency. Hidden or draft products never appear, and internal fields can be left out by selecting only the fields you want.

This split is why a product can exist in the admin but be missing from the storefront: it may be a draft, not in the sales channel tied to your publishable key, or have no price for the region.

Creating a product (read-only)

In real Medusa, products are created through the admin dashboard or the createProductsWorkflow. A sketch of the input (prices shown here use the amount form Medusa expects; see Prices, Currencies and Regions):

TypeScript
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"

await createProductsWorkflow(container).run({
  input: {
    products: [
      {
        title: "Classic Tee",
        handle: "classic-tee",
        status: "published",
        options: [
          { title: "Size", values: ["S", "M"] },
          { title: "Color", values: ["Black", "White"] },
        ],
        variants: [
          {
            title: "S / Black",
            sku: "TEE-S-BLK",
            options: { Size: "S", Color: "Black" },
            prices: [{ amount: 19, currency_code: "usd" }],
          },
          // ...one entry per combination you sell
        ],
      },
    ],
  },
})

Note that you list the variants you actually sell. Medusa does not force every combination to exist: a rare color may only come in two sizes.

Stand-in 1: generating variants from options

Generating all combinations is the Cartesian product of the option values. This stand-in builds the variant list and gives each a SKU from a prefix. It illustrates the idea behind the admin's "generate variants" helper; it is not Medusa's code.

JS Variants from options (cartesian product)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice how quickly the count grows: three options with 3, 2 and 2 values already make 12 variants. This is why catalogs should not turn every attribute into an option. Use options only for the choices that change what the shopper buys and that you must price or stock separately.

Stand-in 2: validating SKUs and handles

Catalog bugs are often data bugs. This stand-in checks the rules a healthy import should enforce: unique SKUs, URL-safe unique handles, every variant selecting a valid value for every option. It is a plain validator, the kind you would write in a workflow step before saving.

JS Validate a product import

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • Creating one product per color or size instead of one product with variants, which splits reviews, SEO and merchandising.
  • Making every attribute an option and exploding the variant count.
  • Reusing or editing SKUs after orders exist.
  • Forgetting that a published product also needs a price and a sales channel before the storefront can show it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do prices and stock attach to in the Medusa model?

    Variants are the purchasable units, so each variant has its own price set and inventory link. A product is the grouping shoppers browse.
  2. 2. A shirt has options Size (S, M, L) and Color (Black, White). What is the maximum number of variants?

    The combinations multiply, 3 x 2 = 6. You can create fewer if some combinations are not sold.
  3. 3. Which organizing tool lets a product appear in several places in a hierarchy?

    Categories form a tree and a product can belong to many of them. A product belongs to at most one collection.
  4. 4. A product exists in the admin but the storefront does not return it. Which is NOT a likely cause?

    Lowercase handles are normal. Draft status, sales channel scoping and missing prices all hide products from the Store API.

Summary

  • A product groups variants; options define the choices; each variant selects one value per option and carries a SKU.
  • Prices and inventory attach to variants through the Pricing and Inventory modules.
  • Collections, categories, tags, types and metadata organize products; use a custom module when metadata is not enough.
  • The Admin API shows everything; the Store API shows only published, channel-scoped, priced products.
  • Keep options for real purchase choices, keep SKUs unique and stable, and validate imports.

Next: Prices, Currencies and Regions