How variants work in a Shopify product CSV
In a Shopify CSV, a product with variants is several rows that share one URL handle. The first row describes the product; every row describes one sellable combination of up to three options.
The three rules
- Rows with the same URL handle belong to the same product. The handle is the glue; the title is not.
- The first row carries the product. Title, description, vendor, type, tags and the option names (
Option1 name,Option2 name,Option3 name) go on the first row only. - Each row carries one variant. Option values, SKU, barcode, price, compare-at price, weight and inventory belong to the variant and are filled in on every row.
Shopify allows up to three options per product (for example Color, Size and Material) and up to 2,048 variants.
A complete example
Title,URL handle,Vendor,Option1 name,Option1 value,Option2 name,Option2 value,SKU,Price,Status
Waffle Towel,waffle-towel,Anatolia Home,Color,Sand,Size,50 × 90,TWL-001-SA,18.00,draft
,waffle-towel,,,Sand,,70 × 140,TWL-002-SA,26.00,draft
,waffle-towel,,,Olive,,50 × 90,TWL-001-OL,18.00,draft
,waffle-towel,,,Olive,,70 × 140,TWL-002-OL,26.00,draftFour rows, one product, four variants. Shopify builds the option lists from the values it finds: Color (Sand, Olive) and Size (50 × 90, 70 × 140).
Products without options: Default Title
Every Shopify product has at least one variant. When a product has no options, Shopify writes Option1 name = Title and Option1 value = Default Title. You can write those values yourself or leave the option columns empty for a single-row product. What you can’t do is add a second row with the same handle and no option values: that produces “The variant ‘Default Title’ already exists”.
Extra images and variant images
A product can have more images than it has variants. Add them on extra rows that contain only the URL handle, Product image URL and Image position. Keep the variant columns empty on those rows so they aren’t read as another variant.
To show a specific photo when a customer picks a variant, put its URL in Variant image URL on that variant’s row.
Title,URL handle,Option1 name,Option1 value,Price,Product image URL,Image position,Variant image URL
Organic Tee,organic-tee,Color,Red,22.00,https://example.com/tee-red.jpg,1,https://example.com/tee-red.jpg
,organic-tee,,Blue,22.00,https://example.com/tee-blue.jpg,2,https://example.com/tee-blue.jpg
,organic-tee,,,,https://example.com/tee-detail.jpg,3,The example.com links only illustrate the layout; use your own public image URLs.
What goes wrong with variants
| Symptom | Cause | Fix |
|---|---|---|
| “Validation failed: options are not unique” | Two rows with the same handle and identical option values. | Delete the duplicate or add the option that differs. |
| “The variant ‘Default Title’ already exists” | A second row for a product without options. | Add option names and values, or use separate handles. |
| “Ignored line… did not contain product data” | The first row for a handle has no title. | Move the title row to the top of the product. |
| “Ignored line… handle already exists” | Two products share a handle. | Give each product its own handle. |
| Variants imported as separate products | Each row has a different handle. | Use one handle for all variants of a product. |
| Options in the wrong order | Option names differ between products or aren’t on the first row. | Put option names on the first row only, in a consistent order. |
Building variants from a supplier list
Supplier price lists usually list one variant per row with a model or parent code, a color and a size, which maps neatly onto Shopify’s format once the rows are grouped. Sheet2Store groups rows by a model or parent column (or by exact title when there is none), fills in the option names on the first row, and flags missing option values and duplicate combinations before you export. See also how to add supplier products to Shopify.
Frequently asked questions
Can different variants have different prices?
Yes. Price is stored per variant, so each row can have its own price, compare-at price and cost.
Do option values need to be in a particular order?
Shopify builds each option’s value list in the order it first meets the values in the file, so put your rows in the order you want customers to see.
Can I add a new variant to an existing product by CSV?
Yes, by importing the product with the same handle and Overwrite products with matching handles checked. Include all its variants, because the file replaces the product’s data.
What is the maximum number of variants?
2,048 variants and three options per product.
Turn a supplier file into an import-ready CSV
Upload a supplier PDF, Excel or CSV price list. Map the columns, set your markup, fix flagged rows and download a Shopify or WooCommerce CSV. The first five rows are free to preview.