variant-matrix

What this skill does

# 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