How to Import WooCommerce Products from a CSV File (Complete Guide)

The hard part of a product import is rarely clicking Import. It is deciding what each row means before WooCommerce receives it.

A useful CSV gives every product a stable identity, separates parent products from variations, and contains only the fields the current job is meant to maintain. Shirely then maps those columns to WooCommerce, shows a preview, and processes the file in batches.

This guide covers the single-language product workflow. You do not need WPML for it. If your catalog is multilingual, Matrix Mode adds language columns and translation relationships on top of the same preparation principles.

Start with a narrow, readable file

Shirely accepts UTF-8 CSV uploads up to 50 MB. Put field names in the first row and one product record on each following row. For a small simple-product import, the source may be as compact as:

sku,name,regular_price,stock,product_cat,featured_image
MUG-101,Stoneware mug,14.50,24,Kitchen > Mugs,https://example.com/images/mug-101.webp
CAP-205,Wool cap,28.00,9,Clothing > Accessories,https://example.com/images/cap-205.webp

SKU is the recommended public matching key for ordinary product imports, especially when the file may be used on another store. A new product also needs enough content to be valid and useful—normally a name, type where relevant, and the catalog fields your store requires.

Do not export or invent sixty columns merely because WooCommerce has sixty possible fields. A price update needs a stable key and price columns. An image migration needs a stable key and image columns. Narrow files are easier to inspect and reduce the number of unrelated values that can change.

Preserve identifiers as text

Open the file in a spreadsheet carefully. SKUs and Global Unique IDs can contain leading zeros, long digit sequences, hyphens or letters. A spreadsheet may silently convert them to numbers or scientific notation.

Format identifier columns as text before pasting data. Then save as UTF-8 CSV and reopen a sample to confirm that values such as 0012345678905 still look exactly the same.

For WooCommerce 9.2 and later, Shirely accepts the source headers ean, gtin, barcode or _global_unique_id and maps them to WooCommerce's native Global Unique ID. Treat the value as text so leading zeros survive, then verify it on the product and individual variations.

Map source headers to WooCommerce fields

After upload, Shirely recognizes common headers and proposes mappings. Treat that as a first pass, not an instruction to stop reviewing.

Check every column that can change catalog behavior:

• SKU and product type;
• name, slug, descriptions and status;
• regular and sale price;
• stock quantity and stock status;
• categories and tags;
• global and local attributes;
• featured image and product gallery;
• Global Unique ID;
• selected SEO or custom meta fields.

Leave a column unmapped when it should not be imported. For simple post meta, use a meta_ column followed by the actual meta key. That can cover known Yoast, Rank Math or ordinary custom fields, but it is not dedicated ACF field-type logic.

An omitted column is outside the update. An explicitly mapped empty value may clear or change a field. Test important empty-cell behavior before running a large file.

Choose the exact Import Mode

Shirely provides three modes:

• Create & Update creates new products and updates rows that match existing products.
• Only Create (skip existing) creates new products and leaves matching products alone.
• Only Update (skip new) updates matching products and leaves unmatched rows unmodified.

Select the mode according to the business job, not according to which button sounds safest. A supplier feed that should never create products usually belongs in Only Update (skip new). A reviewed initial catalog may use Only Create (skip existing). A controlled source that owns both new and existing rows may use Create & Update.

Matching still depends on clean identity. A duplicate SKU, a changed SKU or a Product ID copied from another WordPress database can change the outcome. Shirely 1.3.0 catalog provenance prevents a foreign exported ID from being blindly treated as a local ID, but stable natural keys and destination QA remain necessary.

Describe variable products parent-first

A variable product is a parent row followed by child variation rows. Add type and parent_sku:

type,sku,parent_sku,name,regular_price,stock,pa_color,pa_size
variable,TEE-300,,Everyday T-shirt,,,Red|Blue,Small|Medium
variation,TEE-300-RED-S,TEE-300,,24.99,18,Red,Small
variation,TEE-300-BLUE-M,TEE-300,,24.99,11,Blue,Medium

The parent must appear before its variations. Every variation SKU must be unique, and parent_sku must match the parent exactly. Put variation-level price and stock on the purchasable variation when those values differ by option.

Use WooCommerce global pa_* attributes when a variation should select reusable taxonomy terms. The variable-products documentation covers the parent, attribute and storefront QA sequence.

Handle categories and images as real dependencies

Product category paths such as Kitchen > Mugs make hierarchy readable. If you are moving a multilingual or deeply nested taxonomy to an empty store, import and verify the category tree as its own step before depending on it in the product run.

Image fields can use a reachable remote URL or an existing local media reference. Shirely resolves featured_image, image_url, _product_image_gallery and product_gallery; multiple gallery references can be separated by a pipe or comma. The first resolved image becomes featured and later resolved images populate the gallery.

Remote files must be reachable by the WordPress server. Private and reserved network destinations are blocked. Test one product with a featured image and several gallery images before scheduling a large media-heavy import.

Preview a sample that represents the catalog

Do not use only the simplest row as your test. Prepare a small sample containing:

• a simple product;
• a variable parent and variations;
• a nested category;
• a product with sale price or managed stock;
• featured and gallery images;
• one identifier with a leading zero;
• one row that should match an existing product.

Review the parsed values and mappings, then run this sample on staging. Open the products in wp-admin and on the storefront. Check price, stock, category links, image proportions, variation selectors, status and the fields that were deliberately omitted.

If the sample surprises you, fix the source or mapping. A bigger run does not make an ambiguous key safer.

Understand batching and resume

Shirely processes large sources in batches rather than loading the whole catalog into one request. If a run is interrupted, completed rows remain saved and the available checkpoint supports resuming the job.

Resume is not a rollback. Review the error, matching key, import mode and current destination state before continuing. If the source was changed after the interruption, a narrow correction file may be safer than assuming the old checkpoint still describes the same job.

Product and Matrix rows are processed on re-import. Smart Sync's unchanged-row skip applies only to posts, pages and custom post types with a mapped Record ID. Product repeatability comes from stable matching, explicit modes, narrow columns and verification—not from a global unchanged-product skip.

Save Automation only after the manual run is proven

Shirely 1.3.0 can save supported product imports as Automation slots. Use Run now first and check Run History. A slot can later use WP-Cron at hourly, twicedaily or daily, or WP-CLI called by system cron.

WP-Cron depends on site traffic and does not guarantee an exact start time. System cron with WP-CLI is the more predictable option when timing matters. Do not overlap imports that may write the same products, terms or WPML/WCML translation groups.

Headless Automation and WP-CLI remove the destructive delete_non_matching option. That boundary prevents an incomplete scheduled source from acting as a broad deletion request.

Verify the result, not only the completion message

Compare run counts with the source and inspect products throughout the result—not just the first page. Check at least one example of every product type and field group included in the file.

When something needs correction, create a small update CSV with the stable key and only the affected columns. A ten-row price correction is easier to approve than re-importing the complete catalog with descriptions, categories and images still mapped.

FAQ

Does every CSV need an SKU column?

SKU is the recommended public matching key for ordinary product imports, especially across stores. Same-store workflows may use a valid local Product ID, and Matrix Mode can use Matrix ID / External ID when that is the intended key. Choose and test one stable strategy.

Can I import directly from Google Sheets?

Yes. A published Sheet can be imported without credentials; a private Sheet requires a Google Service Account. The import still runs as an explicit job rather than a continuous connection.

Will the same file always avoid duplicates?

No unconditional promise is safe. Correct matching and mode selection let Shirely update existing products. Missing, duplicate or changed identifiers can produce a different result, so preview and test.

Can I import JSON or XML with this workflow?

No. The supported file upload described here is CSV. Google Sheets is available as a separate source. Do not build a public workflow around unsupported JSON or XML source claims.

A calm import starts before the upload

A dependable product import is a sequence: narrow the file, protect identity, review mappings, select the exact mode, test the awkward rows and verify the storefront. Once that manual path is repeatable, batching and Automation can remove routine setup without removing the QA gate.

Use the documentation for field and settings details. For an existing catalog, prepare a narrow file and follow the same preview process with Only Update (skip new).