WooCommerce Customer / Coupon / Order CSV Import Suite

The WooCommerce Customer / Coupon / Order CSV Import Suite allows you to easily import customer, coupon, and order data from a CSV file into your shop. A minimum of fields are required for a successful import, yet nearly all customer, order, and coupon fields are supported, allowing you to determine the level of detail you wish to import. This is particularly useful when migrating shops and importing from a different eCommerce platform, which may or may not use exactly the same fields as WooCommerce, or when mass-creating coupons (for a Groupon-style sale for instance). Orders can be mapped to existing users (or assigned to ‘guest’), and order items are mapped to existing products via SKU or product_id. In addition to standard WordPress / WooCommerce user and order fields, arbitrary meta fields may also be set, giving you complete control over the import process.

Installation

↑ Back to top

To install Customer/Order/Coupon CSV Import Suite:

1. Download the extension from your WooCommerce dashboard
2. Ensure your site uses WordPress 4.4 or newer.
3. Go to Plugins > Add New > Upload, then select the ZIP file you just downloaded
4. Click Install Now, and then Activate
5. Go to WooCommerce > CSV Import Suite (or click the “Import” link) to start importing your data

Best Practices (Please Read!)

↑ Back to top

These guidelines outline the best procedure to follow while importing. This is intended to maximize success and minimize time and effort while using this plugin.

1. Read through this entire documentation so you know exactly what needs how the import process operates. There is no substitution for this step; yes reading documentation takes time, but it will actually save you time in the end.

2. Export your Customers, Coupons, and Orders from wherever they are currently stored, or build your import files by hand.

3. Set the column names and data formats for the files as described below in this documentation.

4. If transferring data between sites while merging, please be cognizant of your user IDs and order IDs, as you may not want them in an import file. THIS IS IMPORTANT, especially if the site you’re importing to already contains data. See more under Merging Data Between Sites.

5. Do an import dry run. This is especially important for Order data to avoid having to upload the same data file multiple times which could result in duplicate order records.

   Use the “Dry Run” option found after the file upload step to first check your data format. Enabling this option puts the plugin into a test mode where no records will be inserted or modified.

6. Fix any errors with your import file and repeat until the dry run completes cleanly. If this dry run looks okay, you’ll be able to click a link to use a real import for the same data / settings. Then do a live import of the customer, coupon, or order data.

In short, we recommend test runs with Customers, Coupons, then Orders. Then you can do a real run of Customers, Coupons, Orders (in that order).

Sample CSVs

↑ Back to top

Here are some sample CSVs files, which you can download by clicking “File > Download as > CSV”. Download a sample Customer CSV to get started: Download Customers CSV Download a sample Coupon CSV to get started: Download Coupons CSV Download a sample Order CSV to get started: Download Orders CSV Note: if using these files for a test import be sure to import the Sample Customers first, followed by the Sample Orders, and also ensure that you have a product with the SKU woo-ninja so that the order item can be mapped.

Importing: An Overview

↑ Back to top

The Customer / Coupon / Order CSV Import Suite makes it easy to import CSVs to WooCommerce. However, there are some general formatting rules to which you must adhere:

• Each Customer, Coupon, or Order belongs on its own row.
• The first row must include column headers – this is so the plugin knows where to map the fields.
• Values must be separated by a delimiter, which is expected to be a comma “,” by default, though this can be set during the import process to a tab or semicolon. If you’re importing a file from Google Sheets or Excel, for example, a comma is used automatically.
• Date fields can use most formats, but if you can build your CSV by hand, YYYY-MM-DD HH:MM:SS (24-hour, with the time optional) format is best. If you don’t want to use that format, then dates in the MM/DD/YYYY or DD-MM-YYYY formats are disambiguated by looking at the separator between the various components. If the separator is a slash (/), then the American MM/DD/YYYY is assumed; whereas if the separator is a dash (-) or a dot (.), then the European DD-MM-YYYY format is assumed.
• Locality fields: two-letter country and state / county abbreviations should be used when available
• Order notes support multiple items separated by a ‘|’ (pipe) character; for instance, Order status changed from pending to processing|Order exported from WP eCommerce

Selecting Import Source

↑ Back to top

To perform any kind of import, you should go to WooCommerce > CSV Import Suite (if you also use the Product CSV Import Suite, this menu will be named “Order CSV Import Suite”). Here you can select an import type: For any type of import, you’ll be asked to choose the source for your import file:

• CSV or tab-delimited text file – Upload a properly-formatted import file from your computer
• URL or file path – Upload a file directly from an external site or a path on your server (ie an upload folder)
• Copy / paste from file – Paste data from a properly formatted file

If you upload a file, you’ll be taken to a screen to select your import file and upload it. If you opt to use a URL or file path, you’ll be able to enter the absolute path (full URL) and continue to pull in the import data. If you want to copy and paste data, you’ll be given a textarea to enter your import data.

Preview Format and Select Options

↑ Back to top

For each import type, once you’ve uploaded your import data, you can preview the data to ensure your delimiter is correct (the plugin will try to auto-detect it), and to also configure some options for your import. These options will vary by the import type. Once you’ve configured options, you’ll then map your import columns to the data they represent. The plugin will try to auto-match these if possible, but you should check that each column is mapped to the appropriate WooCommerce data.

Dry Run and Live Import

↑ Back to top

Once you’ve mapped data, you’re ready to test the import to ensure it’s formatted properly. You should attempt a dry run with import data to check it before running a live import. If there are issues with your data format, the dry run will inform you of which orders would be skipped or failed and why, so that you may reformat your import file. If this data looks good, you can click the “Run a live import now” link in the notice to use your data and settings for a live import instead. If not, you can also go back to the import settings to re-configure your import and try again. Following a live import, you’ll see a status summary of imported, merged, skipped, and failed rows for your import file to notify you of progress.

Import Completed Notices

↑ Back to top

If you have a large file being imported in either a dry or a live run, you do not have to wait for this import to complete. Because imports are processed in batches in the background on your site, you can safely leave the page and the import will continue to progress. You can continue to work on other areas of your store, and can even leave the site completely while your import processes. For both dry runs and live imports, you’ll see a notice pop up in the admin area when your import has been completed. For dry runs, this will let you see results and then run your live import. For live imports, you’ll have a link to the progress results page to let you review the updated, created, merged, and skipped files in more detail.

Importing Customers

↑ Back to top

Because orders can be mapped to your customers, it’s important to import any customer data first. Importing customers involves setting up a CSV file containing various column headers. When importing customers, the only requirement is the email column. Please note that WordPress will automatically assign the User ID as customers are created! Any User ID set for a customer will not be respected on creation. The ID column can optionally be used when performing a merge, or email will be used if not set. If merging data between different sites, be aware that User ID is always preferred, but likely will not match up between your sites. Only include the User ID while merging if you intend to match users based on it, as it will be used before username or email to identify a user. Please read about merging cross-site data for further insights.

Accepted Customer Data

↑ Back to top

Column headers determine what fields your data maps to. This sample file can show you the recommended minimum columns, or you can view this sample file to see all columns in use. Column headers can be named whatever you’d like, as you’ll map these headers to the appropriate data when you set up your import. These are sample column headers / values that you can import (using these names will help to automatically map columns):

Customer columns / data
user_id	billing_last_name	shipping_first_name
username	billing_company	shipping_last_name
email	billing_address_1	shiping_company
password	billing_address_2	shipping_address_1
date_registered	billing_city	shipping_address_2
role	billing_state	shipping_city
url	billing_postcode	shipping_state
paying_customer	billing_country	shipping_postcode
billing_first_name	billing_phone	shipping_country

A few helpful notes:

• date_registered – If not set, the current date / time will be used when creating new customers.
• username – This is a good idea to provide for easier login, but if not supplied then it will be set to the email.
• password – You can provide plaintext or pre-hashed passwords (if importing from another WordPress site / CSV Export).
  • Passwords exported from a much earlier version of WordPress may use a different hash, and therefore would need to be reset or imported as plaintext.
  • Passwords exported from an existing WordPress install 3.x or higher should use the same hash, and so the “Don’t hash user passwords” import option can be used.
  • Any other passwords not from a WordPress environment would need to be reset, or use plaintext to be re-hashed on import, and so the “Don’t hash user passwords” import option must not be used.
• role – The WordPress user role. This defaults to ‘customer’ on import.
• paying_customer – This should be “yes” or “no”
• billing_country/shipping_country – This should be the two-letter country code. You can find a list of official codes here.

Customer Meta (custom fields)

↑ Back to top

To import a custom field, use the meta key as the column name. For example, if you wanted to import a custom field called “customer_contacted” you would name your column: customer_contacted When you map your columns, you can then select “Custom field with column name” for this while importing.

Customer Import Process

↑ Back to top

To import your customers, first properly format your import CSV file. Select your import method, and your file / data. You’ll now be able to configure customer import options and preview your CSV.

• Shipping Address – Enable this to use the billing address as the customer shipping address if shipping columns are not set. If they are included in the CSV, but simply blank, this setting will not take effect.
• Don’t hash user passwords – If your CSV file already contains hashed passwords (for example, passwords exported by the Customer / Order CSV Export plugin), then you can enable this. Otherwise, the importer will assume the password is plaintext and should be hashed.
• Send Emails – Enable this to send the WooCommerce “new account” emails to newly created customers, and WordPress password reset emails to update customers, after the import.
• Merge Update –
  • Update existing records if a match is found – Enable this to merge customer data on import. The plugin tries to match a customer by the user ID, username, then the email.
  • Insert as new if a match is not found – Enable this to create new customers if the importer can’t match a row to an existing customer. When disabled, non-matched rows are skipped.
• Debug Mode – Enable this to log import rows as they’re added. As a best practice and for maximum performance, please only enable this if you experience issues with imports.
• Fields are separated by – If your preview looks incorrect, the plugin may not have detected the delimiter properly. Try to switch delimiters to fix the preview; if no delimiters look correct, you will need to reformat your file.

Next, you’ll map your CSV file’s columns to WooCommerce customer data. The plugin will try to match data to column headers, but you should double-check this to ensure that data mapping is correct.

You can choose any of the customer data fields we’ve listed above for each column.

Importing Coupons

↑ Back to top

When importing coupons the only requirements are the coupon_code, discount_type, and amount columns. The coupon_code column is the only required column when performing a coupon merge to update existing coupons.

Accepted Coupon Data

↑ Back to top

You can get a good idea of the available coupon fields and their expected values by looking at the “Add New Coupon” screen in WooCommerce by going to WooCommerce > Coupons > Add Coupon, or by viewing our sample coupon CSV.

column	required?	default	values
code	yes	n/a	identifies the coupon; must match an existing coupon to merge
type	for new coupons	n/a	represents coupon type; can be: fixed_cart (cart $) percent (cart %) fixed_product (product $) or plugin custom type
description	no	–	optional coupon description
amount	for new coupons	n/a	the amount / value of the coupon
expiry_date	no	–	the date the coupon expires
enable_free_shipping	no	“no”	“yes” if the coupon grants free shipping
minimum_amount	no	0	the minimum subtotal needed to use the coupon
maximum_amount	no	–	the maximum subtotal allowed to use the coupon
individual_use	no	“no”	“yes” if the coupon cannot be used with others
exclude_sale_items	no	“no”	“yes” if the coupon should exclude sale items
products	no	–	comma-separated list of SKUs for products that need to be in the cart to use this coupon For product discount: products the coupon applies to
exclude_products	no	–	comma-separated list of SKUs for products that cannot be in the cart to use this coupon For product discount: products the coupon will not discount
product_categories	no	–	comma-separated list of product category slugs, ie: ‘games, t-shirts’; product must be in this category for the coupon to remain valid For product discount: products in these categories will be discounted.
exclude_product_categories	no	–	comma-separated list of product category slugs, ie: ‘games, t-shirts’; product must not be in this category for the coupon to remain valid For product discount: products in these categories will not be discounted.
customer_emails	no	–	comma-separated list of email addresses to restrict this coupon to specific billing and user emails
usage_limit	no	–	number of total coupon uses
limit_usage_to_x_items	no	–	maximum number of individual items the coupon can apply to when using product discounts
usage_limit_per_user	no	–	number of times this coupon can be used by an individual user.
usage_count	no	0	number of times the coupon has been used

Coupon Meta (custom fields)

↑ Back to top

To import a custom field, use the meta key as the column name. For example, if you wanted to import a custom field called “coupon_url” you would name your column: coupon_url When you map your columns, you can then select “Custom field with column name” for this while importing.

Coupon Import Process

↑ Back to top

To import your coupons, first properly format your import CSV file. Select your import method, and your file / data. You’ll now be able to configure coupon import options and preview your CSV.

• Merge Update –
  • Update existing records if a match is found – Enable this to merge coupon data on import. The plugin tries to match a coupon by the coupon code.
  • Insert as new if a match is not found – Enable this to create new coupons if the importer can’t match a row to an existing coupon. When disabled, non-matched rows are skipped.
• Debug Mode – Enable this to log import rows as they’re added. As a best practice and for maximum performance, please only enable this if you experience issues with imports.
• Fields are separated by – If your preview looks incorrect, the plugin may not have detected the delimiter properly. Try to switch delimiters to fix the preview; if no delimiters look correct, you will need to reformat your file.

Next, you’ll map your CSV file’s columns to WooCommerce coupon data. The plugin will try to match data to column headers, but you should double-check this to ensure that data mapping is correct. You can choose any of the coupon data fields we’ve listed above for each column.

Importing Orders

↑ Back to top

Because orders can be mapped to your customers, it’s important to import any customer data first. As orders can also contain coupons, having coupon data available before importing orders is useful as well. Order items are mapped to your products via SKU, or can optionally be mapped to product_id instead, so ensure all applicable products are loaded as well. Orders are merged based on order ID, then order number, so please be aware of this when merging. If merging data between different sites, you may want to omit order ID. Please read about merging cross-site data for further insights, or see this tutorial to learn how to keep order number consistent between sites.

Accepted Order Data

↑ Back to top

When importing orders there are no required fields; however there wouldn’t be much point in importing an order without at least some values defined, such as line items and customer details. Note: If the import CSV file contains no shipping headers / columns, the customer billing details will be copied over as shipping details. You can view our sample order CSV as a starting point, or view the minimum import CSV to see the recommended minimum columns. Note that, if creating orders, there may be default values set if not present in your CSV. As of version 3.3.0, merging will not use any default values.

Order Data
column header	default (if creating orders)	values
order_id	automatically generated	integer – (only needed for merging, not inserting, orders) the post ID of the order, typically how the order is identified. Must match an existing order to merge, this will not be used for inserting new orders.
order_number	–	if provided, this must be an integer and is the numerical incrementing portion of your order number. See the Custom Order Numbers section for a discussion of the limitations on order numbers.
order_number_formatted	–	(optional) formatted order number. If your order numbers consist of an incrementing number portion and some letters/characters, this is the entire order number. For instance, you might have order_number: 817 and order_number_formatted: WT-817-UK. See the Custom Order Numbers section for a discussion of the limitations on order numbers.
created_at	import’s current date / time	the date & time the order was placed. The timezone of the date must match the WordPress timezone setting of the site the order is imported into. See the helpful tips section for further information.
status	processing	order status; this must match one of the order statuses defined in your shop. In a default WooCommerce installation this will be one of “pending”, “failed”, “on-hold”, “processing”, “completed”, “refunded”, or “cancelled”.
currency	shop currency	the currency in which the order was placed
shipping_total	–	the total order shipping amount, ie “5.65”. If not provided, this can be calculated based on your import settings.
shipping_tax_total	–	the total order shipping tax, ie “0.21”; if not provided, this can be calculated based on your import settings.
fee_total	–	the total fees amount, ie “3.99”
fee_tax_total	–	The total tax on fees, ie “0.42”
tax_total	–	this is the total order tax; if not provided, this can be calculated based on your import settings.
cart_discount	–	the sum of all cart discounts applied
order_total	–	the overall order total; if not provided, this can be calculated based on your import settings.
refunded_total	–	the total of all refunds for the order
payment_method	–	this should be the payment method name as seen in the Order admin, ie “cheque”, but can be any string that identifies the payment method to you.
shipping_method	–	this should be the shipping method name as seen in the Order admin, ie “free_shipping”, but can be any string that identifies the shipping method to you.
customer_note	–	any notes added by the customer for the order
order_notes*	–	order notes support multiple items separated by a ‘|’ (pipe) character; for instance, Order status changed from pending to processing|Order exported from WP eCommerce
download_permissions_granted	0	set this to “1” to grant access to downloadable products in the order
refunds	–	refund lines for the order

A few helpful notes:

• order_id – Order ID’s cannot be imported. WooCommerce will insert the order and assign a new ID during the import. The Order ID field is only used for updating/merging existing orders on your site.
• created_at – The date used in the CSV file should match the same timezone of the site the order will be imported into. This is typically set from the WordPress settings > general page in admin. If the export was taken from a different site, with different timezone settings, the CSV file should be modified before import to avoid incorrect order dates in the new system. The format of the date value should match ‘Y-m-d H:i:s’ (e.g. 2000-01-20 12:00:00)

See the notes below for formatting order item cells properly.

Order Items
column header	values	data needed
line_items	all line items purchased in the order, such as products. This must contain at least the following data for each item: product ID or SKU, quantity purchased, and total price for the line (qty x unit price).	product_id or sku, quantity, total, subtotal*/td>
shipping_items	all data for each shipping method, just contain at least method ID, total cost	method_id (ie flat_rate), method_title, total
tax_items	all tax items for the order, must contain tax code and total	code, title, total
fee_items	all fee items for the order	name, total
coupons	all coupon data for the order, each coupon must have a code and amount	code, amount

*Not specifying the subtotal of a line item when importing orders will change it based on the item’s total divided by its quantity. Order items can use a couple of formats to delimit keys and values. If programmatically creating data, we recommend using JSON, while if you’re building an import by hand, the “pipe-delimited” / native format is a bit easier to work with. We recommend using this and letting WooCommerce recalculate totals with your import settings.

• JSON – can accept data in JSON format, such as:

  [{"product_id":99,"product_name":"Woo Album","quantity":1,"total":19.99}]

  Please ensure that the required data listed above is included.
• Pipe-delimited – data divided by pipe characters, such as:

  product_id:99|sku:woo-album|name:Woo Album|quantity:1|total:19.99

  Multiple items can be divided by a semi-colon (;) delimiter. Please ensure that the required data listed above is included.

Order Refund Data

A special case to mention is refund data. If you need to include refunded items in your import, there are a couple steps to take:

1. Include additional information for each product in the line_items column.
   • refunded – the cost refunded for this item, ie refunded:35.00
   • refunded_qty – the quantity refunded as a negative integer, ie refunded_qty:-1
2. Include the refunds column if you want to add further data on the refund (without this column the refund is assumed to happen with the import itself).
   • date – The date on which the refund was processed, ie date:2016-09-01 10:00:00
   • amount – The total amount processed in this refund, ie amount:35.00
   • reason – The reason this refund was processed (optional), ie reason:No longer wanted

Customer Data
column header	default	values
customer_user	guest	optionally links this order to a customer; this can be the customer ID, email, or username. If not provided, the order will be marked as a guest purchase. If the customer is found they will be marked as a “paying_customer”
billing_first_name	–	customer billing first name
billing_last_name	–	customer billing last name
billing_company	–	customer billing company
billing_address_1	–	customer billing address – line 1
billing_address_2	–	customer billing address – line 2
billing_city	–	customer billing city
billing_state	–	this should be the two-letter state / county code when available.
billing_postcode	–	the customer billing postcode
billing_country	–	this should be the two-letter country code. You can find a list of official codes here.
billing_email	–	customer billing email
billing_phone	–	customer billing phone
shipping_first_name	billing first name if column not set	customer shipping first name
shipping_last_name	billing last name if column not set	customer shipping last name
shipping_company	billing company if column not set	customer shipping company
shipping_address_1	billing address 1 if column not set	customer shipping address – line 1
shipping_address_2	billing address 2 if column not set	customer shipping address – line 2
shipping_city	billing city if column not set	customer shipping city
shipping_state	billing state if column not set	this should be the two-letter state / county code when available.
shipping_postcode	billing postcode if column not set	the customer shipping postcode
shipping_country	billing country if column not set	this should be the two-letter country code. You can find a list of official codes here.

Order Item Meta

Arbitrary order item meta can be added to an order item by using the following syntax:

meta:meta_key=meta_value

As an example, to add the item meta MANUFACTURER: APPLE you could use the following:

meta:MANUFACTURER=APPLE

Note that any number of item metas can be added in this manner, and they may include any character, except the meta name may not contain a colon (:) or pipe (|). Within the meta value the special characters (:) and (|) are allowed but must be preceded by a backslash (\). For instance:

meta:MANUFACTURER=APPLE \| APPLE INC.

Will set the order item meta named “MANUFACTURER” to “APPLE | APPLE INC.” To add multiple meta items to a line_item, and using the pipe separated format, you should use the “,” character as a separator. For example:

meta:MANUFACTURER=APPLE,DEVICE=IPHONE

will add both MANUFACTURER and DEVICE meta data to the line item.

Custom Order Numbers

↑ Back to top

Custom order numbers are a tricky subject and deserve special mention. Due to the implementation of WooCommerce, which uses the underlying post_id for the order number by default, it’s not possible to directly set the ID for an order without migrating database tables directly. As a workaround, the CSV Import Suite will automatically add an order note containing the original order_number / order_number_formatted if one is provided. In addition, any specified order_number / order_number_formatted will also be set as special meta data on the order. This meta data can be used by a compatible custom order number plugin like the Sequential Order Numbers Pro or (free) Sequential Order Numbers plugins. With Sequential Order Numbers Pro installed, your imported order numbers will work seamlessly: the order numbers will be displayed both in the admin and frontend, but even without a compatible custom order number plugin you can always view your historical order numbers in the notes section for each order.

Order Meta (custom fields)

↑ Back to top

To import a custom field, use the meta key as the column name. For example, if you wanted to import a custom field called “order_delivery_date” you would name your column: order_delivery_date When you map your columns, you can then select “Custom field with column name” for this while importing.

Order Import Process

↑ Back to top

To import your orders, first properly format your import CSV file. Select your import method, and your file / data. You’ll now be able to configure order import options and preview your CSV.

• Allow Unknown Products – Enable this to allow line items with unknown product IDs or SKUs to be included (not recommended).
• Reduce product stock – Enable this to reduce the stock for products associated with paid orders.
• Recalculate taxes & totals – Enable this to use WooCommerce core functions to recalculate order, shipping, fee, and tax totals upon import for the order record. This may change the data from what you’ve included in your import file. This will not match new shipping zones based on current site settings, as only the totals will be adjusted.
• Use addresses from customer profile – Enable this setting to use the billing and shipping details from the customer profile. This will only use customer details from the user profile if none of the billing or shipping columns are set for orders (useful if you only want to import customer IDs and use saved information).
• Send Emails – Enable this option to send new order emails to customers when inserting new orders. It will also email store managers for any status changes due to order updates/merges.
• Merge Update –
  • Update existing records if a match is found – Enable this to merge order data on import. The plugin tries to match an order by the order ID, order number, then the formatted order number.
  • Insert as new if a match is not found – Enable this to create new orders if the importer can’t match a row to an existing order. When disabled, non-matched rows are skipped.
• Debug Mode – Enable this to log import rows as they’re added. As a best practice and for maximum performance, please only enable this if you experience issues with imports.
• Fields are separated by – If your preview looks incorrect, the plugin may not have detected the delimiter properly. Try to switch delimiters to fix the preview; if no delimiters look correct, you will need to reformat your file.

Next, you’ll map your CSV file’s columns to WooCommerce order data. The plugin will try to match data to column headers, but you should double-check this to ensure that data mapping is correct. You can choose any of the order data fields we’ve listed above for each column.

Importing from Shopify

↑ Back to top

If you’re migrating to WooCommerce from Shopify, please be aware that the default Shopify order CSV export will not import by default. However, we can make some changes to import orders.

Shopify Order Differences

First, Shopify has concepts of an order “Fulfillment status” and “Financial status” (which are available for each line item in an order), whereas WooCommerce does not manage orders in this fashion. Instead, WooCommerce has one overall “order status” that indicates both the payment and shipment status for the order. (Read more about WooCommerce order management.) As a result, you cannot preserve fulfillment status for your line items upon import. We recommend fulfilling all paid Shopify orders before migrating, and then these orders can be imported with the “completed” status. For orders that have not yet been paid, you can import these as “pending payment” or “on hold” depending on your workflow.

Shopify Column Names

You may want to make some cosmetic changes to your CSV file, such as breaking the Shopify “billing name” column up into “billing first name” and “billing last name” columns. However, there are a few changes you must make to the default Shopify order export. The WooCommerce Order CSV Importer doesn’t recognize one-row per item formats well (it expects one-row per order formats), but we can force it to recognize Shopify’s format by using some very specific column names. Adjust some columns in your Shopify export to use these column names exactly while importing, and when the importer maps them automatically for you, do not change them to map the columns to other values.

Shopify column name	Represents?	WooCommerce column name
Name	the order ID / reference number. Must not contain “#” symbol, see note below	order_id
Id	the shopify order ID	n/a – remove column from file
Lineitem price	the price of the line item. Used to calculate the item_total for WooCommerce	n/a – leave as is
Lineitem quantity	quantity of the item purchased	item_quantity
Lineitem name	the name of the product	item_name
Lineitem sku	the SKU for the product (must match new WooCommerce SKU)	item_sku
n/a	this column must exist in the file – create this as a new column, even if empty	item_meta
Tax 1 Value	the tax for the item (you should combine all applicable tax into this column)	item_tax

Due to a conflict between how Shopify considers the Lineitem price, and WooCommerce considers the item_total, there is one final change needed to correctly import the line item item_total.

• Add a new column to your sheet and label it item_total.
• Create a function to calculate the value in this column, which should use the existing Shopify Lineitem price × item_quantity.

You must also remove the # symbol in the Name / order_id row. Typically, most programs have a way to find / replace this value. For example, if you edit the file with Google Sheets, you can follow these steps:

1. Highlight your “Name” / order_id column and go to Edit > Find and replace…

   

2. In the “Find” field, enter: # In the “Replace with” field, do not enter anything. Click “Replace all”.

   

3. Don’t forget to rename your column to order_id if you haven’t done so already.

   

Lastly, Shopify groups meta, such as the color purchased, in the “Lineitem name” category. You can move this data into the new item_meta column if you’d like (it makes your order data a bit nicer), but it’s not necessary; the item_meta column just has to exist. You could also consider renaming the Vendor column to item_meta if this would make sense for your store. Once you’ve edited your CSV, you should now be able to begin the import, and map your Shopify data to the desired WooCommerce data.

Managing Imports

↑ Back to top

You can view or delete import progress data by going to WooCommerce > CSV Import > Import List. This will show you a list of your recent import jobs (typically for the past 14 days; they are cleared out periodically). This allows you to view the progress page for a previous import or delete the progress data for an old import. You can also use this to stop and delete an import while it’s running. To view the progress page for a previous import or a currently running import, click the “eye” or View action for that import. To delete progress results for an import, click the “trash” or delete icon. This will not delete imported data. It is not an “undo” button — you should always perform dry runs to confirm data is as expected, since once it’s created or updated, there is no going back. Deleting a job simply deletes the progress data associated with it. If you click the “x” or stop icon, this can halt a processing import. It will fail the job and delete the progress information. This does not delete data that was already processed. Since imports are processed in batches, any information that was already processed will be on your site. This action lets you stop a running import if needed. We do not recommend using it unless an import appears to be stuck, as this can result it incomplete data merge or creation.

Plugin Compatibility

↑ Back to top

Customer / Coupon / Order CSV Import Suite is compatible with several plugins that add metadata to to customers, coupons, or orders, as it allows you to import custom meta fields and custom taxonomies. While it may not be compatible with every plugin, here are some it works well with, and import tips for each.

URL Coupons

↑ Back to top

Customer / Coupon / Order CSV Import Suite is compatible with URL Coupons version 2.4.0+. This lets you import URLs for coupons, determine what products the URL coupon should add to the cart, and adjust redirects or defer settings for the coupon. You can import the extra metadata URL coupons needs by following the instructions in the URL Coupons documentation.

Customer / Order CSV Exporter Compatibility

↑ Back to top

This plugin is compatible with the Order / Customer CSV Exporter format, and able to import exported Orders. The steps required to export orders in a format compatible for import are as follows:

1. Go to WooCommerce > CSV Export
2. Click on the ‘Settings’ tab at the top
3. For the Orders and Customer Export Formats, select CSV Import

If you have old CSV Export data with one row per item instead of one row per order, the CSV Importer will try its best to detect this, and provide you with mapping options. However, for best performance, you should be using the Exporter’s “CSV Import” format, which is what this plugin expects.

Admin Custom Order Fields

↑ Back to top

Admin Custom Order Fields can be imported with the CSV Import Suite. In order to import order fields, you must name the column with the field ID, such as: _wc_acof_{id} You can determine a field’s ID by viewing your list of order fields, and hovering on the order field to view the ID. For example, if a field has ID: 2, then you should name your column: _wc_acof_2

The value for each row should be the value for that order. The only current limitation is for admin fields that, if a field can have multiple values (such as a multiselect), then the import can only accept multiple values in a serialized format. We do have improved compatibility for this on our roadmap, so please get in touch with feedback if this feature is important to you!

Cost of Goods

↑ Back to top

To import costs for an order with Cost of Goods, you’ll need both order meta and order item meta fields. For the entire order, you should set a column to import the _wc_cog_order_total_cost order meta, and map this to “Custom field with column name” on import. This represents the total cost for all order items. You’ll also need two meta fields for each order line item: _wc_cog_item_cost — the unit costs of the product _wc_cog_item_total_cost — the total cost for the line item (product cost x quantity) For example, an imported line item may look like this:

product_id:75|name:Woo Logo|quantity:2|total:30|meta:_wc_cog_item_cost=10|meta:_wc_cog_item_total_cost=20

Custom Taxonomies Support

↑ Back to top

With version 3.0+ of this plugin, you can import custom taxonomies for customers / coupons / orders. To import a taxonomy, the taxonomy slug should be your column header (ie coupon_cat). The value for each row should be a list of terms, separated by a pipe (“|”) character. Example:

Groupon|Spring Sale

Points and Rewards

↑ Back to top

While we have no specific integration with WooCommerce Points and Rewards to import previously assigned points, it is still possible to have this data generated! The Points and Rewards plugin will automatically calculate points data for any new inserted order. Therefore, as long as the metadata for Points and Rewards is removed from the CSV import file prior to importing the order, Points and Rewards will generate the correct point total and store it in the correct database table.

Merging Data Between Sites

↑ Back to top

Most merchants who use Customer / Coupon / Order CSV Import together with the Customer / Order CSV Export plugin do so to update data on the same site, so merging doesn’t often pose an issue since order and customer IDs remain the same. However, if you merge data between sites, you need to be very aware of your import file so you don’t overwrite existing data based on IDs, as these will not match. The importer cannot think for you; you must be very explicit when you give it data and tell it to add or overwrite data. This important with the case of user or order IDs in customer or order imports, respectively. Customers are matched based on the following columns, in this priority:

• user ID
• username
• email

Orders are matched based on the following columns, in this priority:

• order ID
• order number formatted
• order number

If you are trying to merge data between sites where the IDs do not match up (which may or may not be likely, depending on how the sites were set up), you may need to remove the IDs column from your import or skip it while importing. Instead, consider using order number instead to match data between sites where post IDs / order IDs won’t match. Likewise, with customers, consider using email address as the default key to match between sites rather than user ID if this will not match up exactly. This could happen if you’ve imported your customers to a new site, as WordPress will create new user IDs upon customer creation. Your old customer IDs will be different from the new ones. In short, think your import through before doing a live run, and you may want to import on a staging site first to ensure your import is performing expected tasks, as adding or overwriting data cannot be undone. Here’s an example case you may want to avoid: If data from Site 2 is exported, then imported to Site 1 with merging enabled, John Smith’s order data will be overwritten with Jane Doe’s order, as the order IDs match (order number isn’t considered unless order ID doesn’t match). If you don’t want to match on user or order ID, then you can’t include it, as the importer doesn’t know this.

Troubleshooting

↑ Back to top

Having trouble? Please ensure your site uses WordPress 4.4 or newer, then check out these sections or the FAQ below.

Imports Remaining Queued

↑ Back to top

Imports are done as a background, asynchronous process, that requires your site to make requests to itself for information. As such, your site cannot block HTTP requests or imports will not begin to process. If your imports freeze without completing, your site may be blocking HTTP requests in some way. Please check the following common causes of blocked requests:

• Are you using a maintenance mode or blocking plugin? For example, the “Airplane Mode” plugin for developers will block HTTP requests. Please disable the maintenance mode plugin to process imports.
• Similarly, if your site is behind BasicAuth, background requests will fail to complete. For example, WP Engine staging sites often use basic authentication to block site access (you see a popup for credentials when you try to access the site): Please see the notes here to correct this issue, or disable basic authentication while testing imports.
• Finally, some hosts will block the requests from servers to themselves. You can test this by going to WooCommerce > Status > Tools and run the Background Processing Test. This tool will simulate the import process:
• Host files: For developers – hosts files to resolve a site to a different domain can’t be used with Customer/Order/Coupon Import and many other WooCommerce plugins. Customer/Order/Coupon Import Suite uses wp_safe_remote_* requests to get data from itself, and these requests require a domain name. If your site is pointing to a domain from a hosts file, rather than a public site, these requests will fail.

If this tool returns an error, this means that your host won’t allow requests from your site’s server (the plugin) to itself to start processing a file (sometimes called a “loopback connection”). Your host must enable this for imports to work. While some hosts may note that this is a security issue, there is no security threat to using a loopback connection; if done incorrectly, it could increase server usage, but quality hosts will combat this for you with intelligent rate limiting. More importantly, many features in WooCommerce or upcoming features need loopback connections to function: for example, the database updater (already in use) and future plans for backgrounded email sending; both of which uses the same type of background processing (and requires loopback connections). It’s essential that a host for an eCommerce site support this.

Other Issues

↑ Back to top

First, please note that any column included in the import will be respected. This means that, if you include a column, but this is blank for a particular row, then this data will be blank / empty on import. When a column is included, it’s always updated, so be careful including blank cells, they can become blank on an order. (The exception to this is when customers are created on a new site, as their user ID will be generated by WordPress and a user ID column will not be respected.) Running into a different issue? Please create a help request and attach your import file / include a link to it in the thread.

Frequently Asked Questions

↑ Back to top

Q: I tried exporting customers with the WooCommerce CSV Export plugin after importing customers with the Customer / Order CSV Import Suite. The newly imported customers are not exported, why is this? A: The WooCommerce CSV Export plugin works in a fundamentally different manner than this plugin. The Export plugin works by exporting the customer Billing information from Order records; this Import plugin works by creating WordPress user records for the imported customers. Exporting looks primarily at orders, while importing creates users. This import plugin also has the capability to import order data and create Order records, associating customer user records with any imported Orders. Thus if you simply import customer records, and then try to export them you won’t succeed. If you import both customer and order records, then you will be able to export any customer information from those imported Orders.

---

Q. I’ve imported my customers, but none are showing up under WooCommerce > Customers! What’s going on? A. If you haven’t yet imported any order data for your customers, WooCommerce doesn’t recognize them as customers, so they won’t show up here yet. Once you import associated order data for these users, WooCommerce will designate them as customers and they’ll appear here.

---

Q. Does this extension import Subscriptions? A. No, this extension will not help import Subscriptions.

---

Q: Why won’t my special / accented / foreign characters import properly? A: The file you are importing must be properly encoded as UTF-8. One way to easily do this is to import or create it in Google Sheets, and download from there before importing. Open office also works well, but MS Excel most likely will not work. (#)

---

Q: I don’t want to send welcome emails, but I do want to send ‘password reset’ emails if relevant. Is this possible? It looks like they’re controlled by the same setting. A: Yes, you can enable password reset emails, regardless of your settings, with a one-line snippet — add this where you keep custom code:

add_filter( 'wc_csv_import_suite_send_password_reset_emails', '__return_true' );

---

Q: Help! How do I stop a frozen import? A: Don’t worry! Sometimes there are conflicts with the imported data that prevent an import from processing, or background processing may not be working as expected. To stop or cancel an import, you can follow the steps listed in our “managing imports” section.

---

Q: Will the customer importer create and assign new roles? A: While you can assign / update a user role, the role must already exist in your WordPress install (currently available roles can be found by logging into the WordPress admin, editing your profile, and clicking the “Role” dropdown). You can use a plugin like the User Role Editor to create custom roles, which then can be assigned to customers using the Customer CSV Importer.

---

Q: Why do I receive an import error when I try to import products with quotes in their names? A: When attempting to import a product or products with quotes listed directly in their names, e.g., Ollivander 12” Rosewood Wand, neither the use of a single quote nor the use of an escaped quote will work. Instead, we recommend using the syntax, &quot, within the import file for the product name, e.g., Ollivander 12&quot Rosewood Wand.

---

Questions & Support

↑ Back to top

Have a question before you buy? Please fill out this pre-sales form. Already purchased and need some assistance? Get in touch with support via the help desk.