P
Portaim

Shopify Variants CSV Import: Options, Handles, SKUs + Default Title Fix

Shopify CSV Import Variants Product Options

If you’re importing products (often starting from supplier Excel/XLSX files), Shopify’s product CSV is where variant mistakes can get expensive: wrong grouping, duplicate options, or updating SKU without the right option columns can create a new default variant and delete existing variants.

This guide focuses on what Shopify’s docs (and one Shopify Community thread) explicitly say about:

  • how Shopify groups variants by Handle
  • how Option name/value columns work (up to 3 options)
  • how to update SKU safely (critical dependency)
  • how to fix “Validation failed: The variant Default Title already exists.”

If a detail isn’t covered below, treat it as “Verify in Shopify Admin / Help Center.”

How Shopify groups variants in a CSV (Handle rules)

What “Handle” is and why it’s required for adding variants

Shopify describes the Handle as “the unique identifier for each product,” used in the product page URL and “based on the value in the Title column.” If you’re adding variants for a product, Shopify says the URL handle (Handle) column is required. A valid handle can contain letters, dashes, and numbers, and it can’t contain spaces.

Variant row structure (first row vs following rows)

For a product with variants, Shopify’s CSV guidance is:

  • First row for the product: include all the product fields (and the first image URL if you use images).
  • Following rows (variants): include the Handle, then skip these columns: Title, Description, Vendor, Tags. Fill out the rest of the variant details (and each image URL if relevant).

Step-by-step instructions

1) Backup first (export your products)

Before importing, Shopify cautions: “make sure that you have a backup of your product data.”

Action: Export your products first (verify the exact export steps in Shopify Admin / Help Center).

2) Prepare Handles (valid characters, no spaces)

Goal: one unique Handle per product, shared across all its variant rows.

  • Handle must contain letters, dashes, numbers and no spaces.
  • If you see “Ignored line because handle already exists,” Shopify’s guidance is: the handle “uniquely identify each individual product,” so “make sure you have a unique handle for each product in your CSV.”

Action:

  • Creating new products? Ensure each product has its own unique handle.
  • Updating an existing product? Use the existing product’s handle (verify in Shopify Admin / Help Center).

3) Add options correctly (Option columns; up to 3 options)

Shopify states:

  • A product can have up to 3 options.
  • Shopify documents Option1 name and Option1 value, and says a product can have up to 3 options—verify the exact Option2/Option3 column names in Shopify Admin / Help Center.
  • Option1 name is where you enter the option name (like size or color).
  • If a product has only one option, Option1 Name should be “Default Title.”

Action:

  • For each variant row, fill in Option1 Name (and Option2/Option3 if needed).
  • Fill in Option1 Value with a unique value per variant (e.g., “Small,” “Medium,” “Large”).

Notes (from Shopify’s “product with variants” structure):

  • The second row repeats Handle.
  • The second row skips Title (left blank here) and focuses on variant-specific fields.

Short example: two variants differentiated by Option1 Value

Handle,Title,Option1 Name,Option1 Value,SKU
my-shirt,My Shirt,Color,Black,SKU-BLK
my-shirt,,Color,White,SKU-WHT

4) Fix “Default Title already exists” by making option values unique per variant row

The Shopify Community thread explains:

  • The error “Validation failed: The variant Default Title already exists.” usually means you’re trying to create multiple variants without specifying unique options.
  • Shopify automatically assigns “Default Title” to a variant that doesn’t have an option listed, and then it flags the duplicate.

Fix (numbered):

  1. Add Option1 Name (example values: “Color” or “Size”).
  2. Add Option1 Value and set a unique value for each variant row.

Example that triggers the issue (conceptually):

  • Multiple rows share a Handle, but option columns are missing or not unique → Shopify assigns “Default Title” → duplicates.

Example that resolves it (unique Option1 Value per row):

Handle,Title,Option1 Name,Option1 Value
my-shirt,My Shirt,Size,S
my-shirt,,Size,M
my-shirt,,Size,L

5) Update SKUs safely (include Option1 name + Option1 value to avoid default variant creation)

This is the most common “surprise deletion” trap Shopify calls out.

Shopify says that even though Title and Handle are the only required columns for updates, some columns depend on other columns. Specifically:

  • If you update a variant-related column like SKU (or Weight value (grams)), … you must also include the Option1 name and Option1 value columns.
  • Warning from Shopify: If you don’t include Option1 name and Option1 value, “a new default variant is created and existing variants are deleted.”

Safe pattern for SKU updates (example columns to include):

Handle,Title,Option1 Name,Option1 Value,SKU
my-shirt,My Shirt,Color,Black,SKU-BLK-NEW
my-shirt,My Shirt,Color,White,SKU-WHT-NEW

If you include SKU in the CSV but omit the required option columns, Shopify warns existing data can be “deleted or removed” (example: “the product variant option is deleted”).

6) Choose overwrite behavior for matching handles (and understand ignored rows)

When importing, Shopify lets you choose Overwrite products with matching handles:

  • If selected: when the import CSV handle matches an existing product handle, CSV values overwrite existing values in matching columns.
  • If not selected: products that match an existing handle are ignored during import.

Action: Pick the overwrite option intentionally, especially if you’re importing updates rather than brand-new products.

7) Test with a small batch, then import (file size limit + confirmation email)

Shopify cautions:

  • Product imports started with a CSV can’t be cancelled once they begin, and you can’t view a history of past imports.
  • Your product CSV can’t exceed 15 MB.
  • When your CSV file is uploaded, Shopify sends a confirmation email to the email account you used to set up your Shopify store.

Action (numbered):

  1. Create a small test CSV with 1–3 products (and a few variants).
  2. Import it and review results in Shopify Admin (verify your exact workflow in Shopify Admin / Help Center).
  3. Scale up once you’re confident the option columns and overwrite behavior are correct.
  4. Watch for the Shopify confirmation email after upload.

Common pitfalls

Including SKU without option columns (deletes/removes existing variant data)

Shopify explicitly warns: if you include a non-required column that relies on other column data not included (example: SKU without Option1 name/value), then existing data is “deleted or removed.” They also warn it can create a new default variant and delete existing variants.

Duplicate option values (“options are not unique”)

Shopify’s “Validation failed: options are not unique” means the product has duplicate options—for example, two variants with the same option values (like “2 medium products, both in black”). Shopify’s docs mention an error for duplicate option combinations. Verify other duplicate-variant rules in Shopify Admin / Help Center.

Blank cells overwriting existing data

Shopify’s overwrite behavior notes:

  • If a non-required column is blank, the matching value in Shopify is overwritten as blank.
  • If a non-required column is not included at all, the existing value remains the same.

Practical implication: leaving blanks in columns you didn’t mean to change can wipe data.

Hitting variant limits (per product) or daily variant creation limits (some stores)

Shopify states:

  • Up to 2,048 variants per product.
  • Up to 3 options per product.
  • Stores with 50,000+ variants can hit a daily limit of 1,000 new variants per day via app or CSV import; Shopify Plus stores are exempt.
  • Shopify’s CSV import issues page states: for stores with 50,000 product variants (excluding Plus), no more than 1,000 new variants can be created within a 24-hour timeframe, and “the 24 hour timer starts at the time of the first upload of the day.”

If you see “Daily variant creation limit reached, please try again later”: verify your store’s current variant count and plan imports in smaller chunks.

Safety notes (read before you import)

Backup/export first, test small batch

Shopify cautions to have a backup before import. Pair that with a small test batch to validate option columns and grouping by handle.

Imports can’t be cancelled once started; no past import history

Shopify states product imports started with a CSV can’t be cancelled and you can’t view a history of past imports. Treat each import as “commit once.”

Overwrite risks: blanks overwrite to blank; option changes can recreate variant IDs

Two key Shopify cautions:

  • Blank values in non-required columns overwrite existing data as blank.
  • Shopify cautions that changing Option1 value deletes existing variant ID values and creates new variant IDs, and that can break third-party dependencies.

Third-party dependencies risk if variant IDs change

Shopify cautions that changing Option1 value deletes existing variant ID values and creates new variant IDs, which can break third-party dependencies relying on variant IDs.

FAQ

1. Do I need the Handle column when I’m adding variants in a Shopify product CSV?

Yes—Shopify says if you’re adding variants for a product, the URL handle (Handle) column is required.

2. Why did Shopify create a new default variant after I tried to update SKUs via CSV?

Shopify warns that if you update a variant-related column like SKU but don’t include Option1 name and Option1 value, then a new default variant is created and existing variants are deleted.

3. What causes “Validation failed: The variant Default Title already exists.” and how do I fix it?

A Shopify Community explanation says it usually happens when you try to create multiple variants without unique option values. Fix by adding Option1 Name and Option1 Value, and make Option1 Value unique per variant row.

4. How many options and variants can one product have in Shopify?

Shopify states up to 3 options and up to 2,048 variants per product.

5. If I change Option1 value, will my variant IDs change (and why does that matter)?

Shopify cautions that changing Option1 value deletes existing variant ID values and creates new variant IDs, which can break third-party dependencies relying on variant IDs.

6. What does “Validation failed: options are not unique” mean in a variants CSV import?

Shopify says this occurs when a product has duplicate options—for example two variants with the same option values (like two Medium/Black variants).

7. Why does Shopify say a line was ignored because the handle already exists?

Shopify notes the handle uniquely identifies each product and says to ensure you have a unique handle for each product in your CSV. Also, if you didn’t select Overwrite products with matching handles, Shopify says matching-handle products are ignored during import.

8. What happens if I leave a non-required CSV column blank vs removing the column entirely?

Shopify says blanks in non-required columns overwrite existing values as blank. If the column is not included in the import file, existing values remain unchanged.

9. Is there a daily limit for creating new variants by CSV, and when does the 24-hour timer start?

Shopify states that for stores with 50,000 variants (excluding Plus), no more than 1,000 new variants can be created by CSV uploads (or API) within 24 hours, and the timer starts at the time of the first upload of the day. Shopify also states Plus stores are exempt from the daily upload limit.

10. Can I import variant metafields using the product CSV file?

Shopify says variant metafields aren’t supported for product CSV import/export. They say to bulk edit variant metafields, use the variant bulk editor and add metafield columns.