When you first start importing 500 products into Shopify, it will break. Usually in a pretty stupid way (like a comma in a product title, or an image URL that 404s). This guide explores the 3 different ways to do Shopify imports, the relevant columns in the csv file, and the most time-wasting errors.
Short version: if you have under 200 products, the native CSV parser is fine. If you have thousands of products, just pay for use of Matrixify to avoid the pain of the native parser. If you are migrating from WooCommerce or BigCommerce, just use an appropriate migration app and clean up afterward. The whole decision tree for this module can be succinctly stated above, but there are many details that will be discussed in the following posts.
On this page
- Three import methods compared
- Native CSV import, step by step
- CSV column reference
- Common errors and fixes
- After the import
- FAQ
Three import methods compared
| Method | Good for | Cost | Pain |
|---|---|---|---|
| Native CSV | Under ~500 products, simple catalogs | Free | Unhelpful errors, slow UI |
| Matrixify | Large catalogs, complex variants, scheduled imports | Paid, free tier exists | Learning curve on column names |
| Migration apps | Moving from Woo, BigCommerce, Magento, Wix | Paid per product | Mappings lie, always verify |
| Shopify API scripts | Recurring syncs, custom ERP pipes | Developer time | You own the bugs |
Native CSV import, step by step
- In Shopify admin, go to Products, then click Import.
- Click “Download sample CSV template”. Always start from this file. Do not write one from scratch.
- Fill in your data in a spreadsheet. Save as UTF-8 CSV. Not UTF-8 BOM. Not Mac OS Roman. UTF-8.
- Upload the file. Shopify shows a preview. If there are errors, fix the sheet and re-upload.
- Hit “Upload and continue”. Large files take a while. Do not close the tab; you will get an email when it finishes.
My rule of thumb for testing is to import the code first with 5 rows of data, NOT 5000. If it works with 5 rows, it should work with 5000. And if it doesn’t work with 5 rows, you’ll waste an hour of your time that you can’t get back.
CSV column reference (the ones that actually matter)
| Column | What it does | Gotcha |
|---|---|---|
| Handle | The URL slug. Groups variant rows together. | All variants of one product share the same handle. |
| Title | Product title. Only fill on the first row per handle. | Leave blank on variant rows. |
| Body (HTML) | Product description. HTML allowed. | Commas inside quotes, always. |
| Option1 Name / Value | First variant option (e.g. Color / Red). | Max 3 option types per product. |
| Variant SKU | Stock keeping unit. | Must be unique across the store. |
| Variant Inventory Qty | Stock count. | Only applies to your default location. |
| Variant Price | Selling price. | Use a dot as decimal, not a comma. |
| Image Src | Public URL of the image. | Must be publicly accessible. Google Drive share links do not work. |
| Image Position | Order of images. | Matters for gallery order and variant image assignment. |
| Variant Image | URL of the variant-specific image. | Must already be in Image Src somewhere on the product. |
| Status | active, draft, or archived. | New imports default to active. Surprise. |
Shopify supports up to 2048 variants for a product via combined listings, but only 3 option types. If your spreadsheet has 4 option types, you will either need to merge 2 of the options together, or use Combined Listings for the product instead of variants.
Common errors and how to fix them
- “Image could not be downloaded”. The URL is not public, is behind auth, or is a redirect. Host images somewhere like S3, Cloudinary, or your CDN. Not Dropbox. Not Google Drive.
- “Variant with same options already exists”. Two rows have the same Option1/Option2/Option3 combination under the same handle. Fix or dedupe.
- “SKU already in use”. SKUs are store-unique. You cannot use the same SKU on two products.
- Silent failure, products appear with no images. Image URLs contain spaces or special characters. URL-encode them.
- Variant rows created as separate products. Handle column is missing or inconsistent on some rows. Lowercase the handle, no spaces.
After the import: the part nobody talks about
This is the hardest part of importing products. Eventually you will complete the import and have to correct a bunch of errors on your product page. It wont be broken, it just wont look correct. Variants will be there, but clicking on a color will take you to a different product, all colors will display all images, swatches will look and act nothing like swatches. They might look like a dropdown nobody wants them.
This is the default behavior for Shopify, where each variant has 1 image, which is treated as the featured image for that variant. There are steps to change this to have multiple images per variant, or to have the gallery change when a swatch is clicked. Rubik Variant Images handles these cases with a “bulk assign” mode that can read the order of images in a gallery from a CSV and automatically group images by variant. No need to open up a second CSV to assign these images.
If you imported different colors as separate products (one handle per color), then that is a totally different job. We call this product Rubik Combined Listings, which can bulk combine products by title pattern, tag, or metafield, and does not require Shopify Plus.
Make sure you test the data on http://csvvalidator.io/ and also use http://www.craftshift.com/sku-generator/ to generate clean SKUs before importing. Both of these are free tools, that don’t require us to sign up. Also, in case you have a folder full of 800 images and each image has been downloaded and named as IMG_0001.jpg, you can use http://www.craftshift.com/bulk-image-renamer/.
Demo, tutorials, docs
live demo at rubikdemo.com. Video tutorials on import and assigning. Full documentation at rubikvariant.com and rubikswatch.com. Both apps have free plans.
“Hands Down the best customer support of all the variation/swatch apps I have used till date. The app does everything. From individual variant gallery to really detailed customizable swatch’s. AI has been integrated, HELPS ALOT WITH SORTING IMAGES.”
Bellissima Covers, Rubik Variant Images reviews
FAQ
What is the max number of products I can import at once?
Native CSV files do not have a hard product limit, but you may find files to reach timeout around ~15MB or ~50k rows. See: Matrixify for larger files.
Can I import products with variant images from CSV?
Yes, via Variant Image column. Image URL must already exist in the product’s Image Src column for another row of the same handle.
What format should image URLs be?
Direct supports direct, public, HTTPS URLs. Not Google Drive or Dropbox share links, or authenticated URLs.
How many variants can a product have?
This configuration allows up to 2048 options by combining listings, with three option types per product allowed at most.
Will the import overwrite existing products?
Only if you check “Overwrite existing products that have the same handle.” Read the confirmation dialog for this feature. Note: this is the default.
Can I import metafields via CSV?
Native CSV has limited metafield support. Matrixify handles it cleanly.
What happens if an image URL is broken?
Product imports without the image and a warning appears in the import row. Fix URL and re-import the single row.
