How to correct variant rows in a Shopify product CSV

Variants cause more broken Shopify imports than anything else. A product with sizes and colours is spread across several rows, and each row has a different job. Once you know the layout, most variant errors are easy to spot.

The layout Shopify expects

Here is a T-shirt in two colours and two sizes:

Title	URL handle	Option1 name	Option1 value	Option2 name	Option2 value	SKU	Price
Organic Tee	organic-tee	Color	White	Size	S	TEE-WHT-S	29.95
	organic-tee		White		M	TEE-WHT-M	29.95
	organic-tee		Black		S	TEE-BLK-S	29.95
	organic-tee		Black		M	TEE-BLK-M	29.95

The rules, from Shopify's CSV documentation:

• The first row holds the product details: title, description, vendor, tags and option names. It is also the first variant.
• Later rows carry the same URL handle and that variant's details. Title, description, vendor and tags are left blank.
• Every variant row has a value for each option the product uses.
• A product can have up to three options.
• Columns with variant data, such as SKU or weight, need Option1 name and Option1 value. If you leave them out, Shopify creates a default variant and deletes the product's existing variants.

The common errors and how to fix them

Two rows with the same option values

If two rows of a product both say "Black / S", Shopify can't tell them apart. This often happens when an ERP export repeats a row, or a colour column was left blank.

Fix: change the option values so that every combination is unique, or delete the repeated row. The Duplicate SKU Checker lists duplicate variants with both row numbers.

Variant rows with no option value

A row that has a SKU and a price but a blank size can't become a variant of a product that uses Size.

Fix: fill in the missing option value. CatalogPilot reports these rows and doesn't guess the value.

Option values but no option name

If Option1 value has values but the product's first row has no Option1 name, Shopify doesn't know what the option is called.

Fix: add the name, such as Size or Color, on the first row of the product.

Several variant rows but no option columns at all

Supplier files often have one row per variant, with the same product name on each row and no Size or Color column marked as an option. Shopify then sees several variants it can't tell apart.

Fix: if your file has columns like Colour or Size, treat them as options. In the column mapper, set them to "Variant option". If the rows are really different products, give them different titles or handles.

Product details that differ between rows

If later rows of a product have a different vendor or description, Shopify ignores them and uses the first row. That's harmless, but it's often a sign that two different products were given the same handle by mistake.

More than three options

Shopify allows at most three options per product, for example Color, Size and Material. A supplier file with four attributes needs one of them moved into the product title, tags or a metafield.

Rows of one product scattered through the file

Shopify expects all rows of a product to sit together. If an edited file has rows for the same handle in different places, sort the file by handle. The CatalogPilot repair tool moves them back together automatically.

Changing option values on existing products

Shopify's documentation warns that changing option values on products that already exist deletes the existing variant IDs and creates new ones. That can break apps or integrations that store variant IDs. Change option values in a CSV only when you mean to.

Check your file

Drop your CSV into the CSV Error Checker for Shopify to see every variant problem with the row it's on. The repair tool fixes the problems that can be fixed reliably, such as grouping, handles, option columns and scattered rows. It leaves anything that would need guessing for you to decide.