Variant Option Normalizer

Purpose

Scans product variants for inconsistent option values (e.g., "Sm", "Small", "small", "S" all meaning the same size) and bulk-updates them to a canonical set you define. Inconsistent option naming breaks size filters, causes customer confusion, and prevents search apps from grouping variants correctly.

Prerequisites

Parameters

Safety

> ⚠️ productVariantsBulkUpdate modifies variant option values. Option value changes affect how the variant appears to customers in the storefront and may break existing cart links or saved wishlists. Run with dry_run: true to review all affected variants before committing.

Workflow Steps

Inputs: query: (or all products if no filter), first: 250, select options, variants { selectedOptions }, pagination cursor

Expected output: Products with variant option values; paginate until hasNextPage: false

Inputs: productId, array of variants { id, options: [] } for affected variants

Expected output: productVariants { id, selectedOptions }, userErrors

GraphQL Operations

# products:query — validated against api_version 2025-01
query ProductVariantOptions($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        options {
          id
          name
          values
        }
        variants(first: 100) {
          edges {
            node {
              id
              title
              sku
              selectedOptions {
                name
                value
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# productVariantsBulkUpdate:mutation — validated against api_version 2025-01
mutation ProductVariantsBulkUpdate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    productVariants {
      id
      title
      selectedOptions {
        name
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Variant Option Normalizer            ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
OUTCOME SUMMARY
  Products scanned:       <n>
  Variants needing fix:   <n>
  Variants updated:       <n>
  Errors:                 <n>
  Output:                 option_normalizer_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "variant-option-normalizer",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": true,
  "option_name": "Size",
  "outcome": {
    "products_scanned": 0,
    "variants_needing_fix": 0,
    "variants_updated": 0,
    "errors": 0,
    "output_file": "option_normalizer_<date>.csv"
  }
}

Output Format

CSV file option_normalizer_.csv with columns:

product_id, product_title, variant_id, sku, option_name, old_value, new_value

Error Handling

Best Practices