variant-matrix

# Variant Matrix

## Overview

Product variants let one product listing cover all size/color/material combinations — each with its own price, SKU, and inventory. Platforms generate the full matrix of combinations from your option values and handle the variant selector UI automatically. The main tasks are: entering options correctly, generating all SKUs, setting per-variant pricing and inventory, and managing large matrices efficiently.

## When to Use This Skill

- When modeling apparel, footwear, or accessories where products have multiple option axes
- When importing products from a supplier CSV with flat variant rows that need to be grouped
- When building an admin interface for merchants to manage variant pricing and inventory
- When a variant selector on the product page needs to disable unavailable combinations

## Core Instructions

### Step 1: Determine platform and understand the variant model

| Platform | Options | Max Variants | Variant Fields |
|----------|---------|-------------|----------------|
| **Shopify** | Up to 3 options (e.g., Size, Color, Style) | 100 per product | Price, SKU, barcode, inventory, weight, image |
| **WooCommerce** | Unlimited attributes used as variations | Practically unlimited (performance degrades at ~50+) | Price, sale price, SKU, stock, weight, dimensions, image |
| **BigCommerce** | Unlimited options per product | 600 SKUs per product | Price adjustment, SKU, stock, weight, image |
| **Custom / Headless** | Design your own | Unlimited | Design your own variant fields |

---

### Step 2: Platform-specific variant setup

---

#### Shopify

**Creating variants from options:**

1. Go to **Admin → Products → [Product]**
2. Scroll to the **Options** section
3. Click **Add option** to add the first axis (e.g., Size)
4. Enter the option values: XS, S, M, L, XL
5. Add a second option (e.g., Color): Red, Blue, Black
6. Shopify generates all combinations automatically (5 × 3 = 15 variants)
7. Scroll to the **Variants** section to see the generated matrix

**Setting per-variant details:**
- Click any variant row to edit its price, SKU, inventory, weight, and image
- Or use **Edit variants** bulk view to update multiple variants at once

**Bulk variant management:**
- Select multiple variants using checkboxes → **Edit** to update price or inventory for a group
- For large catalogs: use **Matrixify** (App Store) to import a CSV with one row per variant — the most efficient way to set up a large matrix

**Disabling unavailable combinations:**
- Variants that have no inventory automatically show "Sold Out" on the product page
- Shopify's variant selector does not auto-disable unavailable combinations by default — most themes require adding logic or using a theme app to grey out sold-out options

**Adding/removing option values after launch:**
- Add a new size (e.g., "XXL"): go to the Options section, add the value
- Shopify adds new variants for the new value; existing variants are unchanged
- Archive discontinued variants instead of deleting — deletion removes order history links

---

#### WooCommerce

**Creating variations from attributes:**

1. Create global attributes: **Products → Attributes → Add Attribute** (e.g., Size with values XS, S, M, L, XL)
2. On your product, go to the **Attributes tab**
3. Select your attribute (Size), check **Used for variations**, click **Add**
4. Add all values this product uses
5. Go to the **Variations tab**
6. Click **Generate variations** → WooCommerce creates one variation per combination
7. Expand each variation to set price, SKU, stock, and image

**Bulk variation updates:**
- WooCommerce's variation editor can be slow for products with 20+ variations
- Use **WP All Import Pro** for importing large variation matrices via CSV
- Or use the **Variable Product Bulk Edit** plugin for batch price/inventory updates

**SKU generation:**
WooCommerce doesn't auto-generate SKUs. Enter them manually or use a pattern:
- Convention: `[PRODUCT-CODE]-[SIZE]-[COLOR]` → e.g., `SHIRT-M-RED`
- Use WP All Import to set SKUs in bulk from a spreadsheet

---

#### BigCommerce

**Creating options and variants:**

1. Go to **Products → [Product] → Variations tab**
2. Click **Create options** and add your option set (Size, Color, etc.)
3. BigCommerce generates the matrix of SKUs automatically
4. Click any SKU row to set:
   - Price adjustment (e.g., +$5 for XL)
   - SKU code
   - Stock quantity
   - Image

**Option Sets:**
- Go to **Products → Option Sets** to create reusable option groups
- Create a "Clothing Sizes" option set with XS–3XL once, then assign it to all apparel products
- Saves significant time when managing large catalogs

**Bulk SKU management:**
- Go to **Products → Import & Export** to export the catalog with all variant SKUs
- Edit in Excel and re-import for bulk price/inventory/SKU updates

---

#### Custom / Headless

Build variant generation from Cartesian product of options, with diff logic to safely update existing catalogs:

```typescript
// lib/variantMatrix.ts

// Generate all variant combinations from option value arrays
// Input:  [['S','M','L'], ['Red','Blue']]
// Output: [['S','Red'], ['S','Blue'], ['M','Red'], ['M','Blue'], ['L','Red'], ['L','Blue']]
export function cartesianProduct(arrays: string[][]): string[][] {
  return arrays.reduce(
    (acc, values) => acc.flatMap(combo => values.map(v => [...combo, v])),
    [[]] as string[][]
  );
}

// Generate variant records with auto-generated SKUs
export function generateVariants(baseSku: string, optionNames: string[], optionValues: string[][]) {
  const combinations = cartesianProduct(optionValues);
  return combinations.map(combo => ({
    sku: [baseSku, ...combo].join('-').toUpperCase().replace(/\s+/g, '-'),
    options: Object.fromEntries(optionNames.map((name, i) => [name, combo[i]])),
    price: null,       // Set individually or via bulk rule
    inventoryQuantity: 0,
    published: true,
  }));
}

// Compute what to create vs. archive when option values change
export function diffVariants(
  existingVariants: { options: Record<string, string> }[],
  newCombinations: string[][],
  optionNames: string[]
) {
  const existingKeys = new Set(existingVariants.map(v => optionNames.map(n => v.options[n]).join('|')));
  const newKeys = new Set(newCombinations.map(c => c.join('|')));

  const toCreate = newCombinations.filter(combo => !existingKeys.has(combo.join('|')));
  const toArchive = existingVariants.filter(v => !newKeys.has(optionNames.map(n => v.options[n]).join('|')));

  return { toCreate, toArchive };
}

// Variant selector logic — which values are available given current selections?
export function getAvailableOptionValues(
  variants: { options: Record<string, string>; inventoryQuantity: number }[],
  currentSelections: Record<string, string>,
  targetOptionName: string
): string[] {
  return variants
    .filter(v =>
      Object.entries(currentSelections)
        .filter(([name]) => name !== targetOptionName)
        .every(([name, value]) => v.options[name] === value)
      && v.inventoryQuantity > 0
    )
    .map(v => v.options[targetOptionName])
    .filter(Boolean);
}
```

---

### Step 3: Define a SKU naming convention

Consistent SKUs are critical for warehouse operations, reporting, and supplier communication. Establish a naming pattern before importing products.

**Recommended format:**
```
[PRODUCT-CODE]-[OPTION1]-[OPTION2]

Rules:
- Max 20 characters total
- All uppercase
- Hyphens between segments, no spaces
- Use standard size abbreviations: XS, S, M, L, XL, 2XL
- Use 3-letter color codes: RED, BLU, BLK, WHT, NVY, GRN
- Example: SHIRT-M-BLU → Blue shirt, Medium
           SHOE-10-NVY → Navy shoe, Size 10
```

Use Matrixify (Shopify) or WP All Import (WooCommerce) to bulk-assign SKUs following this pattern for an existing catalog.

---

### Step 4: Manage large variant matrices

For products with many combinations (50+ variants):

**Shopify:** The 100-variant limit may be an issue for products with 3+ options. Strategies:
- Combine two options into one (e.g., "Size/Width" instead of separate Size and Width options)
- Create separate product records for each color and use metafields to link them
- Use Shopify's native Bundles for configurable products that require more flexibility

**WooCommerce:** Performance degrades with 50+ variations on one product. Use **WooCommerce Performance Optimizations** or **YITH WooCommerce Variations Table** to improve the admin and storefront experience.

**Lazy variant creation:** For extremely large matrices (e.g., custom paint colors × finish × size = 500+ SKUs), generate variants on demand when first ordered rather than pre-creating all combinations:

```typescript
// For very large matrices: create variants on first request rather than upfront
export async function ensureVariantExists(productId: string, options: Record<string, string>) {
  const key = Object.values(options).join('|');
  const existing = await db.productVariants.findFirst({ where: { productId, variantKey: key } });
  if (existing) return existing;

  const product = await db.products.findUnique({ where: { id: productId } });
  return db.productVariants.create({
    data: {
      productId,
      sku: generateSku(product.baseSku, options),
      variantKey: key,
      options,
      price: applyPricingRules(product, options),
      inventoryQuantity: 0,
    },
  });
}
```

## Best Practices

- **Archive variants, never delete them** — deleted variants break historical orders that reference them; mark as `published: false` when discontinued
- **Use the platform's bulk edit tools for price and inventory updates** — editing 100 variants one at a time is impractical; all platforms support bulk edits
- **Limit options to 2–3 axes** — beyond 3 options (e.g., size × color × material), the variant selector becomes confusing and the matrix grows exponentially
- **Test the variant selector before launch** — verify that selecting an unavailable combination shows the correct "sold out" state and that the price/image updates correctly
- **Validate SKU uniqueness** before bulk importing — a SKU collision during import silently skips the conflicting row or throws an error depending on the platform

## Common Pitfalls

| Problem | Solution |
|---------|----------|
| Shopify 100-variant limit reached | Combine options or create separate products per color; use metafields to group related products in the storefront |
| Variant image not switching on option select | Assign variant-specific images explicitly per variant; the platform can only switch images if the variant has its own image set |
| Adding a new option value creates duplicate variants | Use diff logic to detect which combinations are genuinely new; Shopify handles this correctly in the admin, but custom imports need deduplication |
| Large matrix slows product page load | For 100+ variants, fetch variant availability via API on option change rather than embedding all variants in the initial page HTML |
| SKU collisions during bulk import | Normalize SKU segments before generating: `toUpperCase().replace(/[^A-Z0-9]/g, '-')`; check for duplicates before saving |

## Related Skills

- @product-data-modeling
- @inventory-tracking
- @catalog-import-export