Shopify Product CSV File Format: The Complete Reference

TL;DR

Shopify imports products from a CSV with a fixed column structure: one row per variant, products grouped by the Handle column, with columns for title, body, variant options, price, images, and SEO. This reference covers every key column, how to format variants and images correctly, the most common import errors, and where the CSV format breaks down — and what to use instead for complex or supplier-driven catalogs.

What a Shopify product CSV is

A CSV (Comma-Separated Values) file is a plain-text spreadsheet where each line is a row and commas separate the columns. Shopify uses a specific CSV format to import and export products: each row represents a product or one of its variants, and a fixed set of column headers maps to product fields — Title, Body (HTML), Vendor, Variant Price, and many more. Get the format exactly right and Shopify ingests the file cleanly; get a column name, row structure, or value wrong and rows fail or import incorrectly.

The single most important thing to understand is that the Shopify CSV is variant-centric, not product-centric. A product with three variants is three rows, tied together by a shared Handle. The first row carries the product-level data (title, body, images); the following rows carry only the variant-specific data. This structure is the source of both the format’s power and most of the errors people hit, so it’s worth getting clear before you build a file.

Why does Shopify use this row-per-variant structure rather than something more intuitive? Because a CSV is flat — it has no way to nest a list of variants inside a product cell — so the only way to represent a one-to-many relationship (one product, many variants) is to repeat rows and link them with a key, which is the Handle. Understanding that this is a workaround for the limitations of a flat file, not a deliberate data model, explains a lot of the format’s awkwardness: the blank cells on follow-on rows, the three-option ceiling, the metafields gap. These are not arbitrary rules; they are the compromises of squeezing a rich product structure into a spreadsheet. It also explains why a purpose-built product system handles the same data more cleanly — it is not constrained to a flat file in the first place.

The required and key columns

Shopify’s product CSV has dozens of possible columns; a handful are essential and the rest are situational. The ones that matter most:

Title and Handle are non-negotiable; everything else ranges from important (price, options) to optional (SEO, tags). Note what’s missing from the standard columns: metafields. Custom data like dimensions, materials, or ingredients generally isn’t covered by the basic product CSV, which is a key limitation we’ll return to.

How to format variants in a CSV

Variants are where most CSV problems originate. The rules:

• One row per variant — a product with 6 variants has 6 rows.
• Shared Handle — every row of the product must have the same Handle, or Shopify splits the rows into separate products.
• Product-level data on the first row only — Title, Body, and product images go on the first row; subsequent rows leave those blank and carry only variant data.
• Option columns define the matrix — Option1 Name “Size” with Option1 Value “Large”, Option2 Name “Colour” with value “Navy”, and so on, up to three options.
• Each variant needs its own SKU, price, and inventory — on its row.

This is manageable for a fashion product with size × colour, fiddly for a furniture product with size × fabric × finish (which can hit the three-option limit), and genuinely hard for a beauty product with 40 shades (40 rows for one product). The format works, but the effort scales with variant count — fast.

Images in the CSV

Images are referenced by URL in the Image Src column, and their order is controlled by Image Position. To attach a specific image to a specific variant — the colour-to-photo link a fashion or beauty PDP needs — you use the Variant Image column on that variant’s row. Common image mistakes: putting all images on the first row without variant mapping (so every variant shows the same photo), broken or non-public image URLs, and inconsistent positioning. For visual categories, getting variant-image mapping right in the CSV is essential, and it’s one of the more error-prone parts of the format.

SEO and the metafields gap

The CSV includes SEO Title and SEO Description columns, so you can set search-engine listing data on import — worth doing rather than leaving Shopify’s defaults. What the basic product CSV generally does not handle well is metafields: the custom structured data (dimensions, materials, ingredients, specs) that complex catalogs depend on. Importing metafields typically requires a separate process, which means a single CSV import rarely produces a complete product for a furniture, beauty, or other attribute-rich catalog. This is a structural limitation of the format, not a temporary gap — and it’s a major reason teams with real catalogs outgrow CSV import.

Common Shopify CSV import errors (and fixes)

• Variants imported as separate products → inconsistent Handle. Fix: one Handle per product across all its rows.
• Images on the wrong variant → missing/incorrect Variant Image. Fix: set Variant Image per variant row.
• Rows skipped → malformed values (bad characters, wrong number format, missing required fields). Fix: read the per-row error report.
• File too large → exceeds Shopify’s import file-size limit. Fix: split into multiple files.
• Metafields missing → not in the basic CSV. Fix: separate metafield import, or a tool that handles them.
• Encoding issues → special characters garbled. Fix: save the file as UTF-8.

Each is fixable, but notice the pattern: with native CSV you re-encounter these on every import because nothing remembers your file’s shape. That repetition is the real cost.

The encoding issue in particular trips up international and beauty/furniture catalogs more than people expect, because their data is full of the characters that break naïve CSV handling — accented letters in supplier names, the × symbol in dimensions, ™ and ® in product names, em-dashes in descriptions. Open a CSV in the wrong tool or save it in the wrong encoding and these turn into garbled sequences that either fail the import or publish as visible mojibake on the live page. The fix is always to save as UTF-8, but the deeper point is that a plain text format with no schema gives you no protection against this class of error — it will faithfully import garbage if that is what the bytes say. A validated import catches encoding and format problems before they reach the store, rather than after a customer sees “Café Noir” rendered as nonsense.

Where the CSV format breaks down

The Shopify CSV format is a fine tool for what it is: a one-time import of a reasonably simple catalog that you’re willing to shape into Shopify’s exact structure. It breaks down on three fronts — complexity (large variant matrices and metafields it can’t cleanly carry), repetition (every supplier file and every update is a fresh reformatting job), and sync (a CSV is a snapshot, so the import is stale the moment data changes). For a small launch, none of that matters. For a complex or supplier-driven catalog, all three become daily friction, which is why teams move from hand-built CSVs to a tool that maps any format and keeps data in sync.

A useful way to decide is to ask how many times you will run this import. If the answer is “once” and the catalog is simple, a hand-built CSV from Shopify’s template is the pragmatic choice — don’t over-engineer it. If the answer is “every season,” “every supplier,” or “every time prices change,” then you are not really importing a file, you are running a recurring data process, and the CSV format will tax you on every cycle. The format itself is not the problem; using a one-shot format for a repeating job is. Recognising which situation you are in — and matching the tool to it — saves the slow realisation, common to growing Shopify brands, that the “quick” CSV import has quietly become one of the most time-consuming recurring tasks in the business. The columns and rules in this reference are worth knowing either way; just know, too, where they stop serving you.

Related reading: how to import products to Shopify, and importing a supplier CSV fast.

CSV format vs a mapped import

A worked example: a product across CSV rows

It helps to see the row structure concretely. Take a fashion t-shirt in two colours (Navy, White) and three sizes (S, M, L) — six variants, so six rows. The first row carries the Handle (say, classic-tee), the Title, the Body (HTML), Vendor, Tags, the first image, and the first variant’s options and data. The remaining five rows repeat only the Handle and carry their own Option values (Colour/Size), SKU, price, and inventory — Title and Body are left blank, because they belong to the product, not the variant. Variant images (the Navy photo, the White photo) are attached via the Variant Image column on the relevant rows.

Now scale that mental model up and the strain shows. A furniture sofa in 4 sizes × 6 fabrics × 3 finishes is 72 rows for one product, and at size × fabric × finish it is already using all three available option dimensions — there is no room for a fourth like leg style without modelling it differently. A 40-shade foundation is 40 rows. Each of those rows has to carry correct, consistent data, and a single inconsistent Handle anywhere in the block fractures the product. The format does not get conceptually harder as products get more complex; it just gets longer and more error-prone, until hand-maintaining it stops being realistic. That inflection point — usually somewhere between “a simple apparel range” and “a real furniture or beauty catalog” — is where teams move off hand-built CSVs.

Export, edit, re-import — and its risk

A common workflow is to export your current products to CSV, edit them in a spreadsheet, and re-import. It is handy for bulk changes, but it carries a specific danger: re-importing overwrites live data based on the Handle, so any edit someone made in Shopify since you exported can be silently clobbered by your older spreadsheet values. The round-trip also re-exposes every formatting risk — a mis-edited cell, a broken Handle, a dropped column — now applied to products that are already live. For a one-off bulk edit on a stable catalog it is fine with care; as a regular operating pattern it is fragile, because you are repeatedly hand-editing the live source of truth through a format with no validation and no undo. This is precisely the workflow a managed source of truth replaces: edit once in a system that validates and syncs, rather than round-tripping spreadsheets against your live store.

CSV for migration vs ongoing operations

It is worth separating two very different jobs people use CSV for. The first is migration — a one-time bulk move of a catalog onto Shopify. Here CSV is a legitimate tool: you shape the data once, import it, and you are done. Even then, the metafields gap and variant fiddliness mean a complex catalog benefits from staging the data in a source of truth first, but CSV can carry the bulk of a straightforward migration. The second job is ongoing operations — recurring supplier imports, regular updates, multi-store publishing. For this, CSV is the wrong tool, because every cycle repeats the formatting work, overwrites risk, and snapshot staleness. The mistake most growing brands make is using a migration tool (CSV) to run ongoing operations, and feeling the friction every week as a result.

Knowing which job you are doing tells you which tool to reach for. Launching a simple store or doing a one-time move: a well-formed CSV from Shopify’s template is fine. Running a complex catalog, onboarding suppliers, or keeping multiple stores in sync: a mapped, validated, syncing import (like Apimio’s Supplier Bridge into Catalog Hub) removes the format friction entirely and turns imports from a recurring chore into a maintained pipeline. The CSV format is genuinely useful — it is just useful for a narrower job than most catalogs end up needing.

Best practices for Shopify product CSVs

• Start from Shopify’s official sample CSV to get column headers exactly right.
• Use one Handle per product across all its variant rows.
• Put product-level data on the first row, variant data on each variant row.
• Map images to variants with the Variant Image column.
• Save files as UTF-8 to avoid character errors.
• For metafields, complex variants, or recurring/supplier imports, use a mapped import instead of hand-built CSV.

Frequently asked questions

What columns does a Shopify product CSV need?

At minimum Handle and Title; in practice you also need Body (HTML), the Option columns, Variant SKU/Price/Inventory, and Image Src. Handle is the key that groups a product’s variant rows.

How do I format variants in a Shopify CSV?

One row per variant, all sharing the same Handle, with product-level data on the first row only and each variant’s options, SKU, price, and inventory on its own row (up to three option dimensions).

How do I import a CSV into Shopify without errors?

Match Shopify’s template exactly, keep Handles consistent, map variant images, save as UTF-8, and read the per-row error report. For complex catalogs, a mapped import avoids most CSV errors entirely.

Can I import metafields with a Shopify product CSV?

The basic product CSV generally doesn’t carry metafields, so custom data like dimensions or ingredients needs a separate process — or a tool like Apimio that imports metafields alongside the product.

What’s the file-size limit for Shopify CSV import?

Shopify limits the import file size, so very large catalogs must be split into multiple files — one more reason large or supplier-driven catalogs use a mapped import instead.