Product CSV columns: what’s required and what overwrites
The Shopify product CSV columns that matter: required fields, option columns that protect variant IDs, the overwrite checkbox, metafield and market columns.
- Required
- Title (new); URL handle + Title (update)
- Encoding
- UTF-8, comma-separated
- Size
- 15 MB per import file
- Where
- Products > Import / Export
- Last checked
In short
A Shopify product CSV needs only Title for new products, and URL handle plus Title for updates. The traps: leaving out Option1 name and Option1 value on an update replaces existing variants, changing an option value creates new variant IDs, and with Overwrite products with matching handles ticked, blank cells clear data. Product metafields use headers like Fabric (product.metafields.shopify.fabric). Files must be UTF-8 and at most 15 MB.
How to use it
- Export the products you’ll change (or download Shopify’s sample CSV) so you start from the current column names.
- Delete the columns you won’t change, but keep URL handle, Title, Option1 name and Option1 value whenever you touch variant data.
- Edit in Google Sheets or another spreadsheet and export as UTF-8 CSV.
- Import with Overwrite products with matching handles ticked only if blank cells should clear values, then check a few products.
Code
columns.txt# Required
New products: Title (plus URL handle when you add variants)
Updating: URL handle and Title
# Variant columns depend on the option columns
Changing SKU, Price, Weight value (grams) ... needs Option1 name and Option1 value.
Leaving out Option1 name/value on update creates a new default variant and DELETES existing variants.
Changing an Option value creates new variant IDs (breaks links and apps that store IDs).
# Overwrite products with matching handles (import checkbox)
Checked: blank cells in included columns overwrite existing values with blank
Unchecked: products whose handle already exists are skipped
# Useful columns
Status active | draft | archived
Published on online store true | false
Tags comma-separated inside one cell, max 250 per product
Barcodes up to 20, separated by ; (gtin:..., upc:...)
Weight value (grams) whole grams: 5.125 kg -> 5125
SEO title / SEO description up to 70 / 320 characters
Product metafields Name (product.metafields.<namespace>.<key>) or product.metafields.<namespace>.<key>
Markets Included / <Market>, Price / <Market>, Compare At Price / <Market>
# Not in the product CSV
Variant metafields (use the variant bulk editor)
Inventory per location (use the inventory CSV)
# File rules
UTF-8, comma-separated, first row = headers, 15 MB max per import file
products-minimal.csvTitle,URL handle,Option1 name,Option1 value,SKU,Price,Status
Rain Jacket,rain-jacket,Size,S,RJ-S,129.00,active
Rain Jacket,rain-jacket,Size,M,RJ-M,129.00,active
Rain Jacket,rain-jacket,Size,L,RJ-L,129.00,active
products-update-metafield.csvTitle,URL handle,Fabric (product.metafields.shopify.fabric),SEO title
Rain Jacket,rain-jacket,recycled-polyester,Rain Jacket in recycled polyester
Written by Lintel. MIT license: free to use in your own store and in client work.
Limits and edge cases
- Variant metafields aren’t supported in the product CSV; use the variant bulk editor.
- Inventory quantity in the product CSV is only for single-location stores; use the inventory CSV for several locations.
- Changing Option values creates new variant IDs, which breaks cart permalinks, ads feeds and apps that stored the old IDs.
- Exports add Included / Price / Compare At Price columns for a market when exactly one of its active catalogs isn’t shared with another market.
Questions
- What columns are required in a Shopify product CSV?
- Only Title for new products. To update products, URL handle and Title. Add Option1 name and Option1 value whenever you change variant data.
- Why did my CSV import delete variants?
- The file updated variant columns without Option1 name and Option1 value, so Shopify created a default variant and removed the existing ones.
- How do I import metafields with a CSV?
- Define the metafield first, then use a header like Fabric (product.metafields.shopify.fabric) or just product.metafields.shopify.fabric.
- What does “Overwrite products with matching handles” do?
- Rows whose handle exists update that product, and blank cells in included columns clear the value. Unticked, existing handles are skipped.
Shopify documentation
- Checked on a Shopify store on the date shown. Shopify changes its admin often; if a step looks different, the idea usually still works.
- Examples use placeholder IDs and your-store.myshopify.com. Replace them with your own.
- MIT license for the code snippets.
Need this built, tested and maintained for your store? See Shopify development.
