Shopify import reference

The Shopify product CSV, column by column, including the rows that confuse everyone.

The Shopify product CSV is not one row per product. It is one row per variant, plus extra rows for additional images, all tied together by the handle. Once that is clear, most import errors explain themselves.

Publish to Shopify from Nexodo See Shopify PIM

Handle

The column that groups variants and images into one product.

Variant rows

Product-level fields only appear on the first row of a handle.

Image rows

Extra images are extra rows with almost every column blank.

The model

One handle, many rows.

The handle is the URL fragment for the product and the key that binds a group of rows together. The first row carrying a handle holds the product-level information: title, body, vendor, type, tags, published state and the first image. Every later row with the same handle adds either a variant or an image.

This is why a file that looks wrong is often right. A CSV with a title in one row and forty blank-looking rows beneath it is a product with forty variants, and repeating the title on each of those rows is a common mistake that produces confusing results rather than an error.

Row type	What it carries	What stays blank
First row of a handle	Product fields, first option value, first image	Nothing that applies
Additional variant row	Handle, option values, variant fields	Title, body, vendor, type, tags
Additional image row	Handle, image source, image position, alt text	Everything else

Product columns

The columns that describe the product rather than the variant.

These appear once per product, on the first row of the handle. Title and body are the customer-facing content. Vendor is the brand. Product category is the Shopify taxonomy value, while type is your own free-text classification, which is the same split as Google's category and product type fields.

Published controls whether the product is visible on the online store, and it is a frequent cause of a successful import that appears to have imported nothing. Check it before assuming the file failed.

Column	Holds	Note
Handle	URL fragment and grouping key	Lower case, hyphenated, must be unique
Title	Product name	First row of the handle only
Body (HTML)	Product description, HTML allowed	Strip supplier styling before import
Vendor	Brand or manufacturer	Use the manufacturer, not the supplier
Product Category	Shopify standard taxonomy value	Distinct from Type
Type	Your own product type	Free text, used for collections
Tags	Comma separated tag list	Quote the field if tags contain commas
Published	TRUE or FALSE for the online store	FALSE hides an otherwise successful import

Variant columns

Options define the variants, and the option names must be consistent.

A product has up to three option axes. Each variant row carries the option name and the option value for each axis. The option names have to be identical across every row of the handle, because a difference in spelling or case creates a second axis rather than a second value.

The variant columns then carry the commercial and logistical data: SKU, barcode, price, compare-at price, weight and unit, inventory tracker and quantity, inventory policy, fulfilment service, whether it requires shipping and whether it is taxable. The barcode column is where a GTIN belongs.

Column	Holds	Common mistake
Option1 Name and Value	First variant axis, for example Size	Name spelled differently across rows
Variant SKU	Your internal stock keeping unit	Left blank, which breaks inventory work
Variant Barcode	The GTIN, UPC, EAN or ISBN	Leading zeros lost by a spreadsheet
Variant Price	Price, no currency symbol	Thousands separator included
Variant Grams and Weight Unit	Shipping weight	Unit mismatch between rows
Variant Inventory Qty	Stock on hand	Sent when the source of truth is elsewhere
Variant Image	Image for this specific variant	Confused with the Image Src column

Errors

The four failures that account for most wasted imports.

Barcodes lose their leading zeros because the file was opened and saved in a spreadsheet that typed the column as a number. Handles collide because two different products were given the same slug. Option names drift because rows were assembled from two different exports. Images fail because the URL is not publicly reachable at import time.

All four are catchable before upload, which is the argument for generating the file from a governed catalog rather than assembling it by hand. Nexodo previews a Shopify publish and shows what will be created and changed before anything is applied, so a malformed value is a review item rather than a live product page.

Open and save CSV files as text, never as a spreadsheet number column
Check handle uniqueness before upload
Verify option names are byte-identical across a handle
Confirm image URLs are publicly reachable before import

Frequently asked questions

Clear answers before you evaluate a PIM.

Why does my import create duplicate products?

Almost always the handle. A row whose handle differs by a character, a case difference or a trailing space becomes a separate product. Normalize handles before generating the file.

Where does the GTIN go?

In the Variant Barcode column. Store it in your catalog normalized and as text so leading zeros survive the export, and check the value length after generating the file.

Can I update only some columns?

Shopify's import applies the file it is given, so partial files behave differently depending on the options chosen at import. For recurring updates a governed publish that computes the difference is safer than repeatedly uploading a hand-built CSV.

How do I add several images to one product?

Add one extra row per image with only the handle, image source, image position and alt text filled in. The first image belongs on the product's first row.

Continue your product data research

Shopify PIM

Test Nexodo with a supplier file your team already uses.

Tell us how your supplier files arrive and what your channels reject, and we will tell you whether this workflow fits.

Talk to us See what Nexodo does

A person replies, normally within one business day
Use a representative product sample
We will say plainly if Nexodo is the wrong fit

The Shopify product CSV, column by column, including the rows that confuse everyone.

One handle, many rows.

The columns that describe the product rather than the variant.

Options define the variants, and the option names must be consistent.

The four failures that account for most wasted imports.

Clear answers before you evaluate a PIM.

Continue your product data research

Put governed product data upstream of Shopify.

Google Shopping feed specification: what is required, what is conditional, and what breaks.

Product attribute mapping: turning every supplier's columns into one model.

Build channel output from approved product data, not another spreadsheet.

Test Nexodo with a supplier file your team already uses.