How to Structure, Import, and Update Shopify Product Variants with CSV

When a Shopify product CSV import ignores your variants or fails outright, the cause is usually the file’s structure, not the product data. Shopify doesn’t store all of a product’s variants in one row. It builds each product from a group of rows that share the same handle, which is the product’s unique URL identifier, and it reads each variant from the option values on those rows.

Because of this, a mistyped handle or a missing option value can cause Shopify to skip variants or overwrite existing ones. This guide explains how to structure variant rows, import them, and update existing variants safely.

How Shopify CSV Files Represent Variants

A product with several variants is a group of rows that share one handle. The first row carries the product details. Each additional row adds one variant or one extra image.

For example, a T-shirt sold in two sizes and two colors needs four variant rows. Option1 Name is Size, Option2 Name is Color, and each row combines one size with one color:

Handles Group Rows Into One Product

Shopify treats every row with the same handle as part of the same product. In the table above, all four rows build a single product called Classic Tee rather than four separate products.

The first row for a handle sets the product-level details, such as Title, Body (HTML), Vendor and Published. These fields belong only on that row. The rows that follow reuse the handle to add variants or images and don’t repeat the product details.

The handle must be identical on every row, character for character. Even a small difference splits rows away from the product they were meant to join.

Option Names and Option Values

Options define what makes each variant different. A Shopify product can have up to three options, stored in the Option1, Option2 and Option3 Name and Value columns. The Name column holds the type of choice, such as Size, and the Value column holds the specific choice for that row, such as Small or Medium.

A product that varies along one dimension needs only Option1. When variants vary along two, such as Size and Color, Option2 carries the second dimension. Each variant row must hold a distinct combination of values, so two rows that both read Small and Black don’t describe two separate variants.

Exports and templates differ on whether the Option Name appears on every variant row or only the first. The safest approach is to export one of your own products that already has variants and follow the pattern that file uses.

Variant-Level Columns

Variant-level columns hold data that can differ between variants, so you fill them in on each variant row:

• Identifiers: Variant SKU and Variant Barcode distinguish each variant in your catalog and inventory systems.
• Pricing: Variant Price, Variant Compare At Price and Cost per item. Enter prices as plain numbers without a currency symbol, such as 24.00 rather than $24.00.
• Inventory: Variant Inventory Tracker is either shopify, so Shopify tracks stock, or blank. Variant Inventory Qty holds the stock count. Variant Inventory Policy is deny or continue, which controls whether the variant can still sell when it’s out of stock.
• Shipping and tax: Variant Grams works together with Variant Weight Unit. Variant Fulfillment Service is typically manual, while Variant Requires Shipping and Variant Taxable take TRUE or FALSE.

Shopify reads these values per row, so a variant row with an empty price or quantity won’t inherit the value from the row above it.

Image Rows vs. Variant Rows

An image-only row adds a product image without creating a variant. It uses the product’s handle but leaves the option and variant columns blank, which is what separates it from a variant row.

Image Position sets the order of the product’s images, with position 1 as the featured image. Variant Image attaches an image to a specific variant so it appears when a shopper selects that variant, which is why you enter it on the variant’s own row. In both cases, image URLs must be complete addresses starting with https://, because relative paths or bare file names won’t point Shopify to the image.

Preparing a Variant CSV That Will Import

The most reliable starting point is a file Shopify has already produced. If you’re changing existing products, export them, edit the export in a spreadsheet program such as Google Sheets, and import the updated file. The headers, columns and variant rows then already match Shopify’s structure, and you only change values.

If you’re adding new products and have nothing similar to export, create one product with all its variants in the Shopify admin and export it. Use that file as your template. When an import misbehaves, comparing your rows against it side by side makes differences in handles, option columns or variant fields easy to spot.

Before you upload, check the file against these requirements:

• Exact headers: Column names are case-sensitive and must match Shopify’s sample file exactly, so Handle works but handle doesn’t. Missing or mismatched headers make the import fail, which often happens with CSVs created by other tools.
• UTF-8 encoding: Google Sheets saves as UTF-8 by default, but other spreadsheet software may require you to select it when saving.
• 15 MB maximum: If the upload shows an error or times out, split the data into smaller files and upload each one separately.

Then import a small subset first, such as a few products with their full variant sets. An import can’t be canceled once it starts, and Shopify keeps no history of past imports beyond recent changes in the store’s activity log, so a structural mistake in a large file reaches every product it touches. If you’re a Shopify Partner handling a large import for a merchant, run the test in a development store before working on the live store.

Importing the CSV and Updating Existing Variants

The overwrite setting you choose during import decides whether Shopify only creates new products or also changes existing ones.

Import Steps in Shopify Admin

1. In your Shopify admin, go to Products.
2. Click Import.
3. Click Add file, then select your CSV file.
4. Optional: deselect Publish new products to all sales channels if you don’t want newly created products to appear on your sales channels right away.
5. Optional: select Overwrite products with matching handles if the file should update existing products. See the next section for what this changes.
6. Click Upload and continue.
7. Review the import details that Shopify shows you.
8. Click Import products.

Shopify sends a confirmation email after the upload.

How Overwrite Affects Existing Variants

If you leave Overwrite products with matching handles unselected, Shopify ignores every row whose handle matches an existing product. The file can create new products but can’t change existing ones, including adding variants to them. If you select the setting, the CSV values replace existing values in every column the file includes.

Because overwrite works column by column, which columns you include matters as much as their values:

• A column is included but left blank: The blank value overwrites the existing one. An empty Vendor cell, for example, clears the product’s vendor.
• A non-required column is left out entirely: The existing value stays unchanged. If your file has no Variant Image column, current variant images are kept.
• A variant column is included without the columns it depends on: Shopify deletes existing data. A file that includes the SKU column but leaves out Option1 Name and Option1 Value deletes the product’s variant option.

The third case is the most damaging, because a file meant only to update SKUs can remove the option structure that separates the variants. When you update existing products, include only the columns you intend to change, and keep the Option Name and Option Value columns whenever the file touches variant fields such as SKU, price or inventory. This lets Shopify match each row to the correct variant.

Troubleshooting Common Variant Import Errors

Most failed or partial variant imports come from mismatched handles, an option change Shopify can’t apply in one import, incorrect column headers, or a file not saved as UTF-8. Find your message or symptom below and apply the matching fix.

The “Line is invalid” error needs two imports because Shopify can’t move an option and introduce a new one in the same pass. Give the moved option a temporary name first:

1. In the first CSV, put the moved option in its new position under a temporary name such as Size. (with a trailing period), and add the new option, such as Type, in the position you want. Import this file.
2. In a second CSV, rename Size. to Size and import that file.

Both files update existing products, so select the overwrite setting for each import and keep the Option Name and Option Value columns in both.

What the Native Product CSV Can’t Handle

The native product CSV covers variant options, prices, SKUs and images, but some variant data and bulk actions fall outside it. A completed import doesn’t always mean every value was applied.

• Variant metafields: Metafields are custom fields that store extra data on a product or variant. A standard product export doesn’t include metafield columns, and adding one by hand isn’t a documented feature. Attempts to set variant metafields this way have failed even when the import completed, so don’t rely on the CSV for this data.
• Inventory with multiple locations: If a store has more than one location, inventory quantities may not import and can default to zero. This behavior is documented for theme test stores and isn’t confirmed for every store, so check quantities after your test import.
• Rich media: You can’t import 3D models or videos through a CSV.
• Deleting products and channel availability: You can’t use a CSV to bulk-delete products or bulk-update availability on other sales channels.

For these tasks, use the bulk actions and bulk editor in the Shopify admin or other tooling built for the job.

Conclusion

Shopify CSV variants import reliably when every row for a product shares the same handle, each variant has its own combination of option values, and the option columns stay in the file whenever you update variants. Building your file from a Shopify export and testing it on a few products keeps your variants, prices and images intact as you scale up. We hope this guide helps you structure, import and update your product variants with confidence.