Thoroughly master WooCommerce product import: the ultimate guide from CSV files to custom products

Why do we need a professional WooCommerce product import tool?

As the scale of online stores grows, it's becoming increasingly impractical to manually add products one by one. Whether it's migrating existing store data, updating inventory prices in bulk, or obtaining product lists from suppliers, efficient data import functionality is crucial. The basic import tools provided by WooCommerce itself are sufficient for simple scenarios, but when dealing with complex product types, custom fields, and large amounts of data, developers need to master more systematic and powerful methods.

Using the correct tools and methods for product import not only saves a lot of time, but also minimizes human errors and ensures data consistency. From standard simple products, variable products, to advanced product types such as subscriptions and bundled sales, a well-structured import process is the cornerstone of e-commerce operation automation. This article will explore in depth the entire process from preparing standard CSV files to processing custom products through programming methods.

Prepare a standard CSV file for bulk import

WooCommerce has a built-in function for importing products via CSV files, which is the most commonly used and straightforward way of performing bulk operations. The key is to prepare a CSV file that meets WooCommerce's expected format.

Recommended Reading WooCommerce e-commerce website development: Build your online store from scratch。

Understand the core product data columns

A basic CSV file import must include some key columns. Among them,IDandTypeThe list is the most important thing.IDIt is used to match existing products to implement updates. If left blank, a new product will be created.TypeIt defines the product types, such assimple(Simple products)variable(Variable products),grouped(Grouped products) and so on. Other basic columns includeSKU(Inventory units),Name(Product name),Published（Publication status, 1 for published）Description(Description),Regular price(Regular price) andStock(Inventory quantity).

UltaHost WordPress Hosting

30-day refund guarantee, unlimited bandwidth and database usage, free DDoS protection; purchase for 3 years and get a discount of 50%.

access page

For variable products, the import process is divided into two steps: first, import the parent product, and then import its child variants. The parent productTypelisted asvariable, sub-variantsTypelisted asvariationAnd throughParentEstablish the association by listing the SKUs of the specified parent products.

Handle classification, tagging, and images

The import of categories and tags requires a specific format. For product categories, you can do it in the following way:CategoriesThe format used in the column is “parent category > child category”, with multiple categories separated by English semicolons. For example: “Clothing > Shirts; Summer New Arrivals”. The tags are placed within symbols.TagsThe columns are separated by English commas.

The import of product images is relatively flexible. It can be done throughImagesList the URLs of the specified images, separating multiple URLs with English commas. The first URL will be used as the main image. When importing, WooCommerce will attempt to download and save these images to the media library. Another method is to upload the images to a specific directory on the server via FTP in advance, and then reference the relative path in the CSV file.

An example of a CSV file for a standard simple product is as follows:

Recommended Reading WooCommerce Tutorial: A Complete Guide to Building a Professional E-commerce Website from Scratch。

ID,Type,SKU,Name,Published,Description,Regular price,Stock,Categories,Images
,simple,T-SHIRT-SM,纯棉简约T恤,1,这是一件舒适的纯棉T恤。,29.99,100,服饰 > 上衣,https://example.com/tshirt.jpg

Use WP CLI to automate advanced imports

For developers and advanced users, the WordPress command-line toolWP-CLIIt provides a more powerful, scriptable import method. It is particularly suitable for integration into deployment processes or for handling large-scale data sets.

A basic passwp-cliThe command to import CSV is as follows:

wp import products.csv --authors=skip

But the more common approach is to use custom scripts. We can write a PHP script that utilizesWP-CLIThewp eval-fileThe script is executed using the command. The core of the script is to use it.wc_get_product_objectThe function creates a product object and sets its properties.

hosting.com Shared Hosting

High performance with AMD EPYC CPUs, NVMe SSD storage and LiteSpeed, 24/7, 24x7 expert in-house support, advanced security measures including SSL, brute force, malware and DDoS protection, savings of up to 73%

access page

Below is an example of a PHP script used to create a simple product programmatically:

<?php
// 读取CSV数据
$csvFile = 'products.csv';
if (($handle = fopen($csvFile, 'r')) !== FALSE) {
    $header = fgetcsv($handle); // 读取标题行
    while (($data = fgetcsv($handle)) !== FALSE) {
        $productData = array_combine($header, $data);

// 创建产品对象
        $product = new WC_Product_Simple();
        $product->set_name($productData['Name']);
        $product->set_sku($productData['SKU']);
        $product->set_regular_price($productData['Regular price']);
        $product->set_description($productData['Description']);
        $product->set_stock_quantity($productData['Stock']);
        $product->set_status($productData['Published'] == 1 ? 'publish' : 'draft');

// 处理分类
        $categoryNames = explode(';', $productData['Categories']);
        $categoryIds = [];
        foreach ($categoryNames as $catName) {
            $term = term_exists(trim($catName), 'product_cat');
            if (!$term) {
                $term = wp_insert_term(trim($catName), 'product_cat');
            }
            if (!is_wp_error($term)) {
                $categoryIds[] = (int)$term['term_id'];
            }
        }
        $product->set_category_ids($categoryIds);

$product->save();
        echo "产品已创建/更新: " . $productData['Name'] . " (ID: " . $product->get_id() . ")n";
    }
    fclose($handle);
}
?>

Save the above script asimport_products.phpAfter that, you can do it by issuing a command.wp eval-file import_products.phpExecute.

Use WP CLI to handle complex associations

WP-CLIThe strength of this lies in handling complex logic. For example, when importing variable products and their attributes, you can first create global attributes, then assign the attributes to the products and generate variants. By writing scripts, you can precisely control the error handling and logging for each step, achieving a fully automated import pipeline. For scenarios that require synchronization with external APIs (such as ERP or supplier systems), this can be combined with other tools to ensure data accuracy and consistency across different systems.WP-CLIThe use of scheduled tasks (Cron Job) is the most ideal solution.

Programming to handle custom products and metadata

When the standard CSV columns cannot meet the requirements, such as the need to import associated custom fields, product types created by third-party plug-ins (such as reservation products), or complex metadata, it is necessary to use programming methods.

Create and update custom field products

All standard data of WooCommerce products (such as price and inventory) and custom data (added via ACF or other methods) are ultimately stored as meta data (Post Meta). The core of the programming import is to use it correctly.set_A series of methods andupdate_post_metaFunction.

Suppose we have a name calledcustom_batch_numberThe custom field, the following code shows how to set it when creating a product:

InterServer Shared Hosting

Shared hosting $2.50 USD per month , first month $0.1 USD promo code tryinterserver, 461 cloud apps scripts, one click install.

access page

// 假设 $product 是一个 WC_Product 对象
$product->set_name('高级定制产品');
$product->set_regular_price(99.99);
$product->save(); // 必须先保存产品以获得ID

// 更新自定义字段（产品元数据）
$product_id = $product->get_id();
update_post_meta($product_id, 'custom_batch_number', 'BATCH-2026-001');
update_post_meta($product_id, '_custom_field', 'value'); // 下划线开头表示隐藏的元数据

It should be noted that some third-party plug-ins define their own product type classes. When creating such products, you should use the corresponding classes, for example,new WC_Product_Booking()And call the specific method provided by the plug-in.

Use WooCommerce hooks to extend the import function

In order to inject custom logic during the import process, WooCommerce provides a large number of hooks. The two key action hooks arewoocommerce_new_productandwoocommerce_update_productThey are triggered respectively after the creation and update of the product.

For example, after importing a product, we can automatically assign it an internal review status:

add_action('woocommerce_new_product', 'my_post_import_actions', 10, 2);
add_action('woocommerce_update_product', 'my_post_import_actions', 10, 2);

function my_post_import_actions($product_id, $product) {
    // 自动为所有新导入的产品添加“待审核”标记
    update_post_meta($product_id, '_internal_review_status', 'pending');

// 或者根据特定条件进行处理
    if (strpos($product->get_sku(), 'PREMIUM') !== false) {
        wp_set_object_terms($product_id, 'premium', 'product_tag', true);
    }
}

In addition, the filter hookswoocommerce_product_import_pre_insert_product_objectIt's also extremely useful. It allows us to modify the data of a product object before it's inserted into the database, which is suitable for unifying the formatting of prices, converting units of measurement, or verifying data compliance.

summarize

The import of WooCommerce products is a skill that ranges from simple to complex and involves multiple levels. Mastering standard CSV import is the foundation, which is suitable for most bulk update and migration scenarios. When faced with repetitive tasks or the need to integrate with development workflows,WP-CLIThe command-line automation demonstrates its power. For highly customized stores involving custom fields, third-party plugin data, or complex business logic, programming methods combined with WooCommerce hooks provide ultimate flexibility and control. Successful import strategies often use a combination of these tools: using CSV to handle daily batch operations, and using scripts to address complex and customized needs. The key is to deeply understand the data structure of WooCommerce and always make a complete backup of the existing data before performing any operations.

FAQ Frequently Asked Questions

How to handle special characters and encoding issues in CSV files

Ensure that the CSV file is saved using UTF-8 encoding, which is the only encoding fully supported by the official WooCommerce importer. If the data contains special characters such as commas, quotes, or line breaks, you must enclose the entire field value in double quotes in English.

For example, when there are commas in the description, it should be written as“这是一件优质，舒适的产品”It is recommended to check in a text editor and ensure that all quotation marks in all fields appear in pairs. This is a crucial step to avoid import errors.

When importing variable products, if the attributes don't display or the variant creation fails, what should I do?

This is usually a CSV format or import order issue. First, make sure that you have correctly set the global attributes. When importing the parent product,Type: variableWhen that happens, it is necessary to…Attribute 1 nameandAttribute 1 value(s)Define attributes in the column, for example颜色and红色,蓝色。

Secondly, import the variant (Type: variationWhen doing so, it is necessary to proceed through the following steps:ParentAccurately quote the SKU of the parent product and specify it in the description.Attribute: 颜色In such columns, the specific attribute values of the variant are specified (such as红色Finally, after the import is completed, you need to go to the “Variants” tab of the product and click on “Create Variant” or “Save Changes”. Only then will the system generate all possible variant combinations based on the attributes.

How to correctly set the product images programmatically

Setting up product images in programming is a bit more complicated than specifying the URL in a CSV. The core steps are to first upload the image file to the WordPress media library, obtain its attachment ID, and then assign that ID to the product.

It can be used.media_sideload_imageThe function downloads the image from the URL and creates an attachment. The example code is as follows:

$image_url = 'https://example.com/product.jpg';
$attach_id = media_sideload_image($image_url, $product_id, '产品图片描述', 'id');
if (!is_wp_error($attach_id)) {
    // 设置为主图
    set_post_thumbnail($product_id, $attach_id);
    // 如需加入产品图库
    // $gallery_ids = array($attach_id);
    // update_post_meta($product_id, '_product_image_gallery', implode(',', $gallery_ids));
}

When importing a large number of products, if the website times out or runs out of memory, how should we handle it?

This is due to the server's execution time and memory limitations. For large-scale imports, it is essential not to operate through the WordPress backend interface, but to use other methods instead.WP-CLIA command-line tool, because it is not affected by the PHP timeout settings.

At the script level, you can adopt a batch processing strategy. For example, you can read and process 100 CSV records at a time, and then use the results after the processing is complete.sleep(1)Pause for a moment and cooperate with uswp_cache_flush()Clean up the cache to free up memory. Additionally, before running the import script, you can do the following:wp-config.phpTemporarily increase the memory limit in China:define('WP_MEMORY_LIMIT', '512M');For the import of tens of thousands or even hundreds of thousands of products, it is recommended to directly operate the database or seek more professional data migration tools.