How to fix missing or invalid product handles in a Shopify CSV

The URL handle column (called Handle in older Shopify exports) is the product's unique identifier in a CSV. It becomes the end of the product's web address, /products/your-handle. It also tells Shopify which rows belong to the same product.

What Shopify requires

From Shopify's product CSV documentation:

• A handle can contain letters, dashes and numbers. Spaces aren't allowed.
• If the handle is blank, Shopify creates one from the product title.
• The handle is required when you update existing products, and when you add variants or extra images. Those extra rows are attached to a product by its handle.

The second point is the one that catches people. If a supplier file lists one row per variant and has no handle column, the first row of each product may import. The variant rows have nothing to attach to.

Symptoms

• Variants show up as separate products, or don't import at all.
• Extra images are missing.
• Two different products end up merged, because they produced the same handle.
• Product URLs contain odd characters or very long slugs.

Fixing handles by hand

1. Add a column called URL handle (or keep Handle if your file uses the older column names).
2. For each product, write a handle in lowercase letters, numbers and dashes, for example waxed-canvas-tote.
3. Copy that same handle onto every row of the product: each variant row and each image row.
4. Make sure no two different products share a handle.
5. When you update products that already exist, use their existing handles, which you can find in a Shopify export. Otherwise you create new products instead of updating the old ones.

Creating handles from titles safely

A handle created from the title is what Shopify itself does when the handle is blank. The common conversion steps are:

Title	Handle
Waxed Canvas Tote	waxed-canvas-tote
Café & Crème Mug	cafe-and-creme-mug
Linen Apron!	linen-apron

Watch out for two different products whose titles produce the same handle, such as "Mug!" and "Mug?". They would be merged into one product on import. Give the second one a different handle, for example mug-2.

Grouping supplier rows into products

Supplier spreadsheets usually repeat the product name on every variant row. They often have a "Parent SKU" or "Style code" column that tells you which rows belong together. To turn them into Shopify products:

1. Group rows by the parent code. If there isn't one, group them by identical product name.
2. Give each group one handle.
3. Keep the title, description, vendor and tags on the group's first row only. Shopify reads product details from the first row.

The CatalogPilot repair tool does these steps for you. It recognises parent-SKU columns, creates handles from titles, resolves clashes, and lists every handle it created in the validation report. Where it can't safely create a handle (for example, a row with no title and no handle), it reports the row instead of guessing.

Check before importing

The CSV Validator for Shopify reports invalid handles, missing handles, products whose rows are scattered through the file, and different products that would end up with the same handle.