3 min read
Categories Guides

How to Import WooCommerce Orders from CSV

Shirely imports WooCommerce orders from CSV through WooCommerce order objects. That supports both legacy order storage and High-Performance Order Storage (HPOS); it does not write orders directly to the posts table.

Use this workflow for a controlled migration or a reviewed, on-demand update. Start with a backup and a small test file, then inspect the preview before running the full import.

Prepare the order data

Use one CSV row for each order. The dedicated order exporter uses these columns:

order_id, origin_ref, status, currency, date_created, customer_id, customer_email,
billing_first_name, billing_last_name, billing_company, billing_address_1, billing_address_2,
billing_city, billing_state, billing_postcode, billing_country, billing_email, billing_phone,
shipping_first_name, shipping_last_name, shipping_company, shipping_address_1, shipping_address_2,
shipping_city, shipping_state, shipping_postcode, shipping_country, payment_method,
payment_method_title, transaction_id, customer_note, total, line_items, refunds

You can use a smaller file for a targeted update. Scalar fields present with a non-empty value are written; omitted or empty fields are left as they are.

Line items and refunds

Put line items in the line_items column as SKU:quantity:total. Separate several items with a pipe character:

SKU-A:2:59.98|SKU-B:1:29.99

Shirely resolves the first value as a SKU, or as a product ID when it is numeric. Import the relevant products first, so each line item can be linked to a product. A non-empty line_items value replaces the order’s existing items; if the column is absent or empty, the existing items are preserved.

Refunds use amount:reason, also separated with a pipe where there is more than one. To avoid duplicate refunds, Shirely skips refund import when the target order already has refunds and reports a warning.

How matching works

An empty order_id creates a new order. For an order exported by Shirely, retain both order_id and origin_ref when you later import it. The provenance reference lets the importer identify a safe repeat import.

Order numbers are unique only inside a store. If an incoming row names an existing order but does not include verifiable provenance, Shirely skips it rather than overwrite an order from the wrong store. When a source order number collides with an existing order from another store, that row is also skipped and reported for review.

Import safely

  1. Export the source orders with Shirely where possible, preserving origin_ref.
  2. Import the products required by the order line items first.
  3. Import customers if you want orders to connect to existing customer accounts. Customer ID is used when valid; otherwise an existing account can be found by email, and a missing account is imported as a guest order with a warning.
  4. Upload the CSV, map the columns, and inspect the preview.
  5. Run a small test first, verify orders in WooCommerce, then run the remaining rows on demand.

During an order import, Shirely suppresses transactional emails and stock adjustments for that request. Review the resulting orders, warnings, totals, and line items after every migration batch.

FAQ

Does this work with HPOS?
Yes. Order import and export use WooCommerce order APIs, which work with HPOS and legacy order storage.

Can I update an existing order?
Yes, when the importer can verify the order’s provenance. Keep the origin_ref from a Shirely export. A bare matching order ID is not enough to authorize an overwrite.

Will a status-only file replace line items?
No. Existing items are preserved unless the row contains a non-empty line_items value.

Do I need WPML?
No. Orders are not handled as multilingual content and do not use Matrix Mode columns.

For catalog work, see how to import WooCommerce products from CSV. For a store-to-store process, export a small sample first and confirm the matching behavior before migrating the full order history.