Wix to Shopify: converting a product CSV export

A Wix export is closer to Shopify's row model than most: handleId already identifies a product across its variant rows. The work is in the handle itself, the units, and one error in Shopify's own documentation.

Where the file comes from

In your Wix account go to Catalog → Store products → Products, then More actions → Export, and choose All, Filtered or Selected. Shopify names the result WixProductDownload.csv and publishes a complete field-mapping table in its migrating-from-Wix guide. Wix’s headers are camelCase: handleId, fieldType, name, description, sku, price, inventory, weight, cost, visible, and the productOptionName1 / productOptionDescription1 pairs.

One correction worth making, because following the documentation literally will cost you data: Shopify’s published table maps both productOptionName1 and productOptionName3 to Option1 Name (and both description columns to Option1 Value). That is a mistake in the table — option 3 belongs in Option3. This preset maps the three pairs to Option1, Option2 and Option3 respectively, which is what Shopify’s importer actually expects.

Pitfall 1: handleId is a handle, and Shopify is strict about handles

handleId repeats on every row of a product, which is exactly the grouping key — so grouping is pinned to it rather than left on auto-detect. But Shopify’s own guide warns about the content: a handle may contain “only letters, dashes, and numbers, but no spaces, accents, or other characters, including periods”.

Wix handles frequently contain all three. A handleId of Leather.Gloves 01 is rejected by Shopify as an invalid handle; an accented one quietly produces a URL nobody can type. The converter slugifies every handle — folding accents, lowercasing, collapsing anything that is not a letter or digit to a single dash — so Leather.Gloves 01 becomes leather-gloves-01, and the validator reports Handle … is not a valid Shopify handle for anything it cannot repair.

Pitfall 2: fieldType marks a row as Product or Variant

Wix writes fieldType: Product on the first row of a product and Variant on each subsequent one, leaving the product-level cells (name, description, image, collection) blank on the variant rows. Shopify uses exactly the same convention, which is why this export converts so cleanly.

What breaks is doing it by hand: copy the name down onto the variant rows “to be safe” and Shopify treats later rows as product data too. The converter writes product-scope columns only on a product’s first output row and warns with A variant row carries a Title when it finds one further down, because that is usually the symptom of a filled-down spreadsheet.

Pitfall 3: weight is kilograms, Shopify stores integer grams

Shopify’s mapping table is explicit: “Convert kilograms to grams by multiplying the values by 1000.” Wix exports 0.12 for a 120 g beanie. Import that into Weight value (grams) unconverted and Shopify stores a weight of nought grams, because the column takes an integer with no decimals — your carrier-calculated shipping then quotes for an empty parcel.

The preset declares the source unit as kg, so 0.12 becomes 120 and Weight unit for display is set separately. The validator rejects any non-integer that reaches the grams column with Weight … is not an integer number of grams.

Pitfall 4: every option a product declares needs a value on every variant

Wix lets a variant row leave an option cell blank. Shopify does not: once a product declares Option2 name: Colour, every variant row of that product must carry a colour. A blank one either produces a duplicate combination — the Validation failed: options are not unique rejection — or a variant whose option is empty, and Shopify’s guide lists “Product variants failed to import” as a known outcome, noting that “if a product is missing a variant option, then it won’t be imported successfully”.

The validator catches this before the upload: Option “Colour” has no value on this variant, naming the row. The bundled Wix sample contains exactly one such row so you can see the report.

Pitfall 5: prices, and the surcharge column that is not a price

price is the variant price and cost is your cost — Shopify’s table maps the latter to Cost per item, which is margin reporting only and is never shown to customers. European Wix stores often write 34,00; Shopify needs 34.00, and the converter normalises it.

Do not map surcharge to anything. It is a per-variant price modifier, not a price, and Shopify has no equivalent concept — the variant price has to be absolute. If your file uses surcharges, add them into price per row before importing. discountMode and discountValue are dropped for the same reason: Shopify models that with Compare-at price plus the real price, not with a rule.

What the preset maps

handleId → URL handle, name → Title, description → Description, brand → Vendor, visible → Published on online store, sku → SKU, price → Price, cost → Cost per item, inventory → Inventory quantity, weight → Weight value (grams) with the kg conversion, and the three productOptionName/productOptionDescription pairs → Option1–3.

Product image URL is left unmapped on purpose: Shopify’s published table does not include an image row, so there is no documented Wix header to trust. Open your file, find the image column, and map it in step 3 — if it holds several URLs in one cell, choose the split image list formula and the extra image rows are generated. collection, ribbon and inventory-policy columns have no product-CSV home either; collections are built in the Shopify admin after import.

Before you upload to Shopify

• Import into a development store or a draft-status batch first. Set the default status to draft in the tool and nothing goes live by accident.
• Shopify caps a product CSV at 15 MB. Bigger catalogues are split into numbered parts, and a product is never split across two files.
• Overwriting existing products by handle is destructive: a blank cell can erase data that is currently there. Export your live products first if you are updating rather than creating.

Full column contract: the Shopify product CSV format, column by column. Nexum Gate is not affiliated with Shopify Inc.