August 13, 2026
8 min read
Table of Contents
By Kokil Thapa | Last reviewed: August 2026
Managing hundreds or thousands of SKUs manually is unsustainable for any growing store. A properly structured WooCommerce bulk product import from CSV lets you create, update, and sync entire catalogs in minutes rather than days. Whether you are migrating from another platform, updating pricing across 5,000 items, or launching a new inventory feed from a supplier, getting the CSV format right prevents broken variations, missing images, and orphaned metadata. This guide covers the exact field mappings, formatting rules, and troubleshooting steps I use on production eCommerce projects.
Quick answer: WooCommerce bulk product import from CSV requires a UTF-8 encoded file with headers matching WooCommerce’s native field names (e.g.,
Type, SKU, Published). Use the built-in Product Importer at Products > All Products > Import, map columns correctly, and always run a test batch of 10–20 rows before full import to validate data integrity.How do you prepare a CSV file for WooCommerce bulk product import?
The most common point of failure in WooCommerce development is not the import tool itself but malformed source data. WooCommerce’s native importer is strict about column headers and encoding. Before attempting any WooCommerce bulk product import from CSV, your file must meet these baseline requirements:
- Encoding: UTF-8 without BOM. Files exported from Excel on Windows often include a Byte Order Mark that causes header recognition failures.
- Delimiter: Comma-separated by default. If your product descriptions contain commas, wrap those fields in double quotes.
- Headers: Must match WooCommerce’s expected field names exactly when relying on auto-mapping. Custom columns require manual mapping during import.
- ID vs SKU: Include either
ID(for updating existing products) orSKU(for creating/updating by SKU). Never leave both blank.
Required vs optional columns
For simple products, only Type, Name, and one identifier (ID or SKU) are strictly required. However, in practice, you should always include Published (set to 1 or 0), Regular price, and Categories. Omitting categories results in uncategorized products that hurt navigation and SEO. For stores using catalog management services, consistent category taxonomy in the CSV prevents post-import cleanup work.
Handling special characters and multilingual content
Nepali businesses selling traditional goods or operating bilingual stores frequently encounter encoding issues. Always save your CSV as UTF-8. In LibreOffice Calc, use “Save As” → “Text CSV (.csv)” → check “Edit filter settings” → select UTF-8. In Excel 2026, use “CSV UTF-8 (Comma delimited)”. Never copy-paste directly from a web page into Excel; invisible formatting characters will break the import parser.
What is the correct CSV format for variable and grouped products?
Variable products cause more import failures than any other product type because they require multiple rows with precise parent-child relationships. The WooCommerce bulk product import from CSV format for variables follows a strict hierarchy:
- Parent row:
Type=variable. Contains the product name, description, categories, tags, and attributes. LeaveRegular priceempty on the parent. - Variation rows:
Type=variation. Each variation references the parent viaParentcolumn (using parent SKU or ID). Includes specific attribute values, price, SKU, stock, and weight. - Attribute definition: Parent row must define attributes in
Attribute 1 name,Attribute 1 value(s)format. Variation rows reference these with matching attribute names.
<!-- Example variable product CSV structure -->
Type,SKU,Name,Published,Categories,Regular price,Attribute 1 name,Attribute 1 value(s),Parent
variable,DHAKA-TOP-001,Dhaka Topi Traditional,1,"Clothing>Men",,Color,"Red|Blue|Black",
variation,DHAKA-TOP-001-RED,,,,,,Color,Red,DHAKA-TOP-001
variation,DHAKA-TOP-001-BLU,,,,,,Color,Blue,DHAKA-TOP-001
variation,DHAKA-TOP-001-BLK,,,,,,Color,Black,DHAKA-TOP-001A common mistake is setting prices on the parent variable row. WooCommerce ignores parent-level prices for variable products; each variation must have its own Regular price. Another frequent error is inconsistent attribute naming between parent and variation rows — “Color” and “color” are treated as different attributes.
Grouped and external products
Grouped products use Type = grouped on the parent row and list child product IDs or SKUs in the Grouped products column (pipe-separated). External/affiliate products use Type = external and require External URL and Button text columns. These types cannot be mixed with variable product logic in the same row.
How do you handle images and custom meta during WooCommerce CSV import?
Images are where most WooCommerce bulk product import from CSV attempts stall. The importer accepts URLs in the Images column, not local file paths. Multiple images are pipe-separated, with the first image becoming the featured image:
Images
https://example.com/wp-content/uploads/product-front.jpg|https://example.com/wp-content/uploads/product-back.jpg|https://example.com/wp-content/uploads/product-detail.jpgOn production sites I maintain, we pre-upload all media to the server and reference absolute URLs. Relative paths fail silently. For large catalogs (2,000+ SKUs), download images to /wp-content/uploads/import-temp/ via SFTP first, then reference them by full URL to avoid timeout issues during HTTP fetching.
Custom fields and meta data
Any column prefixed with Meta: maps directly to post meta. For example, Meta: _supplier_code sets the _supplier_code meta key. This is essential for Nepal-based eCommerce stores integrating with local inventory systems or payment gateways like eSewa and Khalti that require custom order metadata. When building POS-integrated stores, supplier codes and bin locations imported via CSV prevent manual entry errors.
| Field Type | CSV Column Format | Example Value | Notes |
|---|---|---|---|
| Featured Image | Images (first URL) | https://site.com/img/main.jpg | Becomes post thumbnail |
| Gallery Images | Images (pipe-separated) | url1.jpg|url2.jpg | Order preserved |
| Custom Meta | Meta: _key_name | Meta: _bin_location → A-12 | Prefix required |
| Categories | Categories | Clothing>Men>Topi | Hierarchy via > |
| Tags | Tags | traditional|nepali|handmade | Pipe-separated |
Why does my WooCommerce CSV import fail or skip products?
Even with perfect formatting, imports fail due to server constraints and data conflicts. After debugging dozens of WooCommerce bulk product import from CSV issues on live stores, these are the recurring culprits:
- PHP memory limit: Default 128M fails above ~500 products. Increase to 512M minimum in
wp-config.php:define('WP_MEMORY_LIMIT', '512M'); - Max execution time: 30-second defaults timeout mid-import. Set
max_execution_time = 300in php.ini or via hosting panel. - Duplicate SKUs: If “Update existing products” is unchecked and a SKU exists, the row is skipped. Always check this box for updates.
- Invalid category slugs: Categories must exist or be creatable. Special characters in category names without proper escaping cause silent skips.
- Image URL timeouts: Slow external image hosts cause the importer to hang. Pre-stage images locally whenever possible.
Server configuration for large imports
On shared hosting in Nepal, default PHP configurations rarely support imports above 1,000 products. If you cannot modify php.ini, split your CSV into batches of 100–200 rows. For dedicated servers or VPS setups, configure PHP-FPM pool settings specifically for import operations. I’ve found that setting request_terminate_timeout = 600 in the FPM pool config prevents worker kills during large media-heavy imports. Stores requiring regular catalog syncs benefit from scalable architecture that separates import processing from frontend serving.
Plugin conflicts and theme overrides
Some themes and plugins hook into woocommerce_product_import_pre_insert_product_object and introduce validation that rejects valid CSV data. Temporarily switch to Storefront theme and disable non-essential plugins before blaming the importer. On legal-tech portals I’ve built that integrate WooCommerce with document management, custom meta validation hooks frequently blocked legitimate imports until whitelisted.
When should you use WP-CLI instead of the admin importer?
The admin interface works for one-time imports under 2,000 products. For recurring syncs, automated pipelines, or catalogs exceeding 5,000 SKUs, WP-CLI’s wp wc product import command is superior. It bypasses browser timeouts, logs failures to a file, and integrates with cron jobs:
## Import with WP-CLI (WooCommerce 9.x+)
wp wc product import products.csv --format=csv --update-existing=yes --allow-root
## Scheduled nightly sync via cron
0 2 * * * cd /var/www/html && wp wc product import /data/supplier-feed.csv --update-existing=yes --skip-images=yes >> /var/log/wc-import.log 2>&1WP-CLI also supports --skip-images for price/stock-only updates, dramatically reducing execution time. For stores syncing inventory from ERP systems every night, this flag alone cuts import time from 45 minutes to under 8 minutes on typical hardware.
Conclusion
Successful WooCommerce bulk product import from CSV depends entirely on data preparation and server configuration, not the import tool itself. Validate your CSV structure against WooCommerce’s schema, test with small batches, ensure UTF-8 encoding, and adjust PHP limits before attempting full imports. For variable products, respect the parent-child row hierarchy and never set prices on parent rows. When imports exceed 2,000 products or require automation, move to WP-CLI for reliability and logging.
If your store’s catalog import keeps failing despite following these steps, or you need help structuring CSV feeds for complex product types, get in touch — I regularly troubleshoot WooCommerce import issues for eCommerce clients in Nepal and internationally.
Frequently Asked Questions
Default limit is 2MB. Increase via WP All Import or server php.ini upload_max_filesize and post_max_size to handle larger catalogs safely.
Only Type, SKU, Name, and Published are strictly required. All other fields like price, description, categories, and images are optional but recommended for complete listings.
Basic mapping and test imports range Rs 15,000–30,000 (~USD 110–225). Complex variable products with custom fields typically cost Rs 40,000–70,000 (~USD 300–525) including validation.
The Published column likely contains false, 0, or is empty. Set it explicitly to true or 1 in your CSV. Also check that the post_status isn't being overridden by a plugin or theme hook during import processing.
Use separate rows for each variation sharing the same parent SKU. Include Attribute 1 name, Attribute 1 value, and Parent SKU columns. Mark the parent row Type as variable and variation rows as variation. Test with five products first before full catalog import to validate attribute linking.
Yes, map the SKU or ID field as your unique identifier. Enable Update existing products in the importer settings. Never rely on product titles for matching since they change frequently. Always backup your database before running update imports on production stores.
Images fail when URLs contain spaces, special characters, or return 403/404 errors. Ensure all image URLs are publicly accessible and properly encoded. WordPress cannot import from private S3 buckets or localhost paths. Pre-validate every image URL returns HTTP 200 before importing.
Save CSV files as UTF-8 with BOM encoding to preserve Devanagari script. Verify your database collation is utf8mb4_unicode_ci. Some spreadsheet exporters corrupt Unicode; use LibreOffice or dedicated CSV editors rather than Excel for Nepali content validation.
WP All Import Pro handles 50,000+ products reliably with chunked processing and cron scheduling. Product Import Export Suite offers better field mapping UI. The default WooCommerce importer works fine under 2,000 simple products but times out on shared hosting with larger datasets.
Custom meta fields require exact meta_key names in column headers prefixed with Meta:. For Advanced Custom Fields, use the ACF field name not the label. Third-party plugins like WP All Import provide visual drag-and-drop mapping interfaces that reduce key-name typos significantly compared to manual header editing.
Categories must use full hierarchical paths separated by greater-than symbols like Clothing > Men > Shirts. Flat category names create new top-level terms instead of nesting. Ensure parent categories exist before importing children, or enable auto-create hierarchy in your importer settings to build the tree structure correctly.
Split files into 500–1,000 product chunks. Use CLI importers like wp-cli wc product import which bypass PHP execution limits. On shared hosting, schedule imports via WP Cron during off-peak hours. Increase max_execution_time to 300 seconds minimum in php.ini if you control server configuration.
Not with default WooCommerce tools. Use WP All Import with the WooCommerce add-on or dedicated review import plugins. Map reviewer email, rating, date, and comment content carefully. Note that importing fake reviews violates platform policies; only migrate legitimate historical review data from previous systems.
Run a dry-run or preview mode showing mapped fields against sample rows. Check for missing SKUs, invalid prices, broken image URLs, and malformed dates. Validate category paths exist. Import ten products first and verify frontend display, cart functionality, and search indexing before committing the full catalog.
Malicious CSVs can inject XSS via unescaped HTML in descriptions or execute SQL through formula injection in spreadsheet cells. Sanitize all imported content using wp_kses_post. Restrict import capabilities to administrator roles only. Never accept CSV uploads from untrusted vendors without server-side validation and malware scanning.
