Shopify Product CSV Checker › Guides

Shopify CSV handles, variant rows and duplicate handles

In a Shopify product CSV, the URL handle column is what connects rows into one product. Most problems with variants and duplicate products come from handles. Here's how Shopify expects them to work.

URL handle rules

The handle is the unique identifier for each product and is used in the product page URL.
By default it's based on the title: a product titled Black Sunglasses gets the handle black-sunglasses.
A valid handle can contain letters, dashes and numbers, and no spaces.
You can set a custom handle if you want the URL to be different from the product name.
For new products, URL handle is required as soon as you add variants. For updates, it's always required along with Title.

How to lay out variant rows

Shopify describes two layouts:

Simple product (no variants): put all the product fields and the first image URL on the first row. Each additional image gets its own row with only the handle and the image URL.
Product with variants: put all the product fields and the first image on the first row. On each following row, enter the URL handle, skip Title, Description, Vendor and Tags, and fill in that variant's details and image URL.

Options work like this:

A product can have up to 3 options (Option1 to Option3 name and value), such as Size or Color.
Shopify's column table says that if a product has only one option, the option name should be Default Title.
Changing values in the Option1, Option2 or Option3 value columns deletes existing variant IDs and creates new ones, which can break apps that depend on those IDs.
Moving an existing option to a different position (for example, Size from Option 1 to Option 2) can cause "Line is invalid (No details)". Shopify's workaround is to use a temporary name such as Size., import, and then rename it in a second import.

Duplicate handles

Because the handle identifies the product, two different products sharing a handle will be treated as one. Give each product its own handle, and keep the same handle only on rows that belong to the same product (its variants and extra images).

Handles also matter for existing products. If you select Overwrite products with matching handles, rows whose handle matches an existing product overwrite that product's values. If you don't, those rows are ignored. So reusing a handle that's already in your store either replaces that product or gets skipped.

Adding extra image rows

Use one row per image. Copy the product's handle into the new row and paste the image URL into Product image URL. Shopify allows up to 250 images per product.

What our checker does with handles and variants

Fixes automatically:

A blank handle on a row that has a Title is filled in from the title (Shopify's documented default).
Invalid handles, such as ones with spaces, are converted to a valid slug the same way on every row of that product. This only happens if the new handle doesn't clash with another product, and the change log notes that the product URL changes.
Variant and image rows that are separated from their product are moved directly under it, without changing any values.
Single-variant products with no options get Title / Default Title.

Reports without changing:

A handle shared by different products, and handle clashes.
Rows with no handle and no title.
A missing Option1 name, option values with no name, and missing option values.
Duplicate variant combinations, more than 3 options, and more than 2048 variants.

You decide which product keeps the handle. Note that the slug conversion drops accented letters (café becomes caf), so check any handle the change log says was changed.

Check your file for free

Run your CSV through the free Shopify Product CSV Checker. Your file is processed in your browser and never uploaded. It fixes only the problems that have one clear answer, reports the rest without changing them, and gives you a change log listing every edit. A fixed file can still fail in Shopify, and Shopify can skip some products even when it says "Products imported". We cannot guarantee Shopify will import every product, so review the change log and check your product count after importing.

Open the free checker

Want us to fix it?

$12 per file. Pay with Stripe, then email your CSV to hello@agentstackmedia.com. We reply with the corrected file and a change log. Reply to your delivery email within 5 days and we will re-fix the same file once, free. We deliver by email, by hand, so delivery is not instant. We only make changes that have one clear answer, we list anything left for you to fix by hand, and we cannot guarantee Shopify will import every product. Card details go to Stripe and we never see them; we keep your file confidential and use it only to fix it and reply to you.

Sources: Shopify Help Center, Using CSV files to import and export products and Importing products with a CSV file (both read Oct 25, 2026). What our checker does is described from its own documentation. Not affiliated with Shopify. Shopify can change its rules, so check the help pages if something here doesn't match what you see.