Shopify product CSV import from supplier files

How Shopify's product CSV is laid out

Start from Shopify's sample product CSV or an export from your store. Shopify says the first line of your product CSV file must be the column headers as listed in its column table, and column header names are case-sensitive. If headers are missing or don't match the format, the import fails. You can't add your own columns: Collection is the only column you can add without breaking the format.

Required columns depend on the job. For new products, the only required column is Title, and URL handle is also required if you're adding variants. When updating existing products, URL handle and Title are required. Older templates may use different names such as Handle; Shopify keeps backward compatibility with older column names.

Handles, variants and options

The URL handle is the unique identifier for each product and appears in the product page URL. It can contain letters, dashes and numbers, but no spaces.

For a product with variants, the first row carries all the product fields and the first image URL. Each following row repeats the handle, leaves Title, Description, Vendor and Tags empty, and fills in that variant's details. Variants are defined by Option1 name and Option1 value (then Option2 and Option3), and a product can have up to 3 options. The SKU column holds the SKU of a variant.

Extra images work the same way: one row per image, with the handle copied into each row. Image URLs need to be publicly accessible, and Shopify allows up to 250 images per product.

Getting supplier files into that shape

1. Export your current products as a backup and template. Shopify says to have a backup of your product data before importing.
2. Write a mapping sheet: each supplier column, the Shopify column it feeds, any conversion. Decide which fields define a product and which define a variant.
3. Build handles yourself rather than trusting supplier names. One product, one handle, spelled identically on every row.
4. Normalize numbers. Price takes only the monetary value without a currency symbol. Weight value (grams) takes only the numerical value, without the unit.
5. Save as UTF-8 with LF-style linefeeds.

Test with a small batch first

Pick a few products covering the hard cases: several variants, multiple images, odd characters. Shopify tells partners doing large imports for merchants to test a small subset of changes first using a dev store. On a live store, the Status column accepts draft, meaning the product isn't yet ready to be sold, so test products can be checked before they're marked ready. This matters because imports can't be canceled once they begin, and there's no import history.

Common failure points

• Inconsistent handles. A typo or stray space in a handle turns one product into two, or splits its variants across products.
• Overwriting by accident. With Overwrite products with matching handles selected, CSV values replace existing ones, and a blank non-required column overwrites the existing value as blank. Without it, products with matching handles are ignored.
• Dropping option columns. If you update SKU or weight without Option1 name and Option1 value, a new default variant is created and existing variants are deleted.
• Changing option values. Editing them deletes existing variant IDs and creates new ones, which can break third-party tools that depend on those IDs.
• Sorting in Excel or Numbers. Shopify warns that a sorted file might cause your product's images to be lost.
• Encoding. Files not saved as UTF-8 can show unexpected characters, and curly quotes can cause an illegal quoting error.
• File size. A product CSV can't exceed 15 MB. Split larger files.
• Units that disagree. One supplier lists ounces, another millilitres, or one leaves a value out. Those need a human decision before the file is built, not a guess.

When it stops being a quick job

It gets harder when two suppliers disagree about the same products, when there are around 100 SKUs with variants, or when someone has to approve product facts before anything goes live. That's what our supplier file preparation service covers: we map two supplier files to your existing import template with your approval, hold back every product with a conflicting or missing fact for you to decide, run a ten-SKU test through your own validator or test store, and hand over the checked file. Your team runs the live import.

The service page has a downloadable synthetic example built on fictional data for a made-up home goods supplier. In it, a bottle listed as 12 US fl oz in one file and 350 ml in the other is held for a decision rather than converted, and a mug with no capacity in either file is held too.

See the supplier file preparation service