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). Nexum Gate emits the sample’s spelling.

Want the conversion done rather than documented? Convert your supplier spreadsheet against this format in the browser.

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 Nexum Gate warns when those are unmapped even though the importer would accept the file.

The 61 columns

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