Wix csv import format

The Wix CSV import format is one of the most confusing parts of setting up a Wix store. Unlike most platforms, Wix has two different CSV formats — V1 for Classic Stores and V3 for New Stores — and the column names and row structure differ significantly between them. Getting one column wrong means your products import with missing data or fail entirely.

This guide explains the complete Wix CSV import format including every required column, how variants work, the difference between V1 and V3, and the most common mistakes that cause import failures.

Wix V1 vs V3 — Which One Do You Need

Wix introduced a new store format in 2022. If your Wix store was created before 2022 you likely use the Classic Store format which requires V1 CSV files. Stores created after 2022 or stores that have been upgraded use the new format which requires V3 files.

The easiest way to check which version your store uses is to go to your Wix dashboard and look at Store Products. If you see a "Catalog" section in the left menu you have the new format and need V3 files. If you see "Store Products" without a Catalog section you have the classic format and need V1 files.

WixSync generates both V1 and V3 files automatically in a single download so you do not need to figure this out before converting — just try V3 first and switch to V1 if the import fails.

Wix CSV V3 Format — Required Columns

The V3 format uses these main columns:

handleId — A unique identifier for each product. All variant rows for the same product must share the same handleId. This is what groups variants together under one product.

fieldType — Either "Product" for the main product row or "Variant" for each variant. Every product needs exactly one Product row followed by one or more Variant rows.

name — The product title. Only required on the Product row, leave blank on Variant rows.

description — The full product description. HTML is supported. Only on the Product row.

productImageUrl — Product image URLs separated by semicolons. Up to 15 images. Only on the Product row.

collection — The collection or category name. Leave blank if not using collections.

sku — Stock keeping unit code. Set on Variant rows.

price — The base price. Set on the Product row.

surcharge — The price difference for this variant compared to the base price. Positive for more expensive variants, negative for cheaper ones. Set on Variant rows.

visible — TRUE or FALSE. Controls whether the product is visible in your store.

inventory — InStock, OutOfStock, or a number for tracked inventory.

productOptionName1 — The name of the first variant option, for example "Size" or "Color". Set on the Product row.

productOptionDescription1 — The available values for the first option, separated by semicolons, for example "Small;Medium;Large". Set on the Product row.

productOptionDescription1 on Variant rows — The specific value for this variant, for example "Medium".

You can have up to 3 product options using productOptionName1/2/3 and productOptionDescription1/2/3.

Wix CSV V1 Format — Key Differences

The V1 format uses similar columns but with some differences in naming and structure. The main differences are:

The handleId column works the same way.
fieldType uses "Product" and "Variant" the same way.
The price columns work the same way.
Image URLs go in a column called "productImageUrl" the same as V3.

The key difference is that V1 does not support as many product options and has stricter limits on description length and image counts.

For most migration purposes V3 is the better format to use if your store supports it.

How Variants Work in the Wix CSV Format

Understanding how variants work in the Wix CSV is essential for a successful import. Every product that has options — sizes, colors, materials — needs to be structured as one Product row followed by multiple Variant rows.

Example for a t-shirt available in Small, Medium, and Large:

Row 1: fieldType=Product, handleId=tshirt-001, name=Classic T-Shirt, price=25, productOptionName1=Size, productOptionDescription1=Small;Medium;Large

Row 2: fieldType=Variant, handleId=tshirt-001, productOptionDescription1=Small, sku=TSH-S, surcharge=0

Row 3: fieldType=Variant, handleId=tshirt-001, productOptionDescription1=Medium, sku=TSH-M, surcharge=0

Row 4: fieldType=Variant, handleId=tshirt-001, productOptionDescription1=Large, sku=TSH-L, surcharge=2

In this example the Large size costs $2 more than the base price of $25, so it has a surcharge of 2.

Simple products with no variants still need both a Product row and at least one Variant row. The Variant row for a simple product has the SKU and inventory information.

Common Wix CSV Import Errors and How to Fix Them

Error: Products import but show no descriptions

The description column is empty or the column name is spelled incorrectly. Check that your CSV has a column named exactly "description" with a lowercase d.

Error: Variants importing as separate products

The handleId values are not consistent. All variant rows for the same product must have identical handleId values. Even a small difference like an extra space will cause Wix to treat them as different products.

Error: Images not showing

Image URLs must be publicly accessible. If your images are hosted on a platform that requires login or uses authentication, Wix cannot load them. Make sure all image URLs return a direct image file when opened in a browser.

Error: Import fails with "invalid file" message

The most common cause is extra columns that Wix does not recognise. Wix is strict about the CSV format and will reject files with unknown columns. Make sure your CSV only contains the columns Wix expects.

Error: Prices showing as 0

The price column must contain a number with no currency symbols. Write 25.99 not $25.99.

Why Use WixSync Instead of Building the CSV Manually

Building a Wix-compatible CSV from scratch or converting one from another platform manually is time consuming and error prone. The column names must be exact, the row structure must be perfect, and variant grouping must be consistent.

WixSync converts Shopify and WooCommerce exports to Wix CSV format automatically, generating both V1 and V3 files in a single download. The conversion takes under two minutes and handles variants, images, prices, and all required columns correctly.

The free trial includes 3 conversions with no credit card required.

Convert your CSV now at wixsync.com or go directly to the Shopify converter at wixsync.com/converter/convert/ or the WooCommerce converter at wixsync.com/converter/woocommerce/