Fix Shopify Product CSV Import Errors
By Selling Fee Tools team ·
A Shopify product import fails, or imports the wrong thing, for a short list of reasons. This guide goes through them, following Shopify’s Help Center pages on product CSV files and the column set of a real Shopify export, and you can check a whole file at once with our validator.
Column names must match exactly
- Column names must match Shopify’s template exactly, including capitalisation. A header typed as handle instead of Handle makes the import fail.
- Collection is the only column you can add without breaking the format. A column like Color does.
- Title is the one column every import needs.
- Metafield columns, market price columns and Google Shopping columns from a Shopify export are recognised.
The file itself
- Save as UTF-8. A file saved in another encoding, as Excel often does, turns accented letters and curly quotes into stray symbols.
- Use commas between columns, not semicolons or tabs.
- Keep the file under 15 MB; split larger catalogues into several files.
Handles and product rows
- The Handle groups rows into one product: the first row holds the product details, and each further row with the same handle is a variant or an extra image.
- The first row of each handle needs the Title. Two different titles on the same handle usually means two products accidentally share one handle: give each its own.
- Handles should be URL-safe, lowercase with hyphens, without spaces.
Options and variants
- A product can have up to 3 options (Option1 to Option3).
- The option names on a variant row must match the product’s first row, and every variant needs a value for each option.
- Two variants with the same option values are a duplicate, and the import goes wrong.
Prices, stock and weights
- Prices must be plain numbers: 19.99, not $19.99 or 1,299.00. An empty price imports as 0.00.
- A Compare-at price must be higher than the price, or no sale is shown.
- Inventory quantities must be whole numbers, and Variant Grams a number of grams.
Images, tags and SEO
- Image Src must be a full public URL: Shopify downloads each image during import.
- Up to 250 images and 250 tags per product.
- SEO title up to 70 characters, SEO description up to 320, image alt text up to 512.
Things a file check can’t tell you
Whether image URLs actually load, whether a custom fulfillment service exists in your admin, and how products with matching handles overwrite existing ones can only be checked by Shopify. Import a few products first, then the rest.
Check your file
The Shopify CSV validator checks every rule above in your browser and lists each problem by row, column and severity with a suggested fix. Its “Download fixed CSV” makes the changes that have one correct answer: trimming spaces, cleaning prices, correcting header capitals, making handles URL-safe and saving as UTF-8.
Coming from WooCommerce? The WooCommerce to Shopify converter builds the file in Shopify’s format. See Move Products from WooCommerce to Shopify.