Shopify CSV Import: Columns, Variants, Images and Error Fixes

A product CSV is the fastest way to add or update hundreds of Shopify products at once, and also the easiest way to damage a catalog if one column is wrong. The format is strict: headers must match exactly, each product is tied together by its handle, and variants and extra images sit on their own rows under the first one.

This guide explains the columns that matter, shows how a product with variants and several images is laid out, walks through the import screen and the overwrite option, and lists the errors that most often stop an import, with the fix for each.

Get the current template first

Shopify updates its product CSV format from time to time. Its help center now documents the columns with plain-language names such as URL handle, Price and Product image URL. Older exports, older tutorials and many third-party tools still use the earlier names, such as Handle, Variant Price and Image Src.

Before you build a file, download the sample CSV linked from the import dialog (Products > Import) or export one existing product from your own store. Either gives you headers in the format your store currently expects. Shopify's help center notes that column headers are case-sensitive, so copy them rather than typing them.

Key columns in the Shopify product CSV

The template has dozens of columns, including Google Shopping fields, market-specific prices and metafields. You rarely need all of them. These are the ones that control what gets created and how.

Only a few columns are strictly required. For a new product you need Title. To add variants or images to it, every row needs the same URL handle. To update an existing product, include the handle and title. Anything you leave out of the file is left alone on existing products, which matters for the overwrite option described below.

How variants and images are laid out in rows

The CSV is flat, so a product with several variants and images spreads across several rows. The rule is simple: the first row carries the full product, and each following row with the same handle carries one more variant, one more image, or both.

Take a T-shirt in three sizes with four images. It needs four rows, because there are more images than variants:

Notice what repeats and what does not:

• The handle repeats on every row. It is what ties the rows together.
• Title, description, vendor, type and tags appear only on the first row. Leave them blank below.
• The option name appears on the first row. Variant rows carry only the option value and variant-level fields (SKU, price, barcode, weight, inventory).
• The fourth row is image-only: handle, image URL and position, nothing else.

A product without variants still needs an option. Shopify's documentation says that if a product has only one option, the value should be Default Title. Exports from Shopify write Title as the option name and Default Title as the value for single-variant products, so keep that pattern.

For products with two or three options (Size and Color, for example), fill Option1 name, Option2 name and so on in the first row, then give every variant row a value for each option. Every combination must be unique; two rows with Size Medium and Color Black will be rejected as duplicates. Shopify raised the limit to 2,048 variants per product in late 2025, with up to three options.

How to import the file, step by step

1. Save the CSV as UTF-8. In Google Sheets, File > Download > Comma-separated values produces UTF-8 by default. In Excel, choose "CSV UTF-8" in the save dialog.
2. Check the file size. Shopify's limit is 15 MB. Split larger catalogs into several files, keeping all rows of each product in the same file.
3. In the Shopify admin, go to Products and click Import.
4. Click Add file and select your CSV.
5. Decide on Publish new products to all sales channels. Deselect it if you want new products on the online store only.
6. Decide on Overwrite products with matching handles (explained below).
7. Click Upload and continue, read the preview summary, and click Import products.

Large imports run in the background, and Shopify emails you when the import finishes. Spot-check several products afterward, including one with many variants, before you announce anything or turn on ads. A quick check list for each sample product:

• The variant count matches your file, and each variant shows the right price and SKU.
• Images appear in the order you set, and variant images switch when you pick a different option on the storefront.
• The status is what you intended. New products set to draft will not show on the storefront until you activate them.
• The product appears in the collections you expect. Automated collections pick products up from tags, type or vendor, so a typo in those columns keeps a product out.
• Inventory and the out-of-stock policy are correct, so you are not selling items you do not have.

If something is wrong across many products, fix the file and re-import with overwrite rather than correcting products one by one in the admin.

The overwrite option: what it does and does not do

When Overwrite products with matching handles is selected and a handle in your file matches an existing product, the values in your file replace the values in the matching columns. Three rules follow from that:

• Blank cells overwrite. If your file has a Tags column and a product's cell is empty, that product's tags are cleared.
• Missing columns are kept. If the file has no Tags column at all, existing tags stay as they are.
• Dependent columns need their partners. Shopify warns that some columns depend on others. For example, variant fields such as SKU need the option columns alongside them, or existing variant data can be removed.

If the overwrite box is not selected, rows whose handle already exists are treated differently: Shopify will not replace the existing product's data with your file. To update prices or descriptions on existing products, you need overwrite on.

The safest pattern for an update is a small file: the handle, the title, the option columns, and only the columns you are changing. Fewer columns means fewer chances to wipe something by accident. For price-only changes, the guide on bulk editing Shopify products covers methods that do not involve a full CSV at all.

Common import errors and how to fix them

Strange characters in titles or descriptions

Accented letters, curly quotes or symbols show up as garbage when the file is not UTF-8. Re-save as UTF-8 and import again. Excel's plain "CSV" option on some systems is not UTF-8.

"Unexpected token < in JSON at position 0"

Shopify's help center links this to header problems. Headers are case-sensitive and must match the template exactly. Compare your header row against a fresh export, including spaces and capitalization.

"Line is invalid" or duplicate variant errors

This usually means two variant rows share the same option values, a variant row has an option value but the first row has no option name, or you are moving option values between positions (Option1 to Option2) on an existing product. For the last case, Shopify suggests renaming the values temporarily in one import and setting the final names in a second.

Images missing after import

Shopify downloads each image from its URL during import. The URL must be public and point straight at the file, not at a page, a login-protected folder or a sharing link that opens a viewer. Test each URL in a private browser window. Very large images can also time out.

Variants or images attached to the wrong product

Sorting the spreadsheet by any column other than handle breaks the row order. Shopify warns that sorting can disassociate variants and image URLs from their product. If you must sort, sort by handle and then restore the original order before saving.

Barcodes and SKUs changed

Spreadsheets strip leading zeros from barcodes (012345678905 becomes 12345678905) and turn long numbers into scientific notation. Format those columns as text before you paste data in. If you need valid barcodes, the GTIN lookup tool checks existing codes, and the barcode generator creates printable labels for internal SKUs.

Inventory not updating

The inventory quantity column works only for stores with a single location. With multiple locations, use the separate inventory CSV under Products > Inventory, which has a column per location.

Prices or weights wrong

Remove currency symbols and thousands separators from price cells. Use a period as the decimal separator. Weight in grams must be a whole number.

Test small before a large import

A failed import of 3,000 products takes hours to clean up. A failed import of five takes a minute. Before any large file, run a short test:

• Cut a sample file. Copy the header row and the rows for five products into a new file: one simple product, one with a single option, one with two or three options, one with many images, and one with a long HTML description.
• Import the sample as draft. Set the Status column to draft so nothing appears on the storefront while you check.
• Compare against the source. Open each test product and check variants, prices, images, alt text and SEO fields against your spreadsheet.
• Fix the file, not the products. If something is wrong, correct the pattern in the full file so the same mistake does not repeat thousands of times.
• Import the rest in batches. Split by collection or vendor so each batch is easy to verify, and keep a note of which files have been imported.

Delete the test products afterward, or import the full file with overwrite on so the test products are updated rather than duplicated. Products are matched by handle, so the same handle always points to the same product.

When a CSV is the wrong tool

CSV imports are good for moving a catalog from a spreadsheet, a supplier feed or another platform. They are clumsy for pulling products from another live store, because you have to scrape or retype everything into the template first. In that case a product importer that reads the source store directly saves the reformatting. AM Jarvis's Product Importer copies products from public Shopify and WooCommerce stores with their variants, images and prices, and lets you edit before import. The broader guide on how to import products to Shopify compares CSV, apps and manual entry.

Whichever route you use, finish each imported product with a proper SEO title and meta description. Blank SEO columns in a CSV mean Shopify falls back to the product title and the start of the description, which rarely makes a good search snippet.