The product CSV is the contract between your supplier file and your store. Most failed imports are not mysterious — they are one column holding the wrong kind of value.

The columns that decide whether an import works

ColumnWhat it must beWhat breaks it
HandleLowercase, stable, unique per productRepeating one handle for unrelated products; changing it after launch
TitleProduct name, same value on every variant rowBlank rows, or a different title per variant
Variant SKUUnique per variantDuplicates, or the same SKU reused after a supplier change
Variant PricePlain numberCurrency symbols, thousands separators, empty cells
Variant Inventory QtyWhole numberDecimals, text such as "in stock"
Image SrcComplete public http(s) URLLocal paths, private links, expiring URLs
StatusA value the store acceptsFree text, mixed languages, blanks

Handle: the quiet key

A handle becomes part of the product URL and groups variant rows into one product family. Generate it from the title, then check for collisions and strip anything volatile like price or stock level. Keep it stable across supplier refreshes — a new handle creates a duplicate product instead of updating the existing one.

Variants live on one product

Every row of a product family shares a Handle. Put SKU, price, inventory, and the variant-specific image on the row they belong to. Test one simple product, one two-option product, and one product with an incomplete combination before you scale.

Practical import order

  1. Save the untouched supplier file as a read-only copy.
  2. Map columns to store fields and decide which products you actually want.
  3. Normalize prices and inventory to plain numbers.
  4. Validate a 10-row sample end to end.
  5. Import the sample, check the storefront, then process the full catalog.

Open the Import Cleaner to run this mapping and validation locally.