LitExtension Blog
  • Ecommerce Platforms
    • Shopify
    • WooCommerce
    • Magento (Adobe Commerce)
    • Wix
    • Other Platforms
  • eCommerce Migration
    • Shopify Migration
    • WooCommerce Migration
    • Magento Migration
    • Other Migrations
  • Store Growth
  • LitExtension
    • LitExtension Updates
    • Case Study
No Result
View All Result
VISIT LITEXTENSION
LitExtension Blog
  • Ecommerce Platforms
    • Shopify
    • WooCommerce
    • Magento (Adobe Commerce)
    • Wix
    • Other Platforms
  • eCommerce Migration
    • Shopify Migration
    • WooCommerce Migration
    • Magento Migration
    • Other Migrations
  • Store Growth
  • LitExtension
    • LitExtension Updates
    • Case Study
No Result
View All Result
VISIT LITEXTENSION
LitExtension Blog
No Result
View All Result

WooCommerce CSV Import: Format, Steps & Troubleshooting

by Kristen Quach
Nov, 2026
in WooCommerce, Platform Tutorials

WooCommerce CSV import is a convenient way to add or update products without entering each item manually. However, even small formatting errors can result in missing images, incorrect variations, or duplicate products.

The good news is that the process is straightforward once you understand the CSV format WooCommerce requires! In this guide, we’ll explain how to structure your product CSV and walk you through importing products, variations, images, and custom metadata.


WooCommerce CSV Import Format: What You Need to Know

For a smooth WooCommerce CSV import, your file needs to follow the specific structure that WooCommerce’s built-in product importer expects. Correct encoding, column names, value formats, and identifiers help reduce import errors, but you should still review the column mapping and import settings before proceeding.

WooCommerce CSV import file requirements

Before importing, make sure your CSV follows these basic formatting rules:

  • Use UTF-8 encoding. WooCommerce recommends saving or exporting the file as a UTF-8 CSV to avoid character and encoding issues.
  • Use 1 and 0 for Boolean fields. For example, Is featured? uses 1 for true and 0 for false. Published controls product status: 1 = published, 0 = private, -1 = draft, and 2 = pending review.
  • Separate multiple values with commas. For example, multiple categories or tags can be entered as comma-separated values. If a single value contains a comma, wrap it in double quotation marks or escape the comma with a backslash, such as Places\, People\, Cities.
  • Use > for taxonomy hierarchies. For example, Clothing > T-Shirts represents a child category under Clothing.
  • Distinguish product IDs from product references. In the ID column, enter the numeric ID, such as 100. In reference columns such as Parent, use id:100 for an existing product ID or SKU101 for a SKU.
  • Keep the column headers consistent with WooCommerce’s schema. WooCommerce automatically maps recognized column names during import; unrecognized columns are not imported by default unless they are mapped appropriately.
Important: You cannot assign a specific WordPress product ID to a brand-new product through the CSV. If the ID does not already exist, WooCommerce assigns the next available ID.

Important WooCommerce CSV fields

You don’t need every available column for every WooCommerce CSV import. The fields you need depend on the product data you’re bringing into WooCommerce. Below are some of the most important ones:

CSV field

What it controls

Example

ID

Identifies an existing product for updates

100

Type

Defines the product type

simple, variable, variation

SKU

Product’s unique identifier

TSHIRT-001

Name

Product name

Blue Cotton T-Shirt

Published

Product status

1

Regular price

Regular selling price

24.99

Sale price

Discounted price

19.99

Categories

Product categories

Clothing, Clothing > T-Shirts

Tags

Product tags

cotton, summer

Images

Product images

https://example.com/tshirt.jpg

Parent

Links a variation to its parent product

TSHIRT-001

Attribute 1 name

Attribute name

Size

Attribute 1 value(s)

Available attribute values

S, M, L

Attribute 1 visible

Whether the attribute is displayed

1

Attribute 1 global

Whether the attribute is a global attribute

1

These fields come from WooCommerce’s current built-in Product CSV Import Schema. The schema also includes fields for descriptions, inventory, shipping, downloads, upsells, cross-sells, external products, and other product properties.

For variable products, the Parent and Attribute fields are particularly important because WooCommerce uses them to establish the relationship between the parent product and its variations. We’ll cover this structure in more detail later in the guide.

Custom fields and metadata

In addition, WooCommerce also supports importing product metadata through CSV. To import a custom metadata field, add the meta: prefix to the column header. For example:

meta:product_depth

This tells WooCommerce to treat the column as product metadata rather than a standard product field. Unrecognized columns without the appropriate mapping are not imported by default. The built-in importer supports plain-text custom metadata; serialized data and JSON are not supported by the standard CSV schema.


WooCommerce CSV Import: How to Import Important Fields & Data Using CSV

Once your CSV follows WooCommerce’s required format, you can run a WooCommerce CSV import to add or update product data in bulk. The overall workflow is similar for different types of data, but products, variations, images, and custom metadata require different CSV structures.

Follow the relevant steps below based on what you want to import.

1. Importing products

For standard products, you can import fields such as product names, SKUs, prices, categories, stock, and descriptions through WooCommerce’s built-in CSV importer.

Step 1: Prepare your product CSV

First, create your CSV with the product data you want to import and use WooCommerce’s supported column headers, such as Name, SKU, Regular price, Sale price, Categories, Tags, and Images. Save the file as a UTF-8 CSV. If you are updating existing products, include their product IDs or SKUs so WooCommerce can match the rows to the products in your store.

Step 2: Upload the CSV and map your columns

In your WordPress dashboard, go to Products > All Products and click Import at the top of the page.

woocommerce-csv-products
Click “Import” to upload your CSV.

On the Upload CSV file screen, click Choose File, select your CSV, and click Continue. WooCommerce will take you to the Column mapping screen and automatically match recognized CSV headers to product fields. Review the mappings and use the dropdown beside any column to select the correct field or Do not import if you want to skip it.

Step 3: Run the import and check your products

Once the mappings are correct, click Run the importer. Wait for WooCommerce to finish processing the CSV without refreshing or leaving the page. When the import is complete, open several products and check important fields such as SKUs, prices, categories, stock, and descriptions.

Updating existing products

If you want to update rather than create products, select Update existing products on the upload screen before clicking Continue. WooCommerce matches the rows in your CSV to existing products by ID or SKU. In WooCommerce 11.2 and later, a mapped GTIN, UPC, EAN, or ISBN column is also used, but only when both ID and SKU are empty. Rows that do not match an existing product are skipped, except new variation rows that WooCommerce can create under an existing parent product.

2. Importing variable products and variations

Unlike simple products, variable products need a different CSV structure because the file must define the parent product and its individual variations.

Step 1: Set up the parent and variation rows in your CSV

First, create one row for the parent product and one row for each variation.

Then, set the parent product’s Type to variable and each variation’s Type to variation. Give the parent and each variation a SKU and make sure every variation has a unique SKU. In each variation row, use the Parent column to connect it to the parent product using the parent SKU or ID.

Step 2: Add the attributes and variation values

Now, use columns such as Attribute 1 name, Attribute 1 value(s), Attribute 1 visible, and Attribute 1 global to define the attributes. The parent row should contain all available values, while each variation row should contain the value assigned to that variation.

For example, a T-shirt with Small and Medium variations can use this structure:

Type

SKU

Parent

Regular price

Attribute 1 name

Attribute 1 value(s)

Attribute 1 visible

Attribute 1 global

variable

tshirt

(leave empty)

(leave empty)

Size

S, M

1

0

variation

tshirt-s

tshirt

24.99

Size

S

1

0

variation

tshirt-m

tshirt

24.99

Size

M

1

0

For a local product attribute, set Attribute 1 global to 0. Use 1 when the attribute is a global attribute already configured in the store. Also, add a Regular price to every variation row, since variations without a price can’t be purchased.

Step 3: Import the CSV through the product importer

Go to Products > All Products > Import, click Choose File, select the CSV, and click Continue. On the Column mapping screen, check that the Type, SKU, Parent, and attribute columns are mapped correctly. Then click Run the importer and wait for the process to finish.

Step 4: Verify the variable product

Last but not least, open the imported product and check that WooCommerce has created the parent as a variable product and attached the expected variations to it. Check the variation attributes, SKUs, prices, and stock individually.

If you are converting an existing simple product: WooCommerce 11.1 introduced a single-import workflow for this case when the parent product row appears before its variation rows. You select Update existing products during the import, and WooCommerce updates the existing parent and creates the new variations in the same import. For this to work, each variation row needs to:

  • Leave the ID column empty.
  • Set Type to variation.
  • Have a unique SKU (or, in WooCommerce 11.2 and later, a usable GTIN).
  • Use the parent’s SKU or id:123 in the Parent column, with attribute names and values that match the parent row.

Before you start, create a backup or test the import on a staging site. After the import, check the product’s Variations tab.

If you cannot guarantee the row order, or you are using a version earlier than 11.1, WooCommerce recommends using two imports instead. First, import the parent row with Update existing products selected to change it to a variable product and add its attributes. Then, import only the variation rows with Update existing products unselected.

3. Importing product images

Here’s the great news: You can add product images through the Images column in the same product CSV, so images don’t need a separate WooCommerce CSV import. WooCommerce supports images that are already in the Media Library as well as directly accessible external image URLs.

Step 1: Add your image references to the CSV

In the Images column, enter the direct URL of an online image or the filename of an image that is already available in your Media Library.

Separate multiple image URLs or filenames for one product with commas. The first image is used as the featured image; meanwhile, additional images are added to the product gallery.

woocommerce-csv-using-external-images
Enter the direct URL of an online image in the “Images” column.

Step 2: Check the image URLs before importing

For external images, make sure the URL points directly to an accessible image. WooCommerce downloads accessible external images into the Media Library during the import. However, some hosts block these requests, require you to sign in, or return a web page instead of the image file (for example, a file-sharing link that opens a preview page). In that case, upload the image to your Media Library or use a direct image URL.

Step 3: Upload and import the CSV

Go to Products > All Products > Import, then click Choose File and select your CSV. On the Column mapping screen, make sure the Images column is mapped to the image field. Then, just like with other import processes, click Run the importer and wait for the import to finish.

Once done, open several imported products and confirm that the featured image and gallery images appear correctly. Note that WooCommerce’s core CSV importer cannot add, edit, or update product image alt text through the CSV.

4. Importing custom product data

What if your products contain custom metadata that is not covered by WooCommerce’s standard product fields? In that case, you can import it using the meta: prefix.

Step 1: Add the custom metadata to your CSV

First, identify the metadata key used by your custom product field and add it to the CSV header with meta: in front of it.

For example, if the metadata key is product_depth, use meta:product_depth as the column header. Enter the corresponding value for each product in that column.

Step 2: Upload the CSV and map the metadata column

Go to Products > All Products > Import, click Choose File and upload your CSV. On the Column mapping screen, WooCommerce can recognize meta: columns as product metadata. If the column is not mapped automatically, open its dropdown and select Import as meta.

After checking the mapping, click Run the importer and wait for the process to finish. Then check the affected products to confirm that the custom metadata was imported correctly.

Keep in mind that WooCommerce’s core importer only handles fields supported by its product CSV schema and recognized product metadata. If the data comes from a third-party extension and requires extension-specific fields, check that extension’s import documentation before proceeding.


Need Help With Your WooCommerce CSV Import?

WooCommerce’s built-in importer works well for product CSVs that follow its required format. But a WooCommerce CSV import gets harder when your files come from another platform with different column names, product relationships, or data structures. The core importer also doesn’t handle customers or orders.

LitExtension’s CSV to WooCommerce migration lets you move products (with categories, variations, attributes, and images), customers, orders, coupons, and more from your files. You can choose between two options:

  • Automated Migration: Upload your files, run a free demo, then launch the full migration yourself.
  • All-in-One Migration Service: Our team prepares and maps your files, handles the migration, and checks the results before delivery.

If your old store is still live on one of 140+ supported platforms, LitExtension’s Automated Migration Tool can transfer the data directly, with no CSV files to prepare.

Move Your CSV Data to WooCommerce Automatically

LitExtension Automated Migration Tool transfers products, customers, and orders from your CSV files to WooCommerce. Try a free demo before the full migration.

START FREE DEMO

LitExtension Automated Migration Tool Demo

Troubleshooting WooCommerce CSV Import Issues

Even a properly formatted file can hit snags during a WooCommerce CSV import. Here are the errors that come up most often, and what actually fixes them.

1. WooCommerce cannot upload or process the CSV

A CSV may fail before the import starts because of an invalid file format, server restrictions, or a file that is too large for the server to process. WooCommerce recommends using a UTF-8 CSV and splitting large files into smaller batches when necessary.

How to fix it:

  • Make sure the file is saved as a UTF-8 CSV with the .csv extension.
  • If WordPress displays “Sorry, this file type is not permitted for security reasons,” upload the CSV to the site’s uploads directory through SFTP or the hosting file manager. Then use Show advanced options in the importer to enter the server file path.

For large files, split the CSV into smaller batches and import them separately. If the problem continues, ask your hosting provider to check allowed file types, upload, memory, and processing limits.

2. CSV data is imported into the wrong field or not imported

WooCommerce automatically maps recognized CSV headers, but columns that do not match the product CSV schema are not imported by default. Formatting also affects how values are interpreted: use numeric values in the ID column, and add the id: prefix when referencing a product ID in columns such as Parent.

How to fix it:

  • On the Column mapping screen, review the mapping for every column before clicking Run the importer. Select Do not import for columns you do not need.
  • Check that your headers match WooCommerce’s supported schema.
  • Use the correct format for special values, such as 1/0 for Boolean fields and id:100 when referencing an existing product ID.

For custom metadata, use the meta: prefix, such as meta:product_depth, and map it to Import as meta if necessary.

3. Variations or their attributes are not imported correctly

Variation data depends on several CSV fields working together. If the Type, Parent, SKU, or attribute values are inconsistent, WooCommerce may skip the variation or fail to associate it with the correct parent product.

How to fix it:

  • Set the parent product’s Type to variable and each variation’s Type to variation. Give every variation a unique SKU.
  • Check that Parent contains the correct parent SKU or ID.
  • Make sure the attribute name and values in the variation rows match those defined for the parent.

When converting an existing simple product using WooCommerce 11.1’s single-import workflow, make sure the parent row appears before its variation rows and the ID column of each variation row is empty.

4. Images are missing or duplicated after import

As mentioned earlier, WooCommerce can import images from direct external URLs or reference images already available in the Media Library. Still, problems can occur when an image URL is inaccessible or returns a web page instead of the image file, or when the same image is referenced by slightly different URLs.

How to fix it:

  • Open external image URLs directly in a browser to confirm that they point to the actual image.
  • Check that the Images values are correctly formatted.
  • Use the exact same URL for an image across imports, since WooCommerce reuses images it has already imported from that URL. Or use the filename of an image that’s already in your Media Library.
  • Test a small number of images before importing a large catalog.

Again, please keep in mind that the core WooCommerce importer does not add or update image alt text through CSV.

5. Products are skipped during import

Check the import log to identify the affected rows and their reported errors.

  • If a SKU already exists, select Update existing products when you intend to update that product.
  • For standard product updates, confirm that each row’s ID or SKU matches an existing product.
  • If products were imported but seem missing, check their Published values and product status.

Correct the affected rows and test a small batch before retrying the full file.


Best Practices for WooCommerce CSV Import

Most of the issues above are avoidable, not just fixable after the fact. A few habits go a long way toward making a WooCommerce CSV import predictable instead of a gamble:

  • Back up your store before importing. Keep a current backup of your database and site files so you can restore the store if needed, or test the import on a staging site first. A product CSV export is useful for reference, but it does not replace a full backup.
  • Test with a small batch first. Import 5–10 rows before running the full file. This surfaces mapping or formatting issues while they’re still easy to fix, rather than after thousands of rows have already gone through.
  • Save your file as UTF-8 before every import. Recheck the saved CSV after editing, as spreadsheet applications can change its encoding or formatting.
  • Use consistent IDs or SKUs for update imports. Confirm that these identifiers match the existing products and are mapped correctly, then select Update existing products before running the importer.
  • Review the mapping screen manually, even when the auto-match looks right. A silently wrong mapping produces no error – just incorrect data sitting in the right-looking place.
  • Spot-check after every import, not just the first one. Open a handful of products – ideally including at least one variable product – and confirm images, pricing, stock, and variations all look correct.
  • Keep source files organized by import date and entity type. If you ever need to re-run or partially undo an import, having the exact file you used on hand saves significant time.
  • For recurring imports, standardize your export template once. A consistent column structure in your source system means less remapping each time you run the process.

None of these steps takes long individually, but skipping them is exactly how a “successful” import ends up needing a second pass or a manual cleanup a few days later.


WooCommerce CSV Import – FAQs

Can I import a CSV file directly into WooCommerce?

Yes. The built-in Product CSV Importer handles WooCommerce CSV import for products through Products > All Products > Import, so you can add or update products in bulk. It does not import customers or orders. To move customer data, see our guide on how to import WooCommerce customers.

What format should a WooCommerce CSV file be?

Save your file as UTF-8 CSV using WooCommerce’s supported column headers. Export an existing product, or download WooCommerce’s sample product CSV from GitHub, to get a compatible starting template. Use numeric IDs in the ID column and the id: prefix for ID references in columns such as Parent.

Can I import product images with a WooCommerce CSV?

Yes. Use the Images column with directly accessible image URLs or filenames from your Media Library. Separate multiple images with commas; the first becomes the featured image.

How do I update existing WooCommerce products with a CSV?

Include matching product IDs or SKUs, select Update existing products when uploading your CSV, review the column mapping, and run the importer.

Can I import variable products with a CSV?

Yes. Use a variable parent row and separate variation rows, linked through Parent. Give each variation a unique SKU and matching attribute values. If variations are missing, check the import log and parent references before retrying.


Final Words

A successful WooCommerce CSV import starts with a file that matches your products and the changes you want to make. Use the correct column structure, check IDs or SKUs when updating existing products, and test a small batch before importing your full catalog.

After the import, review your product details, variations, and images, and check the import log for any failed or skipped rows. These checks help you catch problems early and build a reliable WooCommerce CSV import workflow for future product updates.

Let Our Experts Handle Your CSV Migration!

With the All-in-One Migration Service, our experts prepare and map your files, run the migration, and check every result for you.

BOOK FREE CONSULTATION

All-in-One Migration Service
Previous Post

Import Sample Data in Magento 2 – The Comprehensive Guide in 2026

Next Post

WooCommerce Update 2026: Everything You MUST Know (Step-by-step)

Kristen Quach

Kristen Quach

Meet Kristen, a passionate advocate for eCommerce success and Content Team Leader at LitExtension. Her expertise in the dynamic world of eCommerce, particularly in WooCommerce, allows her to provide valuable guidance and practical strategies that help businesses thrive in the digital age.

Table of Contents
  1. WooCommerce CSV Import Format: What You Need to Know
    1. WooCommerce CSV import file requirements
    2. Important WooCommerce CSV fields
    3. Custom fields and metadata
  2. WooCommerce CSV Import: How to Import Important Fields & Data Using CSV
    1. 1. Importing products
    2. 2. Importing variable products and variations
    3. 3. Importing product images
    4. 4. Importing custom product data
  3. Need Help With Your WooCommerce CSV Import?
  4. Troubleshooting WooCommerce CSV Import Issues
    1. 1. WooCommerce cannot upload or process the CSV
    2. 2. CSV data is imported into the wrong field or not imported
    3. 3. Variations or their attributes are not imported correctly
    4. 4. Images are missing or duplicated after import
    5. 5. Products are skipped during import
  5. Best Practices for WooCommerce CSV Import
  6. WooCommerce CSV Import – FAQs
  7. Final Words
woocommerce-migration-litextension

Popular eCommerce Migration

  1. Shopify Migration
  2. WooCommerce Migration
  3. Magento Migration
  4. BigCommerce Migration
  5. PrestaShop Migration

Best Ecommerce Platforms

  1. Shopify Review
  2. WooCommerce Review
  3. Wix Ecommerce Review
  4. BigCommerce Review
  5. Best Ecommerce Platforms

 

Popular Migration Pairs

  • Wix to Shopify
  • Magento to Shopify
  • BigCommerce to Shopify
  • WooCommerce to Shopify
  • Shopify to WooCommerce

Company

  • About LitExtension
  • Success Stories
  • Sitemap
  • Disclosures
  • Our Author
  • Contact Us

DMCA.com Protection Status

  • All the Basics to Build eCommerce Website
  • Disclosures
  • LitExtension Authors
  • LitExtension Blog – Shopping Cart Migration Expert & eCommerce News
  • LitExtension Blog Sitemap
  • LitExtension Methodology

© 2011 - 2024 LitExtension.com All Rights Reserved.

No Result
View All Result
  • Ecommerce Platforms
    • Shopify
    • WooCommerce
    • Magento (Adobe Commerce)
    • Wix
    • Other Platforms
  • eCommerce Migration
    • Shopify Migration
    • WooCommerce Migration
    • Magento Migration
    • Other Migrations
  • Store Growth
  • Ecommerce News
    • News & Events
    • Case Studies
VISIT LITEXTENSION

© 2011 - 2024 LitExtension.com All Rights Reserved.