Shopify product CSV template explained (handles, variants, options)
Shopify’s product CSV is not a free-form table. It is a flattened representation of products and variants where each row is usually one variant, and a shared Handle tells Shopify which rows belong to the same product. Once you read the file that way, most “random” import bugs resolve into a small set of structural mistakes.
Column names and behavior are defined in Shopify Help under Using CSV files to import and export products. Export a product from your own shop when you need a ground-truth header row.
Handles: the join key
Handle is the stable identifier in the URL and in CSV rows. Rows that share a handle are interpreted as variants of one product. Change the handle accidentally and you create a new product—or orphan rows the importer cannot attach cleanly.
Practical rules
- Pick a handle once per product and reuse it on every variant row.
- Avoid stray whitespace; handles are easy to duplicate with invisible characters.
- Import order matters less than consistency—every variant row must agree on handle.
One row per variant
For a product with color and size, expect a row per combination. The title and body HTML often repeat on each variant row; variant-specific fields (SKU, price, barcode, inventory) differ per row. When you collapse variants into one row, you lose data Shopify expects to spread across multiple lines.
Option name and value columns
Shopify exposes Option1 Name, Option1 Value, and optionally Option2 and Option3. Those columns define the axes of variation (for example, Color and Size). If you create a product with only one variant and leave options blank, Shopify may show Default Title in the admin—that is a symptom of how the variant was created, not arbitrary text you should fight. More detail: variant options and Default Title.
Title, body, and duplicated fields
Product-level text fields repeat across variant rows by design. That feels wasteful in a spreadsheet, which is why many teams switch to template-aware editors or scripts for large catalogs. The importer, however, expects that redundancy.
Images
Image columns hold URLs that resolve to publicly reachable media—not files embedded in the CSV. If a URL 404s or needs authentication, the row may import while the image silently fails. See product images and URLs.
When exports beat invented templates
A CSV exported from your store reflects enabled features, locales, and sometimes plan capabilities. Blog templates and screenshots go stale. Treat an export as your schema reference when building imports programmatically—including when you avoid Excel.
FAQ
Why does my file have far more rows than products?
Variant count multiplies rows. Ten sizes and five colors for one style can be fifty rows.
Can I rename Option columns?
No. Header text must match Shopify’s expected names for the importer to map fields.
Where do metafields go?
Metafield columns appear when you export with metafields included or when Shopify’s docs for your workflow say they are supported. If your export lacks them, do not invent headers from memory—use the exporter or the current documentation for your admin capabilities.