Shopify variant CSV imports seem simple enough, until they don’t. Until the first file doesn’t import correctly. You didn’t know that variants required extra rows to differentiate variations under the same product handle? That the image column expects a URL instead of a path to the image? That blank cells have different meanings than empty strings? That one typo in the Option1 Name column can produce 400 duplicate products instead of 1? This guide is the one we wish we had read before jumping into a variants import.
You will get: exact column structure, Handle trick for multi-variant products, how images are handled, how metafields can be included and list of errors that appear on every first import. So next import won’t break.
In this post
- How Shopify’s product CSV is structured
- The Handle trick for multiple variants
- Step by step: your first import
- Images in a variant CSV
- Metafields in the same file
- Common errors and fixes
- After the import: variant images and grouping
- Frequently asked questions
- Related reading
How Shopify’s product CSV is structured
Shopify imports from a CSV that is flat but the variant in the CSV is hierarchical and can therefore have multiple rows of data per product. All the information that doesn’t change for a product (everything outside of variant information) is in the first row, and then following rows with the same Handle contain the same product information except for the variant details. Typically every row of data after the first will contain different variant information for the product. So the first row might have information like the Title, Description (Body HTML), Vendor, Tags, while each subsequent row would be the same except for the Weight and Price.
Key fields that you will need to be familiar with on every import: Handle, Title, Body (HTML), Vendor, Type, Tags, Published, Option1 Name, Option1 Value, Option2 Name, Option2 Value, Option3 Name, Option3 Value, Variant SKU, Variant Inventory Qty, Variant Price, Variant Compare At Price, Image Src, Image Position, Image Alt Text, Status. A clean starter file is just a click away with our product CSV generator tool.
The Handle trick for multiple variants
The most common rule that breaks first imports is that every row pertaining to the same product must have the same Handle. Handle is the URL slug and must be in all lowercase and no spaces, also no capitalization. So, on a Shopify import, a row with handle “classic-tee” is considered a different product than a row with handle “Classic-Tee”.
On variant rows Leave Title, Body HTML, Vendor, Tags and Status blank (except for the first row for a given product handle). You can load the rows, but Shopify will often import them if you fill in the fields again. However, this will cause confusion and make it very hard to rollback. You should only fill in the fields that are variant specific. These include the Option values, SKU, inventory, price, compare at, and weight.
Step by step: your first import
- Export a sample CSV from your store (Products, Export, All, CSV for Excel). This gives you the exact column headers Shopify expects.
- Delete all data rows but keep the header row.
- Add your first product in row 2 with all product-level columns filled. Put the first variant’s option values and SKU on the same row.
- For each additional variant, add a new row with the SAME Handle and only variant-specific columns filled.
- Validate the file with our CSV validator tool. It will catch handle mismatches, missing required fields, and bad option combos.
- Save as UTF-8 CSV. Do NOT save as xlsx. Excel sometimes adds a BOM, which is fine, but switching format corrupts characters.
- In Shopify admin, go to Products, click Import, upload the file.
- Tick “Overwrite any current products that have the same handle” only if you mean it.
- Review the import summary. Fix errors in the CSV, re-upload if needed.
Images in a variant CSV
Images in the product CSV are by URL, not file attachment. You put the image URL in the Image Src column, and Shopify downloads the image during import. One URL per row. If you have multiple images for a single product, add rows for each image with the same Handle, but fill in the Image Src column (and the Image Position column) and leave the rest of the columns for product variants empty.
To assign an image to a variant, set the Variant Image field to the URL for the product’s image that was imported. If you assigned a URL for the product image before the image for the individual variant, then Shopify will associate the correct image with the correct variant. If you imported the product image list after the individual product’s image then linking will fail but this will likely go unnoticed.
Most merchant’s currently use a CSV import function to load in variants – but this only allocates 1 image to a variant. This means you will then require an extra step to add the variant images for the different colours with front, back, details and lifestyle images – which is much easier with a class of variant image apps. The Rubik Variant Images app goes the extra mile with its AI auto-assign function which will automatically assign images to the correct variants after the import process based on product names, variant names, file names and alt text. Additionally the app’s bulk assign function works differently when processing large product catalogues – it will use the order of images within the gallery and assign a featured image boundary where appropriate.
Metafields in the same file
You can add metafields into the CSV by adding columns named like “Metafield: namespace.key [type]”. An example for this would be “Metafield: custom.material [single_line_text_field]”. Please make sure that the metafield definition exists in Settings, Custom data, Products before the import. If it doesn’t exist, Shopify will import it as a loose metafield.
Use this line for attributes with values like material, body fit, care instructions etc. as it will save you a lot of time when importing by not having to go back and do bulk editing of metafields.
Common errors and fixes
| Error | Cause | Fix |
|---|---|---|
| Duplicate products | Handle case mismatch | Lowercase everything, one handle per product |
| Missing required field | Empty Title on first row | First row of each handle must have Title |
| Variant images not linked | Variant Image URL not in product’s Image Src list | Add URL to an earlier row first |
| Price parsed as 0 | Comma as decimal in European format | Use period as decimal separator |
| Too many variants | Over 2048 variants per product | Split into multiple products or use Rubik Combined Listings |
| Inventory not updating | Inventory tracking disabled | Set Variant Inventory Tracker to shopify |
After the import: variant images and grouping
= Imported. Two things left to do. Gallery Filtering. I’d like to filter the images on the variant page. This is what Rubik Variant Images does. A really handy plugin that pairs really well with the previous plugin above as you can set it to auto-filter the images after upload per variant.
Second: for SEO, a lot of people have their colors come in as separate products – with their own URLs, with their own titles, with their own images – and then you’d want collection page swatches so people can see all those colors from the grid. That’s Rubik Combined Listings. It also does bulk grouping from your CSV, so you can do a second round of organization after you’ve imported all your products.
Video walkthrough
Try it on your store
See the post-import variant image flow on our demo at rubikdemo.com. Full Rubik Variant Images docs are at rubikvariant.com/docs. The video above explains all steps in an end-to-end walkthrough.
Frequently asked questions
How do I add multiple variants to one product in a CSV?
Keep all variants on the same row, place each on a separate row with the same Handle as the first row, and keep product-level fields (like Description, Meta Title and Description, etc) empty on the extra rows, filling only the variant-specific fields (Option values, SKU, price, inventory).
Can I import variant images via CSV?
Yes, but only 1 image per style, via the Variant Image column. Only matches images already in the product’s Image Src list. If you need to include multiple images per color, use a variant image app after you’ve imported the data.
What is the maximum number of variants a Shopify product can have?
2048 variants per product (up from 100 variants in 2024) with 3 option types per product such as size, color and material.
Why does my import create duplicate products?
If you have column mismatches, make sure your handles are case and whitespace sensitive. Keep them all lower case with hyphens and make sure that each row of the same product has identical handle values.
Can I update existing products by reimporting?
Yes. Make sure “Overwrite any current products that have the same handle” is checked. Back up the current products by exporting the CSV file first.
Does the CSV import support metafields?
Yes. Create a column Yes. Add a column named “Metafield: namespace.key [type]” and fill values per row. Then define the metafield in Settings, Custom data first for best results.
What image formats work?
JPEG, PNG, GIF, WebP formats supported. Shopify images can be imported from publicly accessible URLs. These images are downloaded during the import window and then Shopify stores them on our CDN.
