Shopify CSV Import Guide
The complete reference — for merchants who can’t afford a broken catalog.
A Shopify CSV import can update 5,000 products in 30 seconds. It can also silently erase prices, drop variants, and replace descriptions — all while reporting success. The difference between those two outcomes comes down to preparation.
This guide is the reference we wish existed when we started. It covers how Shopify reads CSVs, what breaks imports, and how to verify your file before you upload it. Every section links to a deeper guide if you need to go further.
If you’re new to Shopify CSVs, read top to bottom. If you have a specific problem, jump to the relevant section — every section has a link to its deep-dive guide.
What is a Shopify CSV?
A Shopify CSV is a plain text file with comma-separated values. Each line represents a row. Each row has the same set of fields, in the same order, defined by the header line at the top.
Shopify uses this format for two things: exporting products out of your store and importing products into your store. The same file format serves both directions, which is why imports can be used to update existing products, not just create new ones.
The typical file has 20-50 columns and anywhere from 1 to 100,000 rows. Each product occupies one or more rows — the first row is the parent, and each subsequent row is a variant or an additional image.
The three core concepts you must understand
1. Handle is the primary key
Handle is the only column Shopify uses to match rows to products. Not SKU. Not barcode. Not title. Handle.
If your CSV contains handle: blue-t-shirt and your store
already has a product with that handle, Shopify updates it. If not, Shopify
creates a new product.
→ Read the full handle errors guide
2. Blank cells erase data — they don’t skip it
If a column is included in your CSV, Shopify treats every blank cell in that column as an intentional instruction to clear the field on matching products.
This is the single most dangerous behavior in the format, and it catches merchants off guard because it’s the opposite of how Excel works.
→ Read the full blank overwrites guide
3. Variants are identified by option combinations
Every variant of a product shares the same Handle. What makes each variant unique is the combination of Option1 Value + Option2 Value + Option3 Value. “Small/Red” and “Small/Blue” are two variants. “Small/Red” and “Small/Red” is a duplicate — Shopify silently drops one.
The structure of a Shopify product CSV
Columns
Shopify’s CSV format includes over 50 columns. Most are optional; a few are required. The full list breaks into six groups:
- Product identity: Handle, Title, Body (HTML), Vendor, Type, Tags, Published, Status, Product Category, SEO Title, SEO Description
- Variant options: Option1 Name, Option1 Value, Option2 Name, Option2 Value, Option3 Name, Option3 Value
- Variant pricing: Variant SKU, Variant Price, Variant Compare At Price, Variant Barcode, Cost per item
- Inventory: Variant Inventory Tracker, Variant Inventory Qty, Variant Inventory Policy, Variant Fulfillment Service, Variant Weight Unit, Variant Grams
- Shipping and tax: Variant Requires Shipping, Variant Taxable, Variant Tax Code, Gift Card
- Images: Image Src, Image Position, Image Alt Text, Variant Image
→ Download our free CSV template with all columns
Rows
A product with no variants and no extra images occupies one row. A product with three variants and two images occupies five rows (one parent, three variants, two images).
The first row is the parent — it contains the Title, Body HTML, Vendor, Type, Tags, Published, Status, and any other product-level fields. Every subsequent row of the same product leaves those blank.
The correct import workflow
The reason most imports go wrong is not bad data. It’s bad order of operations. Here’s the sequence that minimizes risk.
Step 1 — Export a backup of your current products
Go to Shopify Admin → Products → Export → All products → Plain CSV file. Save this file. It’s your rollback point.
If anything goes wrong with the import, you can re-import this file to restore your catalog to its current state. It takes 30 seconds and it’s the single most important safety practice for bulk imports.
Step 2 — Prepare your update file
If you’re creating new products: build the file from a template. If you’re updating existing products: start from a fresh export and edit only the columns you’re actually changing.
Either way: match Shopify’s column names exactly. Don’t rename, don’t add extra columns, don’t reorder unless you have a reason.
Step 3 — Validate the file
Run the file through a validator before you upload it. This is what catches the missing handles, blank cells, duplicate combinations, and encoding issues before they hit your store.
→ See the full before-import checklist
Step 4 — Test-import a small batch
Create a smaller version of your CSV with 2-5 products. Import it first. Verify the results on the storefront. If the test batch works, run the full import.
Step 5 — Import the full file
Shopify Admin → Products → Import → choose your file. Shopify shows a preview; review it before confirming. The import itself takes seconds for small files and minutes for large ones.
Step 6 — Verify a sample of the results
Pick 5-10 products that were affected by the import. Check prices, variants, images, and descriptions. Look for anything unexpected. If something is wrong, re-import your backup.
The six categories of import errors
Everything that breaks a Shopify CSV import falls into one of these six categories. Each has a dedicated guide.
1. Handle errors
Missing, duplicate, or malformed handles. The most common cause of failed updates and silent duplicates.
2. Blank overwrites
Empty cells in included columns. Shopify treats these as intentional clears. This is the error that quietly wipes prices and inventory.
3. Variant errors
Orphaned rows, duplicate option combinations, incomplete pairs. Silent product collapses that you only notice weeks later.
4. Encoding errors
UTF-8 BOM, smart quotes, wrong delimiters, non-UTF-8 character sets. Invisible problems that break imports before they start.
5. Template and structure errors
Missing required columns, renamed headers, extra columns Shopify ignores, wrong file format.
6. Pre-import verification gaps
No backup, no test batch, no validation. The workflow mistakes that turn a small problem into a catalog-wide failure.
The tool that catches all of this
Manually checking 20 columns across 2,000 rows is not realistic. The eye misses things. Excel filters only catch one column at a time. And the errors that break imports — missing handles, blank cells, duplicate combinations — require looking at relationships between rows, not just cells.
Autonom Shopify Guard is a free browser-based validator that scans your CSV for every error category in this guide. It shows you exactly which rows and columns are affected, sorts issues by severity, and lets you fix the safe ones automatically.
It runs entirely in your browser — nothing is uploaded, no account is required. You can verify this by watching the Network tab in your browser’s DevTools during a scan.
Validate your CSV before you import
Free, browser-based, no account. Checks 30+ issues including every category in this guide.
Open Shopify CSV Validator →Deeper guides
Every section above has a longer companion guide. Start here for the overview; dig into the specific ones when you hit a problem.
Frequently asked questions
What file format does Shopify accept for product imports?
Shopify only accepts CSV files — specifically UTF-8 encoded, comma-delimited files with the .csv extension. Files saved as .xlsx, .xls, .numbers, or with semicolon delimiters will be rejected.
How many products can I import at once?
Shopify doesn’t limit the number of products, but it does limit file size to 15 MB. If your file exceeds that, split it into multiple files. Each file imports independently.
Will importing a CSV delete my existing products?
No. A CSV import never deletes products. It creates new ones or updates existing ones. However, if you include a column in your update CSV and leave cells blank, Shopify will clear those fields on matching products — which can feel like deletion.
How do I know if an import succeeded?
Shopify shows an import summary at the end of the process. It lists how many products were created, updated, or skipped. But “success” doesn’t mean the data is correct — always verify a sample of the results on the storefront.
Can I import products that don’t have handles yet?
Yes, but not recommended. Shopify will auto-generate a handle from the title. The generated handles are sometimes unpredictable, especially for titles with special characters. Always define handles explicitly.
What happens if my CSV has extra columns Shopify doesn’t recognize?
Shopify ignores unknown columns silently. Your import still succeeds, but the data in those columns is not stored anywhere. If you need to store extra data, use tags or metafields.
Do I need to include every column in my CSV?
No. Include only the columns you’re actively importing. This is safer than including columns you don’t need, because any column you include triggers the blank overwrite behavior for its blank cells.
How do I backup my Shopify products before importing?
Shopify Admin → Products → Export → All products → Plain CSV file. Save the resulting file. If your import goes wrong, re-import this file to restore your products to their previous state.
What’s the difference between creating and updating products via CSV?
The format is identical. The difference is whether the Handle matches an existing product. If it does, Shopify updates. If it doesn’t, Shopify creates. You don’t tell Shopify which mode to use — it decides based on the handles in your file.
Can I roll back an import if something goes wrong?
Only if you exported a backup before importing. Shopify doesn’t offer built-in version history for products. Re-importing the backup file restores the previous state for the fields it contains.