Variant grouping
Shopify treats CSV rows that share the same Handle as variants of a single product. This article explains how that works, the common mistakes, and how CSVwise detects and handles variant grouping.
How Shopify groups variants
In Shopify's product CSV format, a product with multiple variants is one row per variant. The variants are tied together by sharing a Handle value.
Example: one "Premium Coffee Mug" product with three size variants.
Handle,Title,Option1 Name,Option1 Value,Variant Price,Variant SKU
premium-coffee-mug,Premium Coffee Mug,Size,Small,12.99,MUG-S
premium-coffee-mug,,Size,Medium,14.99,MUG-M
premium-coffee-mug,,Size,Large,16.99,MUG-L
Notice:
- All three rows share
Handle: premium-coffee-mug. - Only the first row has the Title, Vendor, Product Type, etc. Those are product-level fields and only need to be set once.
- Each row has its own
Variant Price,Variant SKU, and option values.
When Shopify's importer sees these three rows, it creates one product with three variants. The first row's product-level fields become the product. The variant-level fields (everything starting with Variant ...) are unique per row.
How CSVwise detects variant grouping
CSVwise looks at the Handle column. If multiple rows share a Handle, it considers them a variant group and raises a warning:
"Duplicate Handles found in 12 row(s). Shopify treats rows sharing a Handle as variants. Confirm this is intentional."
You'll also see a note describing the groups CSVwise found:
"Detected 4 variant group(s) covering 12 rows. Shopify will combine rows sharing a Handle into a single product with multiple variants."
Warnings and notes never block your download, so if the duplicates are intentional there's nothing to do: read it and generate. If they're a typo (two genuinely different products that happen to have the same handle), pick one to rename in the source CSV and re-upload.
Common variant-grouping mistakes
1. Same product, different handles by mistake
You meant to group three sizes of the same mug as variants, but the rows have slightly different handles:
premium-coffee-mug-small
premium-coffee-mug-medium
premium-coffee-mug-large
Shopify will import these as three separate products, not one product with three variants. CSVwise can't catch this automatically. From its point of view, the handles really are different. You'd notice this after import as three duplicate-looking products in your store. Fix it by making all three handles the same (premium-coffee-mug) and putting the size into Option1 Value.
2. Different products, same handle by mistake
You have two unrelated products that both ended up with the handle tote-bag:
tote-bag,Canvas Tote Bag,...
tote-bag,Leather Tote Bag,...
Shopify will merge these into one product with two "variants", but the variants will share confusing product-level fields. CSVwise flags this with the duplicate-handles warning so you can catch it before import. Rename one of the handles in the source CSV.
3. Variant rows with product-level fields filled in
You filled out Title, Vendor, etc. on every variant row:
premium-coffee-mug,Premium Coffee Mug,Vendor,Mug Co,...,Size,Small,...
premium-coffee-mug,Premium Coffee Mug,Vendor,Mug Co,...,Size,Medium,...
premium-coffee-mug,Premium Coffee Mug,Vendor,Mug Co,...,Size,Large,...
Shopify's importer ignores product-level fields after the first row for a given handle. There's no actual harm. CSVwise lets this through without complaining. It's just redundant data in your CSV.
4. The "parent" row is missing
Shopify expects the first row for a handle to carry the product-level fields. If your variants come in some other order (for example, sorted alphabetically by SKU), the wrong row ends up "first" and the product-level fields get associated with an arbitrary variant.
CSVwise doesn't catch this. It treats any row of a variant group as a legitimate continuation row, so a missing Title on a later row is expected rather than flagged. Check the ordering yourself and re-sort the source CSV so the row carrying the full product fields comes before its variants.
Variant option columns
Shopify supports up to three variant options per product (Option1 Name / Option1 Value through Option3 ...). CSVwise doesn't auto-fix option columns (they're already in the format Shopify expects), but it does flag rows where:
- A variant has values for option columns the product doesn't define a name for.
- Two variants of the same product share the same combination of option values (Shopify rejects this).