Key takeaways
Handleis the grouping key. Rows sharing a Handle become one product with multiple variants.- Only the first row of a Handle group carries product-level fields. Repeating them on later rows causes odd results.
- Blank is not the same as absent. Shopify applies defaults, and a blank price imports as 0.00.
- Three options and 100 variants per product, hard limits, no exceptions.
Shopify's product CSV is unusual: it is not one row per product, and it is not one row per variant either. It is one row per thing to say about a product, grouped by a slug in the first column.
Once that clicks, the rest of the format is straightforward. Until it does, the import produces mystifying results.
The Handle rule, which explains everything else
Handle is the URL slug and the grouping key at the same time. Every consecutive row with the same Handle belongs to the same product.
Within a group:
- The first row carries product-level fields: Title, Body, Vendor, Type, Tags, Published, plus its own variant and first image.
- Subsequent rows carry additional variants, additional images, or both, and leave the product-level fields blank.
A t-shirt in three sizes with four photos looks like this:
Handle,Title,Option1 Name,Option1 Value,Variant SKU,Variant Price,Image Src,Image Position
cotton-tee,Cotton Tee,Size,Small,TEE-S,24.99,https://cdn.example/1.jpg,1
cotton-tee,,Size,Medium,TEE-M,24.99,https://cdn.example/2.jpg,2
cotton-tee,,Size,Large,TEE-L,24.99,https://cdn.example/3.jpg,3
cotton-tee,,,,,,https://cdn.example/4.jpg,4Three variants, four images, one product. The last row is images only, so it leaves every variant column empty.
Repeating the Title on variant rows is the classic mistake. It usually still imports, but combined with any inconsistency elsewhere it is what turns one product with three variants into three products with one variant each.
Product-level columns
| Column | What it does | If blank |
|---|---|---|
Handle | URL slug and grouping key. Lowercase, hyphens, no spaces. | Row is skipped |
Title | Product name shown to customers. | Treated as a continuation row |
Body (HTML) | Description. Accepts HTML. Wrap in quotes if it contains commas. | Empty description |
Vendor | Brand. Used by automated collections and filters. | Store name |
Product Category | Shopify's standard taxonomy. Feeds Google Shopping. | Uncategorised |
Type | Your own free-text product type. | Empty |
Tags | Comma separated inside one quoted cell. Drives automated collections. | No tags |
Published | TRUE or FALSE. Visible on the online store channel. | TRUE |
Status | active, draft or archived. | active |
Gift Card | TRUE only for gift card products. | FALSE |
Import as draft first. Set Status to draft and Published to FALSE on your first run. You get to inspect everything in the admin before customers can see it, and flipping the whole set to active afterwards is one bulk action.
Option columns
Options are the choices a customer makes. You get three, named in pairs.
| Column | Notes |
|---|---|
Option1 Name | The attribute label, for example Size. Must repeat identically on every variant row in the group. |
Option1 Value | This variant's value, for example Medium. |
Option2 Name / Value | Second option, for example Colour. |
Option3 Name / Value | Third and final option. |
For a product with no choices at all, leave all six blank. Shopify creates a single default variant automatically. Do not invent an option called "Default Title" yourself.
The hard limits: 3 option names and 100 total variant combinations per product. These are platform constraints, not import constraints, and no CSV trick works around them. If you are coming from WooCommerce, this is the migration issue most likely to cost you a day, and it is covered in detail in the WooCommerce to Shopify migration guide.
Variant columns
| Column | What it does | If blank |
|---|---|---|
Variant SKU | Your stock code. Also the matching key for future updates. | Empty, and updates become unreliable |
Variant Price | Selling price. Numbers only, no currency symbol. | 0.00 |
Variant Compare At Price | The struck-through "was" price. Must exceed Variant Price to display. | No sale badge |
Variant Grams | Weight in grams, always, regardless of your display unit. | 0 |
Variant Inventory Tracker | shopify to track stock, blank to sell without tracking. | Untracked, always in stock |
Variant Inventory Qty | Units on hand at the default location. | 0 |
Variant Inventory Policy | deny or continue selling when out of stock. | deny |
Variant Fulfillment Service | manual unless using a third-party fulfilment app. | manual |
Variant Requires Shipping | FALSE for digital products. | TRUE |
Variant Taxable | Whether tax applies. | TRUE |
Variant Barcode | ISBN, UPC or GTIN. Needed for Google Shopping. | Empty |
Two defaults that bite. A blank Variant Price becomes 0.00 and the product goes live as free. A blank Variant Inventory Tracker means Shopify never decrements stock and you oversell. Neither produces an import error.
Image columns
| Column | Notes |
|---|---|
Image Src | Absolute, publicly reachable URL. Shopify fetches it at import and copies it to its own CDN. |
Image Position | 1 is the featured image. Increment for the rest. |
Image Alt Text | Accessibility and image SEO. Genuinely worth filling in. |
Variant Image | The image shown when this specific variant is selected. Must be one of the URLs already in the group. |
The URLs must be reachable by Shopify's servers at the moment of import: public, no authentication, no hotlink protection, no referer check. If your source CDN blocks unknown referers, every image is skipped without an error message.
Get a valid Shopify CSV in one step
Scrapify reads any WooCommerce or Shopify store and writes the Shopify format directly, with Handle grouping, variant rows and absolute image URLs already correct.
SEO and remaining columns
SEO TitleandSEO Description: meta tags. Left blank, Shopify falls back to the product title and the first part of the description, which is worse but not broken.Google Shopping / *: legacy columns Shopify largely superseded withProduct Category. Modern setups can ignore them.Cost per item: your buy price. Never shown to customers, powers margin reporting.Included / [Country],Price / [Country]: only appear if you have Shopify Markets configured.
File-level rules that cause silent failures
- UTF-8 encoding. Save as CSV UTF-8. Excel's plain "CSV" option produces Windows-1252 and turns accented characters into question marks.
- Comma delimited. Not semicolons. European Excel locales default to semicolons and Shopify will not recognise the file.
- Quote any cell containing a comma. Especially Tags and Body (HTML).
- Escape quotes by doubling them. A 15" laptop is written
15"" laptopinside a quoted cell. - 15MB maximum. Split larger files, keeping every row of a Handle group together in the same file.
- Keep Handle groups contiguous. Sort by Handle. Splitting a group across the file confuses the grouping.
Using the CSV to update existing products
Re-importing with a Handle that already exists updates that product, provided you tick "Overwrite any current products that have the same handle". Without that box, Shopify skips the row entirely.
The gotcha is that overwrite is per row, not per field: any column you omit from the file is treated as blank and wiped. If you are updating prices only, include Handle, the option columns, Variant SKU and Variant Price and nothing else, or you will erase descriptions and images across the catalogue.
Test on a two-product file first, always.