WooCommerce Subscriptions Importer and Exporter

Import subscriptions to WooCommerce via CSV, or export your subscriptions from WooCommerce to a CSV.

• Importer Documentation
• Exporter Documentation

---

Support

The WooCommerce Subscriptions Importer and Exporter is released freely and openly to help WooCommerce developers migrate subscriber data to WooCommerce Subscriptions. Even with this plugin, migrations involve a lot of manual work to format subscription data correctly and test imports. Neither Prospress nor WooCommerce provide services to complete a migration with this tool.

For help with a migration, please contact an official Woo partner. For smaller-scale migrations, learn more and consider using Codeable's Migration packages here.

Prospress do not provide support for migration issues. This means Prospress can not help with CSV formatting, fixing broken renewals or other issues with subscriptions imported incorrectly. Similarly, issues with subscriptions created with this plugin are not supported via the WooCommerce support system.

If you think you have found a bug in the extension, problem with the documentation or limitation in the data that can be imported, please open a new issue to report it.

---

Subscriptions Importer

With the WooCommerce Subscriptions CSV Importer, you can import subscriptions from a CSV file into your WooCommerce store. This is particularly useful when migrating stores from a different eCommerce platform.

The subscriptions will be setup with the WooCommerce Subscriptions extension to process future recurring payments.

Before you Begin

Importing your subscriptions to WooCommerce is a complicated process.

To maximize your changes of success with an import, please read through this documentation in its entirety.

There is no substitution for this step. Fully understanding the details of the import process will save you time by avoiding mistakes that may become serious issues in the future.

Importer Usage Guide

To import your subscriptions to WooCommerce via CSV, you need to:

1. Create a CSV file with all your subscription data formatted for import (this is by far the most complicated step). The CSV Formatting Guide details the options and requirements for your CSV's content.
2. Go to WooCommerce > Subscription Importer
3. Upload your CSV file
4. Select Import Options:
   1. Check Run in test mode to validate your CSV file without creating corrupted data
   2. Check Email Passwords to email customers that are newly created their account details
   3. Check Add memberships to grant subscribers any membership/s plan corresponding to subscription products
5. Click Upload and file and import
6. Review each column of data in your file to make sure the Importer has mapped it to the correct column header.
7. Click Test CSV
8. If there are errors, fix up the CSV file and return to step 1.
9. If there are no errors, click Run Import
10. Review the Import Completion Table and Import Logs for uncover any issues with the import

While these steps may sound simple, the devil is in the details, especially in creating your CSV. The rest of this guide will provide you with the details. Please be sure to read this in its entirety.

Import Options

When uploading your CSV file, the Importer also provides you with a few options to customise the behaviour during the import process.

Import options:

• Run in Test Mode
• Email Passwords
• Add Memberships

Run in Test Mode

Running the import in test mode will analyse each row of your CSV and notify you of any warnings or errors with that data.

It will not import any subscription data in your store's database, like users or subscriptions.

After running test mode, the Importer will provide you with an Importer Test Results table. This displays the issues with your CSV. If there are issues, you can safely abort the import process to fix up the CSV. If there are no issues, you can continue the Import.

We strongly recommend you continue to run the importer in test mode until you have correct all warnings and errors. Unfortunately it's not possible to catch all errors that will occur when actually importing your subscriptions. The good news though is that even during an actual import, exceptions and other errors that can only be discovered at the time of import will be logged and the corresponding subscription will not be created.

Email Passwords

When a CSV files includes a username or email address, and the Importer can not find an existing user with either of those details, it will create a new WordPress user.

You can also specify a password to use on the user's account in the CSV, otherwise, the account is created with the secure password generated by WordPress.

When the Email Passwords option is enabled, if the Importer creates a new user account, it will also email that user a registration email with their login details and a temporary password.

If left unticked, the new users created will need to go through the "forgot your password" process which will let them reset their details via email.

Please note: the minimum requirement for creating a new user is an email address. If no username is given, the importer will to create a username from the email. Say you you need to create a new user and have only given the email address, janedoe@example.com, the importer will try a new user with username janedoe. If this username is already taken, we then try the username janedoe1, janedoe2 and so on; until it finds a free username (i.e janedoe102).

Add Memberships

If you have WooCommerce Memberships active on your site, you will also be presented with the option to Add Memberships.

When this option is enabled, subscriptions imported with product line items linked to a membership plan will also grant the subscriber's user account with corresponding membership access.

Column Mapping

During step 2 of the import process, each column header found in the CSV will be listed as a row in the table on the Map Fields to Column Names page.

You can use the dropdown menu to find and match each piece of data to a value known by the importer. You must not have the same fields mapped more than once unless it's found under the custom group.

The full list of fields, with an explanation of each, are available in the CSV Columns section of this guide.

Import Completion Table

After an import has been completed, you will be provided with a table displaying the result of each row's import.

This table will display the success of failure of the import for each row, as well as any warnings or errors that occurred when importing that row.

Review this table carefully after running your import to identify any potential issues with each subscription.

Import Error Logs

In addition to the output displayed in the Import Completion Table, the Subscriptions CSV Importer will also log issues into a special log file.

These log entries can be reviewed to see what when wrong during the import and therefore, what needs to be fixed up after the import (if anything).

These logs may contain issues not identified during test mode which relate to plugin conflicts, database issues or other errors that only occur during the live import. Becuase of this, we strongly encourage you to review the log files even if your CSV had no issues during test mode.

Exception Logger

The importer will catch all PHP exceptions thrown during the import and log them along with with the line in the CSV that was being processed when the exception occurred.

To view the exception logs:

1. Go to the WooCommerce > System Status administraction screen
2. Click the Logs tab
3. Click the select box for log files
4. Click file prefixed with: wcs-importer-
5. Click View

Example Exception Log Entry

01-15-2016 @ 05:30:26 - Row #2 failed: Array (
    [0] => Could not create subscription: Invalid Subscription billing period given.
)

Fatal Error Logger

When a fatal error occurs during the import process, the importer will log the row of data from the CSV that caused the issue and a stack trace of where the error occurred.

To view the shutdown logs:

1. Go to the WooCommerce > System Status administraction screen
2. Click the Logs tab
3. Click the select box for log files
4. Click file prefixed with: wcs-importer-shutdown-
5. Click View

Example Fatal Error Log Entry

01-12-2016 @ 05:52:16 - CSV Row: Array
(
    [product_id] => 5078
    [status] => cancelled
    [customer_id] => 1
    [start_date] =>
    [next_payment_date] =>
    [end_date] =>
    [shipping_method] => free_shipping
    [coupon_items] => code:recurring_discount|amount:10.00
)

01-12-2016 @ 05:52:16 - PHP Fatal error Call to undefined method WCS_Importer::add_coupons() in /Users/Matt/Dropbox/Sites/subs2.0/wp-content/plugins/woocommerce-subscriptions-importer-exporter/includes/class-wcs-import-parser.php on line 425.

Import HTTP Error Handling

While the Import Error Logs handle PHP errors that can be caught and logged, the Importer will also attempt to handle HTTP errors from Ajax.

To this, it will:

1. catch a HTTP error code returned by the request and
   1. display the HTTP error in the Importing Results table
   2. output the full xmlhttprequest object to the console
2. wait for 20 seconds
3. resume the import by attempting the next set of rows

Importantly, the set of rows with a failure will not be reattempted as there is no way to know which subscriptions were imported successfully. The subscriptions in the rows with HTTP errors need to be manually checked.

To aid in checking these rows, the Importer will provide:

1. the rows affected during the import when the HTTP error code is detected
2. a list of all rows affected during the entire import once the import process completes

Screenshot of CSV Import affected by various HTTP errors

CSV Formatting Guide

By far the most difficult aspect of migrating your subscriptions using the CSV Importer is formatting a valid CSV with all required data.

A subscription is created from a variety of different pieces of data, from customer details like billing and shipping address, to product details, like quantity, taxes and totals, shipping details, like shipping method, tax and cost, as well as billing schedule details, like recurring billing period, next payment date and end date. To import your subscriptions, you must create a CSV with all of this data in a valid form.

This section provides you with an overview of all the fields your CSV can contain (and in some cases, must contain).

CSV Requirements

Please follow these general rules when formatting your CSV file:

• The first row must include column headers - this is so the plugin knows where to map the fields.
• Each subscription needs to have its own row.
• Not all columns need to be filled in for each row, unless the field is labelled required in the CSV Columns section.
• Most fields are not required. However, to avoid creating subscriptions with unintended default data applied, specify as many fields as possible in your CSV.
• Two-letter country and state/county abbreviations should be used for all country, state or county data.
• Date values should always be in UTC/GMT timezone.
• Date fields can be in any string format handled by PHP's strtotime() function. However, strtotime() is a strange beast that on occasion creates unexpected date strings. It also doesn't always handle timezones as expected. Becuase of this, we encourage you to always use MySQL format for dates, e.g. YYYY-MM-DD HH:MM:SS or in PHP's date formatting terms y-m-d H:i:s). For example, 1970-01-01 00:00:01.
• All dollar amounts can be either an integer or decima/float value. For example, 5.65, 3 and 127.2 are all valid.
• Arrays are formated as key:value|key:value|key:value.