The Shopify product CSV format, column by column

Shopify’s product importer reads a flat CSV with a fixed header. The table below lists all 61 columns in the exact order they appear in the official product_template.csv sample, which is the authority when the prose documentation and the file disagree — and they do. The column reference calls column 11 Barcodes; the sample file calls it Variant Barcodes. Shopify’s common-import-issues article still prints an older header set entirely (Handle, Body (HTML), Variant SKU). CSV Forge emits the sample’s spelling.

Three kinds of row in one table

The single biggest source of failed imports is treating the CSV as one row per product. It is not. One product occupies as many rows as it has variants, plus one extra row per image beyond the first:

The product’s first row carries product fields (Title, Description, Vendor, Tags, SEO, option names) plus the first variant and the first image.
Each additional variant row repeats only URL handle and the variant columns. Product fields are left blank — Shopify ignores them there, and filling them invites confusion about which row “wins”.
Each additional image row carries URL handle, Product image URL, Image position and optionally Image alt text. Nothing else.

Rows are tied to their product by URL handle alone. If the handle differs by a single character between two rows meant to be the same product, you get two products.

Required, and effectively required

Title is the only column Shopify requires to create a new product. Adding variants additionally requires URL handle; updating existing products requires both. In practice a usable catalogue also needs SKU, Price and at least one image URL, which is why CSV Forge warns when those are unmapped even though the importer would accept the file.

The 61 columns

#	Column	Type	Scope	Constraint	Example
1	Titlerequired	text	product	The only column Shopify requires for a new product. Blank on variant rows.	Physical Product “The Band” T-Shirt
2	URL handle	handle	product	Letters, digits and dashes only; no spaces. Repeated on every row of a product.	physical-product-the-band-t-shirt
3	Description	longtext	product	Plain text or HTML. Quoted when it contains commas or line breaks.	Celebrate the timeless legacy of…
4	Vendor	text	product	Free text. Commonly your supplier or brand name.	Harmony Threads
5	Product category	text	product	A Shopify taxonomy breadcrumb or taxonomy ID. Not the same field as the Google category.	Apparel & Accessories > Clothing > Clothing Tops > T-Shirts
6	Type	text	product	Your own free-text product type.	Graphic shirt
7	Tags	list	product	Comma-separated, max 250 characters for the whole cell.	Unisex, Clothing, Men, Women
8	Published on online store	boolean	product	TRUE or FALSE. Defaults to TRUE when the cell is blank.	TRUE
9	Status	enum	product	active, draft or archived. If the header is present the cell needs a value.	active
10	SKU	text	variant	Identifies the variant. Keep leading zeros — it is text, not a number.	TheBandTShirt-SG
11	Variant Barcodes	list	variant	Up to 20 values separated by semicolons, optionally type-prefixed (ean:, upc:, gtin:, isbn:).	ean:4006381333931; upc:036000291452
12	Option1 name	text	product	Set once on the first row of the product. Max three options per product.	Size
13	Option1 value	text	variant	One value per variant row. Combinations must be unique inside a product.	Small
14	Option1 Linked To	text	product	Optional metafield reference that links the option to a metaobject.	product.metafields.shopify.color-pattern
15	Option2 name	text	product	Only when the product has a second option.	Color
16	Option2 value	text	variant	Required on every variant row once Option2 name is set.	green
17	Option2 Linked To	text	product	Optional metafield reference for option 2.	product.metafields.shopify.color-pattern
18	Option3 name	text	product	Only when the product has a third option. Shopify allows no fourth.	Material
19	Option3 value	text	variant	Required on every variant row once Option3 name is set.	Cotton
20	Option3 Linked To	text	product	Optional metafield reference for option 3.	—
21	Price	money	variant	Number only — no currency symbol, no thousand separator, dot as decimal mark. Blank imports as 0.00.	19.99
22	Compare-at price	money	variant	Same numeric rules as Price. Leave blank when there is no reference price.	24.99
23	Cost per item	money	variant	Your cost. Used for margin reporting; never shown to customers.	11.00
24	Charge tax	boolean	variant	TRUE or FALSE.	TRUE
25	Tax code	text	variant	Avalara or Shopify Tax code. Plan-dependent; usually left blank.	A9277
26	Unit price total measure	decimal	variant	Unit-pricing numerator (EU unit price). All four unit-price columns go together.	500.00
27	Unit price total measure unit	text	variant	Unit for the total measure, e.g. ml, g, cl, kg, l, m², m.	ml
28	Unit price base measure	decimal	variant	Unit-pricing denominator.	50.00
29	Unit price base measure unit	text	variant	Unit for the base measure.	ml
30	Inventory tracker	enum	variant	shopify, shipwire, amazon_marketplace_web, or blank for no tracking.	shopify
31	Inventory quantity	integer	variant	Whole number. Single-location stores only; multi-location needs the separate inventory CSV.	47
32	Continue selling when out of stock	enum	variant	DENY stops selling at zero stock; CONTINUE allows overselling.	DENY
33	Weight value (grams)	integer	variant	Integer grams. No unit text, no decimals — convert kg/lb/oz before export.	150
34	Weight unit for display	enum	variant	Display unit only. The stored value stays in grams.	g
35	Requires shipping	boolean	variant	FALSE for digital goods and services.	TRUE
36	Fulfillment service	text	variant	manual, or the handle of a custom fulfillment service. Custom services require a SKU.	manual
37	Product image URL	url	image	A publicly reachable http(s) URL. Shopify downloads it at import time.	https://burst.shopifycdn.com/photos/forest-hiker.jpg
38	Image position	integer	image	Starts at 1 and increases per product. Extra images go on extra rows.	1
39	Image alt text	text	image	Max 512 characters.	Green t-shirt with The Band graphic
40	Variant image URL	url	variant	The one image shown for this variant. http(s) URL.	https://cdn.example.com/red-small.jpg
41	Gift card	boolean	product	TRUE only for gift-card products, which cannot be created by import.	FALSE
42	SEO title	text	product	Max 70 characters.	Vintage The Band Graphic T-Shirt
43	SEO description	text	product	Max 320 characters.	Celebrate the legacy of rock icons…
44	Color (product.metafields.shopify.color-pattern)	list	product	Standard product metafield. Semicolon-separated colour names.	green; gray; red
45	Google Shopping / Google product category	text	product	A Google taxonomy breadcrumb or ID. Not used by the Google & YouTube channel.	Apparel & Accessories > Clothing > Shirts & Tops
46	Google Shopping / Gender	text	product	Unstructured Google metafield.	Unisex
47	Google Shopping / Age group	text	product	Unstructured Google metafield.	Adult (13+ years old)
48	Google Shopping / Manufacturer part number (MPN)	text	product	Unstructured Google metafield.	TSH-12345-GRY-S
49	Google Shopping / Ad group name	text	product	Unstructured Google metafield.	Rock Band Graphic Tees
50	Google Shopping / Ads labels	text	product	Unstructured Google metafield.	Music Merch
51	Google Shopping / Condition	text	product	Typically New, Refurbished or Used.	New
52	Google Shopping / Custom product	boolean	product	TRUE or FALSE.	FALSE
53	Google Shopping / Custom label 0	text	product	Unstructured Google metafield.	Top Seller
54	Google Shopping / Custom label 1	text	product	Unstructured Google metafield.	—
55	Google Shopping / Custom label 2	text	product	Unstructured Google metafield.	—
56	Google Shopping / Custom label 3	text	product	Unstructured Google metafield.	—
57	Google Shopping / Custom label 4	text	product	Unstructured Google metafield.	—
58	Packed product length	decimal	variant	All four packed-dimension columns must be filled together, or all left blank.	30
59	Packed product width	decimal	variant	All four packed-dimension columns must be filled together, or all left blank.	20
60	Packed product height	decimal	variant	All four packed-dimension columns must be filled together, or all left blank.	3
61	Packed product dimension unit	enum	variant	cm or in. Required when any packed dimension is set.	cm

Value rules that reject files

Money columns take digits only

Price, Compare-at price and Cost per item accept a number with a dot decimal mark and nothing else. No currency symbol, no thousand separator, no decimal comma. A blank price imports as 0.00 rather than failing, which is worse than an error because it is silent.

Booleans and enums are not interchangeable

The sample file writes booleans as TRUE/FALSE, out-of-stock behaviour as DENY/CONTINUE, and status as lowercase active/draft/archived. Writing true into Continue selling when out of stock is a rejected value, not a synonym for CONTINUE.

Weight is an integer number of grams

Weight value (grams) takes a whole number with no unit text and no decimals. Weight unit for display is a separate, cosmetic field (g, kg, lb, oz) that does not change the stored value. A source column in kilograms must be multiplied by 1000 and rounded before export.

Packed dimensions are all four or none

Packed product length, width, height and dimension unit must be populated together or all left blank. Three of four is invalid, which is a common outcome when a supplier sheet gives dimensions but no unit column.

Barcodes are semicolon-separated

Variant Barcodes takes up to 20 values separated by semicolons, optionally type-prefixed as ean:, upc:, gtin: or isbn:. Commas are not separators here. Never include both a legacy Barcode column and Variant Barcodes.

Options: three maximum, combinations unique

A product supports at most three options. Option names go on the product’s first row, option values on every variant row, and the combination of values must be unique within the product or the import fails with Validation failed: options are not unique. A simple product with no options leaves all six option columns blank; Shopify creates the default variant itself.

Length limits

SEO title 70 characters, SEO description 320, Image alt text 512, and the whole Tags cell 250. These truncate rather than fail, so they are warnings in CSV Forge and not errors.

File-level requirements

UTF-8 encoding, LF line endings, comma delimiter.
Maximum 15 MB per product CSV. Larger catalogues must be split into several files; there is no documented row cap, only the size cap.
Image URLs must be publicly reachable over http(s) at import time — Shopify downloads them. Local file paths and bare filenames produce getaddrinfo errors.
Inventory quantities apply to single-location stores. Multi-location inventory needs the separate inventory CSV.
Variant metafields cannot be imported through the product CSV at all. Product metafields can, using <name> (product.metafields.<namespace>.<key>) headers.

Overwriting is destructive

When you import a file whose handles already exist and choose to overwrite, an empty cell can erase existing data rather than leave it alone. Export your current products first and map only the columns you intend to change. See Shopify’s note on overwriting with a CSV.

Convert a supplier file against this format →