The Ultimate Guide to Bulk Importing Products into Wix Using a CSV File
- Wix doctor
- Jun 29
- 15 min read
(Updated 28th June 2026)
Bulk importing products with a CSV file is one of the fastest ways to build or update a Wix Stores catalogue. It can also be one of the most frustrating if your spreadsheet contains formatting errors, missing data or incorrect values.
This guide brings together everything you need to complete a successful Wix CSV import, from preparing your spreadsheet and understanding each field to resolving common upload errors. Whether you're importing products for the first time or updating an existing catalogue, each section will help you avoid the mistakes that cause imports to fail.
Follow the guide from start to finish, or use the contents below to jump straight to the topic you need.
If your CSV import has reached the point where you'd rather hand it over, that's perfectly understandable. Large product catalogues, complex variants and recurring import errors can quickly become time-consuming, even for experienced Wix users.
Wix Doctor has helped businesses import product catalogues ranging from a handful of products to many thousands, creating clean CSV files that upload successfully and match the structure required by Wix Stores. Whether you need someone to prepare your spreadsheet, resolve import errors or manage the entire process from start to finish, support is available.
For those who prefer to learn, this guide explains every stage of the import process in detail. If you'd rather save time, you can get in touch with Wix Doctor for professional assistance and get your products online sooner.
Contents:
Setting up your Wix product import CSV file
Preparing your CSV file correctly is one of the most important steps in the entire import process. A well-structured spreadsheet gives you the best chance of completing a successful upload the first time.
It can be tempting to create a CSV file from scratch, especially if your product data already exists in another spreadsheet. In most cases, that creates extra work and increases the risk of upload errors, as the column headings must match the fields expected by Wix Stores.
The simplest approach is to download the Blank Wix CSV Template directly from your Wix dashboard. Every required column is already included and named correctly, giving you a reliable foundation for your product catalogue.
Avoid changing the column headings, even if they seem unclear or unnecessary. Wix uses these headings to map your data during the import process, so even a small change can prevent products from importing correctly.
The video below shows where to find and download the blank Wix CSV template before you begin adding your products.
Wix Doctor tip: Save your spreadsheet regularly while you work. A product catalogue can represent hours of editing, and frequent saves help protect your progress.
Understanding handleId and fieldType
The first two columns in the Wix CSV template are handleId and fieldType. They are among the most important fields in the entire spreadsheet, as they tell Wix how your products are identified and organised.
Wix Doctor tip: You might notice these names don't follow normal grammar rules. They're written in a programming convention called camelCase, where the first word begins with a lowercase letter, and each following word starts with a capital letter, without spaces. This formatting is intentional and must remain exactly as it appears in the Wix template.
What is handleId?
The handleId is the unique identifier for each product in your catalogue. Think of it as a permanent reference that allows Wix to recognise which rows belong to which product.
You can use almost any combination of letters and numbers, provided each product has its own unique value. If your products already have SKUs, using the SKU as the handleId is often the simplest approach.
Every product must have a unique handleId. Duplicate values can prevent your CSV from importing correctly and make it impossible for Wix to distinguish between products.
The importance of handleId becomes much clearer in the next section, where we'll look at the relationship between products and variants.
What is fieldType?
The fieldType column tells Wix whether each row represents a Product or a Variant.
This value must be entered exactly as Product or Variant, including the correct spelling and capitalisation. Extra spaces, spelling mistakes or different wording can cause the import to fail because Wix won't recognise the value.
Although these two fields look simple, they provide the structure for your entire CSV file. Understanding how they work before adding products will save a great deal of time later in the import process.
For a more detailed explanation, read our guide: What is handleId and fieldType in Wix CSV Uploads?
Defining the difference between Product and Variant
Understanding the difference between Product and Variant is one of the biggest hurdles when creating a Wix CSV file. Once this concept clicks, the rest of the spreadsheet becomes much easier to understand.
Imagine you're selling a mug that's available in three different colours. Would you rather create three separate product listings or one product listing with three colour options? Most online stores use a single product with multiple variants because it provides a cleaner shopping experience and makes it easier for customers to choose their preferred option.
When to Use 'Product'
Use Product for every item you are listing, including those with variations. This applies to products that are only available in a single size, colour or style.
For example, if you're selling an oak dining table that's only available in one finish and one size, it should be entered as a Product. Because there are no alternative options, the entire listing only requires a single row in your CSV file.
Remember, every Product must have its own unique handleId, as explained in the previous section.
When to Use 'Variant'
Use Variant whenever a product is available with different options, such as colour, size, material or another selectable attribute.
Using the mug example, you would first create a Product row for the mug itself. You would then create three Variant rows, one for each colour. These variant rows all belong to the same parent product, so they must use the same handleId.
The shared handleId tells Wix that every variant belongs to the same product listing. Customers see one product page with multiple options instead of several duplicate listings.
Understanding how Wix reads your CSV
Your CSV file is simply a set of instructions for the Wix database.
If the spreadsheet could speak, the rows above would read something like this:
"This product is called example2. It's a mug, and it comes in three colours. Here are the three variants that belong to it."
Once you understand the relationship between Product, Variant and handleId, building even large product catalogues becomes much more straightforward.
For a more detailed explanation, read our follow-up guide: Defining Products and Variants in Wix CSV Uploads.
Adding the product name and description
The name and description fields are among the most important customer-facing elements in your CSV file. They become the title and description displayed on your product page, so they should accurately describe what you're selling and help customers understand the product.
Product names and descriptions
Every Product row should include a name and description.
Your product name should be clear and descriptive, while the description provides more detail about the product, including features, materials, dimensions or any other information that helps customers make a purchasing decision.
Because these fields are standard text fields, you have complete flexibility over the content you add.
Product rows vs Variant rows
When working with Variants, the approach changes slightly.
The Product row should contain the name and description, while the corresponding Variant rows should leave these fields blank. Each variant automatically inherits the product name and description from its parent Product, so entering the same information again serves no purpose.
Even if you add text to the Variant name or description fields, it won't be displayed on the product page. Leaving these cells empty keeps your CSV cleaner and makes it easier to manage.
Wix Doctor tip: Spend time writing accurate product names and helpful descriptions before importing your CSV. They're just as important for your customers as they are for search engines, and updating hundreds of products afterwards takes considerably longer than getting them right the first time.
Adding images to your Wix CSV when uploading products
Product images are one of the most important parts of any online store, and adding them to a Wix CSV works a little differently from adding text.
A CSV file cannot store image files. Instead, Wix imports your images using publicly accessible image URLs.
Using URLs for Images
Every product image must have its own URL that Wix can access during the import process.
The first URL listed becomes the main product image, while any additional URLs are added to the product gallery in the order they appear. This allows you to display multiple images for each product without uploading them individually after the import.
Where to get your image URLs
The simplest and most reliable approach is to upload your images to the Wix Media Manager first. Once uploaded, you can copy the URL for each image and paste it into your CSV.
You can also use images hosted on services such as Google Drive, Dropbox, iCloud or Microsoft 365, provided the images are publicly accessible. Before importing your CSV, always check that each URL opens the image directly without requiring a login or additional permissions.
Wix Doctor tip: Test one or two image URLs in a private browser window before importing your CSV. If the image loads successfully without signing in, Wix should be able to access it too.
If you're moving an existing online store to Wix, you can often reuse the image URLs from your current website instead of uploading every image again. As long as your existing store remains live during the import and the image URLs are publicly accessible, Wix can fetch each image and automatically copy it into your Wix Media Manager as part of the import.
To copy an image URL from your existing website, open the product page in your browser, right-click the image and select Copy image address or Copy image URL. The wording varies slightly between browsers, but the result is the same. Paste that URL into the productImageUrl column of your CSV.
Adding multiple images
All image URLs for a product are entered into the productImageUrl column.
If a product has multiple images, place every URL in the same cell and separate each one with a semicolon.
Example:
https://image1.jpg;https://image2.jpg;https://image3.jpgDo not add spaces before or after the semicolons, as this can prevent Wix from reading the URLs correctly.
Adding products to categories
Categories help organise your products, making them easier for customers to browse, filter and discover throughout your online store.
Before we begin, there's one small quirk in the Wix CSV template that's worth knowing. Although Wix refers to them as Categories throughout the dashboard, the corresponding column in the CSV is still called collection. Don't let the name confuse you; they refer to exactly the same thing, so whenever this guide mentions categories, you'll be entering the values into the collection column of your CSV.
Using categories is optional, so you can leave the collection column empty if you don't want to group your products. For larger catalogues, however, a clear category structure makes navigation much easier for your customers and simplifies store management.
Using existing categories
If your Wix store already has categories, enter the category name exactly as it appears in your dashboard.
Category names are case-sensitive and space-sensitive, so even a small difference can create an entirely new category. For example, Dining Tables and Dining Tables (with an accidental space at the end) will be treated as two separate categories.
Creating new categories
You can also create new categories during the import process.
If Wix doesn't find a matching category name, it automatically creates one using the text you've entered. Every product using that exact category name will then be grouped together.
Consistency is essential. Always use the same spelling, spacing and capitalisation for every product you want to appear in the same category.
Wix Doctor tip: When working with a large catalogue, create a second worksheet in your spreadsheet containing a master list of your category names. Whenever you need to assign a category, copy and paste the name from this list instead of typing it manually. It only takes one hidden space or typing error to create a duplicate category.
Adding a product to multiple categories
A single product can belong to more than one category.
To do this, enter all category names into the collection column, separating each one with a semicolon and no spaces.
Example:
Tables;Furniture;Solid OakThis product will be added to the Tables, Furniture and Solid Oak categories.
Setting the price for Products and Variants
One of the most common questions about the Wix CSV template is:
"How do I set different prices for variants?"
The answer lies in understanding the relationship between the price and surcharge columns.
Pricing standalone products
If your product doesn't have any variants, pricing is very straightforward.
Simply enter the selling price into the price column of the Product row. This becomes the price displayed on your website.
There's no need to include a currency symbol, as Wix automatically uses the currency configured in your website settings.
Pricing products with variants
Products with variants work slightly differently.
The price entered on the Product row should always be the lowest-priced variant. This becomes the base price for every variant belonging to that product.
If another variant costs more, you don't enter its full selling price. Instead, you enter the difference in the surcharge column for that Variant row.
Wix automatically adds the surcharge to the base price to calculate the final selling price.
Example
Imagine you're selling a mug in three different colours.
Variant 1 costs £15.99
Variant 2 costs £17.99
Variant 3 costs £17.99
The Product row would have a price of 15.99, as this is the lowest-priced option.
The first Variant row should have a surcharge of 0, as it already matches the base price. Even though the surcharge is zero, it's good practice to enter 0 rather than leaving the cell blank, as it clearly defines the value and keeps your data consistent.
The second and third Variant rows would each have a surcharge of 2.00.
Wix then calculates the final prices automatically:
Base price: £15.99
Variant 1: £15.99
Variant 2: £17.99
Variant 3: £17.99
Wix Doctor tip: The surcharge column only stores the difference between the base price and the variant price. Don't enter the full selling price for each variant, or your prices will be higher than expected.
Setting up options for your Variants
Defining variant options is often the most challenging part of creating a Wix CSV file, and it's also where many import errors occur. The good news is that once you understand how these fields work together, the process becomes much easier.
Variant options tell Wix what choices are available for a product, such as colour, size, material or any other attribute your customers can select on the product page.
The three option fields
Every variant option uses three columns in your CSV:
productOptionName
productOptionType
productOptionDescription
These three fields work together to create the option your customers see on the product page.
productOptionName
The productOptionName field is simply the label shown to your customers.
Examples include:
Mug Colour
Shirt Size
Material
This field only needs to be completed on the Product row. Leave it blank on every Variant row.
productOptionType
The productOptionType field tells Wix how to display the options.
There are only two accepted values:
DROP_DOWN
COLOR
DROP_DOWN displays a standard drop-down list.
COLOR displays clickable colour swatches.
Wix Doctor tip: Although Wix uses British English throughout much of its dashboard, this field must use the American spelling COLOR. Entering COLOUR or any other variation will cause the import to fail.
Like productOptionName, this field is only completed on the Product row.
productOptionDescription
This field defines every available option for the product.
For DROP_DOWN, list each option separated by a semicolon.
Example:
White;Blue;RedFor COLOR, enter the HEX colour code followed by a colon and the colour name.
Example:
#FFFFFF:White;#5271FF:Blue;#FF3131:RedEach Variant row should then contain only the matching value from the list you've already created.
For example, when using DROP_DOWN:
Variant 1 → White
Variant 2 → Blue
Variant 3 → Red
Or, when using COLOR:
The easiest way to think about it is this:
The Product row defines every available option.
Each Variant row selects one of those options.
Adding multiple option groups
Some products have more than one selectable option, such as both colour and size.
The Wix CSV template supports this by providing additional sets of option columns:
productOptionName1
productOptionType1
productOptionDescription1
followed by:
productOptionName2
productOptionType2
productOptionDescription2
and so on.
The blank Wix CSV template includes six option groups, allowing you to create products with multiple attributes.
Wix Doctor tip: Always complete Option 1 before moving to Option 2, then continue in order. Skipping option groups can make large CSV files much harder to read and maintain.
How multiple option groups work together
When you add more than one option group, Wix creates a variant for every possible combination of those options.
For example, imagine you sell printed packing tape with two options:
Length
30 m
90 m
Design Service
Add on (+ £35)
Own Artwork (Free)
Although there are only two choices in each option group, your CSV requires four Variant rows, one for each possible combination:
30 m + Add on (+ £35)
30 m + Own Artwork (Free)
90 m + Add on (+ £35)
90 m + Own Artwork (Free)
Each Variant row represents one unique combination that a customer can purchase.
Wix Doctor tip: A quick way to work out how many Variant rows you'll need is to multiply the number of choices in each option group together. Two colours and three sizes require 6 variants. Four colours and two materials require 8 variants.
Adding additional information to your product listing
The main product description won't always contain every piece of information your customers need. That's where the additionalInfoTitle and additionalInfoDescription fields come in.
These fields allow you to add extra information to your product page, such as care instructions, material specifications, size guides, delivery information or any other details that help customers make an informed purchasing decision.
Both fields are optional, so you can leave them blank if they're not required.
How the additional information fields work
additionalInfoTitle is the heading that appears on your product page.
Examples include:
Care Instructions
Size Guide
Delivery Information
Materials
Product Specifications
additionalInfoDescription contains the information displayed beneath that heading. This can include washing instructions, dimensions, product specifications, manufacturer information or any other content that's useful to your customers.
Depending on your chosen Wix product page layout, this information is displayed in its own section alongside or below the main product description.
Adding multiple information sections
The Wix CSV template supports multiple additional information sections by numbering the columns:
additionalInfoTitle1
additionalInfoDescription1
followed by:
additionalInfoTitle2
additionalInfoDescription2
and so on, up to 6 sets of fields.
Wix Doctor tip: Always begin with additionalInfoTitle1 and additionalInfoDescription1, then continue in numerical order as needed. Following the same numbering sequence throughout your CSV makes the spreadsheet much easier to read, edit and troubleshoot later.
Wrapping up
If you've followed this guide from start to finish, you should now have everything you need to build, validate and import a Wix product CSV with confidence.
Before uploading your spreadsheet, remember to export or save it as a CSV (.csv) file. Most spreadsheet applications automatically save your work in their own format, such as Microsoft Excel or Apple Numbers, so exporting to CSV is an essential final step before importing into Wix.
Large product catalogues can take time to perfect, especially when products include multiple variants, options and categories. Working methodically and checking your data as you go will help avoid the small formatting mistakes that cause most import errors.
Thank you for reading this guide. I hope it's saved you time and made the import process a little easier.
Guest author
This article was written by Wix Doctor, a specialist Wix support agency providing technical help, troubleshooting and advanced solutions for Wix websites.
If you've reached the point where you'd rather hand your CSV over to someone who's done it hundreds of times before, Wix Doctor offers professional CSV preparation, troubleshooting and bulk product import services for Wix Stores.
Whether you're importing a handful of products or migrating an entire catalogue, help is available whenever you need it.
You can also explore the rest of the Wix Doctor knowledge base for more tutorials covering CSV imports, product variants, troubleshooting and advanced Wix features.
Quick reference guide to the remaining CSV fields
The fields below are either optional or more straightforward to use, so they don't require a full section in this guide. Here's a quick overview of what each one does.
sku (Optional) – A unique product code. Many businesses use the same value as the handleId, although it can be different if required.
ribbon (Optional) – Displays a ribbon on your product listing. Examples include New, 10% Off, Best Seller or Limited Stock.
visible – A Boolean field that only accepts TRUE or FALSE. TRUE publishes the product to your store, while FALSE keeps it hidden.
discountMode (Optional) – Sets the discount type. Accepted values are PERCENT or AMOUNT.
discountValue (Optional) – Defines the discount amount. Enter the number only, without a currency symbol or percentage sign. Wix applies the correct format based on the discountMode value.
inventory (Optional) – Enter the stock quantity if you want Wix to track inventory. For products without variants, enter the value on the Product row. For products with variants, leave the Product row blank and enter the stock level for each Variant instead.
weight (Optional) – Used when setting up shipping rates based on product weight. Leave this field blank if you don't use weight-based shipping.
cost (Optional) – Records the amount you paid for the product. Wix uses this value to calculate profit within your dashboard and reports.
customTextField1 (Optional) – Creates a text field for customer personalisation. Examples include engraving instructions, gift messages or other custom requests.
customTextCharLimit1 (Optional) – Sets the maximum number of characters customers can enter into the custom text field.
customTextMandatory1 (Optional) – Accepts TRUE or FALSE. TRUE makes the personalisation field mandatory before checkout, while FALSE leaves it optional.
brand (Optional) – Stores the product's brand name. This can be useful for automations, reporting and shipping rules. It doesn't create a customer-facing brand filter, so if you want customers to browse by brand, create a dedicated category instead.
Wix Doctor tip: Before importing a large catalogue, test your CSV with one or two products first. Once you're happy with the results, import the remaining products with confidence.