How to Import WooCommerce Customers from CSV

Customer imports deserve more care than a typical catalog update. A product row cannot receive an unexpected email. A customer can — and a poorly tested migration can create confusion before anyone has checked whether names, addresses, and accounts landed correctly.

Shirely imports each customer as a WordPress user with the customer role and saves the WooCommerce billing and shipping profile on that account. The workflow is separate from product and order import, which makes it easier to map, preview, and verify this sensitive data on its own.

Prepare one clear row per customer

A new customer needs user_email. The user_login field is optional; when it is not provided, Shirely can use the email address as the login. Common account fields include first_name and last_name, followed by WooCommerce's billing_* and shipping_* address fields.

A practical file might begin like this:

user_email,user_login,first_name,last_name,billing_address_1,billing_city,billing_postcode,billing_country,shipping_address_1,shipping_city,shipping_postcode,shipping_country
alex@example.com,alex,Alex,Nowak,12 Market Street,Krakow,30-001,PL,12 Market Street,Krakow,30-001,PL

Use UTF-8, keep country and region values consistent with WooCommerce, and do not add empty columns merely because they exist in an old export. A focused file is much easier to review than a hundred-column spreadsheet in which only ten fields matter.

If the source is a Shirely customer export, keep customer_id and origin_ref. They give the importer useful provenance for a repeat import or migration. Email also acts as a natural matching key when a safe provenance match is not available.

Preview the mapping before writing users

Upload the CSV, choose the customer import, and review the proposed field mapping. Familiar headers such as user_email, first_name, and billing_city are straightforward, but a source system may use names like email_address, postal_code, or delivery_city.

Map only what you intend to change. Shirely's customer updates are partial: non-empty fields supplied by the row can be written, while fields not included in the row remain unchanged. That makes a narrow correction possible — for example, updating billing phone numbers without replacing every shipping address.

Use the preview to catch shifted columns, broken characters, and address data mapped to the wrong side. For a large migration, make the first test a small selection that includes:

• a new customer;
• an account that already exists by email;
• billing and shipping addresses that differ;
• accented or non-English characters;
• a row with an intentionally omitted optional field.

How customer matching avoids casual overwrites

WordPress user IDs are local to each site. Customer 842 in an old store may have nothing to do with user 842 in the destination.

Shirely uses provenance when it is available and does not blindly trust a colliding customer ID from another installation. If that ID is ambiguous, the row is skipped instead of authorizing an update to the wrong account. A matching email can identify an existing customer when there is no safe provenance match; otherwise a new customer can be created.

This is why retaining origin_ref matters in a Shirely round trip. It preserves the context behind an ID instead of treating the number as globally meaningful.

After a test import, check both outcomes: confirm that a known email updated the intended account and that a genuinely new row created one new customer rather than a duplicate.

Passwords and customer emails need an explicit decision

Do not import password hashes. Shirely rejects values that look like password hashes and generates a password instead. Customers who need access should use the destination store's normal password-reset process.

Shirely 1.3 also separates a deliberate manual invitation from unattended work:

• in the manual wizard, an invite can be enabled for newly created customers;
• existing accounts do not receive that invite;
• Automation and WP-CLI runs do not send customer invite emails.

That boundary is useful during a migration. You can load and inspect customer records without turning an unattended data job into a messaging campaign. If you choose to invite new customers during a manual run, test the email template and delivery path on staging first. Do not assume the data import itself is a communications plan.

Import in a safe store-migration order

Customer data rarely moves alone. A sensible sequence is:

1. Import the products that future order line items need.
2. Import a small customer sample and inspect the WordPress users and WooCommerce address fields.
3. Import the remaining customers.
4. Import a small order sample and verify customer links.
5. Continue with the wider order history only after those checks pass.

Back up the destination before the first write. Run the workflow on staging and keep other imports that could touch the same records out of the way until it finishes.

Verify more than the customer count

A matching row count is helpful, but it does not prove that the import is good. Open several imported profiles and confirm:

• email, login, name, and role;
• billing and shipping names;
• country, state, postcode, and street fields;
• phone and billing email where supplied;
• non-ASCII characters;
• the expected result for a repeated row;
• whether the chosen email behavior occurred only where intended.

Also inspect warnings. A skipped ambiguous ID is information to resolve, not a reason to force the importer to overwrite whatever happens to own that number.

Frequently asked questions

Will every imported customer receive a welcome email?

No. The manual wizard can optionally invite newly created customers. Existing accounts do not receive that invite, and headless Automation or WP-CLI imports do not send customer invite emails.

How does Shirely prevent duplicate accounts?

It uses provenance-aware matching when available and can use email as a natural key. An ambiguous customer-ID collision is skipped instead of being trusted blindly.

Can I import password hashes from the old store?

No. Values that look like password hashes are rejected. Use the destination store's normal password-reset process when customers need to sign in.

Does a missing CSV column clear that field?

No. Customer updates are partial. Fields not supplied in the row remain unchanged; map and test the fields you actually want to update.

Do customers need WPML or Matrix Mode columns?

No. Customer accounts are not translated catalog content and do not use Matrix Mode.

For a full store move, continue with importing WooCommerce orders from CSV after the customer sample has been verified. The Shirely documentation explains the wider workflow and the safety boundaries for manual and unattended runs.