Migration template explained
To migrate your customers into Recharge, you will need to format your exported data into the Recharge-migration-template.csv. The data needs to be in this format for our system to import it correctly.
This guide provides an overview of the headings within the template and the information required to prepare the file.
Before you start
- Make sure you do not include any special or strange characters in the data.
- Do not change the column titles or headings in the file.
- Do not use zero values for cells without any data. Instead, leave the cells blank.
- Make sure to add all products that your customers have been subscribed to into the Products section in your merchant portal. If the product is no longer available but has active subscribers, you can mark them as hidden in Shopify after they have been added to Recharge. Refer to Creating subscription rules for more information.
- If you use a filter in your spreadsheet, ensure you haven't inserted blank columns between the default columns we’ve set. If you want to use a filter in your spreadsheet, select all data contained in the file. This way, when you sort the data, it will ensure that you don't mix up the columns.
- After you have added all your data, save your CSV file in UTF-8 format using LF-style linefeeds. If you are not familiar with encodings, then see your spreadsheet or text editor program's documentation.
Template headings explained
Most fields are mandatory unless noted as optional in the table below. For mandatory fields, ensure you have entered values in every column row.
Column headings |
Description |
|
This is the name of each product the customer has on file. If a customer is subscribed to more than one product then each product should be on a separate row. |
|
This is the name of the variant for each product. If you do not have variants, you can leave this blank. If you're using BigCommerce and your products have variants you must enter the variant title exactly as it is spelled in BigCommerce. Otherwise, if the product doesn't have variants you can leave this field blank |
|
The product ID of the original product (not the hidden, auto-renew product). |
|
The variant ID of the original product (not the hidden, auto-renew product). Shopify assigns a variant ID to a product even if your product does not have multiple variants. Refer to Shopify's guide on finding the variant ID to locate the variant ID for products that have variants. You can also navigate to your Products dashboard in Shopify, and select a specific product. Once you have the Shopify product page open for that product, add .json to the end of the page URL to access the Variant ID through the product JSON. This method is helpful if your product has multiple variant IDs. |
|
How many of each product the customer will order each renewal date (or shipping date for prepaid orders). |
|
The price the customer will pay per item each renewal date. This does not include shipping, taxes, or quantity. It should be the product price per unit without the currency symbol.
You can enter any price, even if it differs from the product price in Shopify. This price will be used for that subscription until the customer cancels their subscription or changes the product. If you charge shipping/tax, it will be added to each recurring order once it is migrated into Recharge so you do not need to include it in this price. |
|
This is the type of unit used to schedule charges. There are three options to be added here: month, week, or day. |
|
The number of months, weeks, or days between each charge. For example, If the customer is charged every month, you would enter 1 in this column and set the unit type in the previous column to months. |
|
This should almost always be the same number as your charge_interval_frequency, unless this is a prepaid subscription, meaning you ship more often than you charge. If you have prepaid subscriptions, then you will set the charge frequency to how often you charge, and the shipping frequency to how often you ship. For a three month prepaid subscription that is delivered every month, you will enter a charge frequency of 3 and a shipping frequency of 1. |
|
If the row is a prepaid subscription then you'll enter "yes" in this column for that row. If it is not a prepaid subscription you can enter "no" or leave it blank. For more information, refer to How do I handle prepaid subscriptions in the migration template? |
|
An optional field for stores who charge every customer the same day each month, regardless of what day they signed up. For example, you charge every customer on the 10th of the month, so you would enter 10 in this column. |
|
If you have prepaid subscriptions, you would include the date the customer started their current prepaid cycle. The format should be YYYY-MM-DD. You'll leave this field blank if they are not prepaid. For more information, refer to How do I handle prepaid subscriptions in the migration template? |
|
The date the customer will be charged for their first recurring payment in Recharge. This date should never be in the past, and the earliest charge date should be the day after you cancel your old system after importing to Recharge. The format should be YYYY-MM-DD. It is recommended that you enter these dates well enough into the future. This will allow time for importing that data and data checks. If the status is cancelled, you'll leave this field blank. |
|
This is the customer's creation date in your old system. The format should be YYYY-MM-DD. |
|
The email address for the customer's account in Recharge and Shopify. |
|
The first name of the shipping recipient. Do not include any strange or special characters. |
|
The last name of the shipping recipient. Do not include any strange or special characters. |
|
This is the customer's phone number. You can use any data format you want. Note: If Shopify settings are configured to require a phone number at checkout, this field is mandatory to avoid auto-generated numbers. It is recommended that you turn off this Shopify setting if you're migrating any customers without phone numbers. |
|
The primary street address of the shipping recipient. Do not include any strange or special characters. Also, ensure you have the address in every row in the case of multiple subscriptions. |
|
The secondary street address of the shipping recipient. |
|
The city of the shipping recipient. |
|
The state/province of the shipping recipient. |
|
The zip or postal code of the shipping recipient. US zip codes should be only the first 5 digits with leading zeros |
|
The country of the shipping recipient. |
|
Company name associated with the shipping address. |
|
Fill this out if the first name is different from the shipping recipient's first name. If blank, it will default to the shipping first name. |
|
Fill this out if the last name is different from the shipping recipient's first name. If blank, it will default to the shipping first name. |
|
You can fill this out if the billing address is different from the shipping address. If this is blank, it will default to the shipping address. |
|
You can fill this out if the billing address is different from the shipping address. If this is blank, it will default to the shipping address. |
|
You can fill this out if the billing city is different from the shipping city. If this is blank, it will default to the shipping city. |
|
You can fill this out if the billing zip or postal code is different from the shipping zip or postal code. If this is blank, it will default to the shipping address. |
|
You can fill this out if the billing province/state is different from the shipping province/state. If this is blank, it will default to the shipping province/state. |
|
You can fill this out if the billing country is different from the shipping country. If this is blank, it will default to the shipping country. |
|
You can fill this out if the billing phone number is different from the shipping phone number. If this is blank, it will default to the shipping phone number. |
Payment columns
Depending on where your existing subscribers' payments are stored, you must include the appropriate columns below so we can create payment methods in Shopify
Stripe
For Stripe customers, you will add two additional columns:
stripe_customer_id
stripe_payment_method_id
Braintree
For Braintree customers, you will add two additional columns:
braintree_customer_id
braintree_payment_token
Authorize.net
For Authorize.net customers, you will add two additional columns to the CSV, and leave the customer_stripe_id column blank:
authorizedotnet_customer_profile_id
authorizedotnet_customer_payment_profile_id
Paypal
For Paypal customers, you will add one additional column:
paypal_billing_agreement_id
Shopify
Optional - If you have customers with payments already within Shopify, it is recommended you provide the shopify_payment_method_id
as it allows our team to associate a specific card with the customers subscription.
Not all platforms will provide you this data. If you do not include this field, we will automatically select the customer's first payment method in Shopify to link to their subscriptions.
Spreedly
For Spreedly customers, you will add one additional column:
spreedly_customer_token
If you are currently using Spreedly to vault credit cards, we can use this ID to match the customer with their payment data in Spreedly.
Additional Columns
You may need to add additional columns if your subscriptions meet the following criteria. Additional columns should be added at the end of the standard migration template.
BigCommerce
For BigCommerce stores, we require the BigCommerce customer ID. So you'll add this field to the CSV and copy the customer IDs from BigCommerce. This is not the customer ID in your subscription system, but in BigCommerce itself.
external_customer_id
We also need the SKU of the variant for each row. If the variant doesn't have SKUs you can leave this blank.
- SKU
Charge on a specific day of the week
If you charge customers on a specific day of the week then you can add this column:
charge_on_day_of_week
The accepted values are Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday.
The interval_unit
must be set to "week".
Expiring subscriptions
If the prepaid subscription cycle is ending and will not renew, you will need to fill out both the last_charge_date and next_charge_date columns in order for our system to generate the prepaid shipments. To tell us this will not renew, you’ll want to add an additional column at the end of the spreadsheet:
number_charges_until_expiration
For prepaid subscriptions that are set to expire, you will indicate 1 in this column.
Inactive/cancelled subscriptions
status
The only available statuses are active and cancelled. If the customer has an active subscription, you should enter active in this column. If the customer has an inactive subscription, you should enter cancelled in this column. If the row is cancelled you’ll also need to remove the next_charge_date value.
cancellation_reason
If customers filled out the reason for their cancellation then you can enter that text in this field. Otherwise, you can leave this blank.
Discount codes
discount_code
If the customer has an active discount code on their subscription, you can add it using this column. You will also need to make sure the discount code is created in Recharge.
Legacy shipping rates
original_shipping_title
-
original_shipping_price
You will add two additional columns, one for the name of the shipping rate (ie. International Shipping) and one that includes the shipping price.
Custom line item properties
line_item_properties
If you have custom properties for products using line items in the JSON format, then we can add these properties once the customers and subscriptions are imported.
All elements in the JSON string will need to be enclosed in double quotations except for integers and be in the following format, using the example below:
[{"name":"sizeS","value":20},{"name":"sizeXXL","value":50}]
Multi-currency
presentment_currency
For stores that are using Multi-currency, you will specify the currency using this column header. The currency must be in the 3-digit abbreviation format. USD, CAD, etc. If you don't include a currency the store's default currency will be used. Each currency needs to be on a separate import file.
Recharge Admin Use Only
Delivery method
Note: Delivery methods are only available for customers who have Shopify payment methods and subscription contracts.
delivery_method_type
and delivery_method_location_id
columns include values, do not add values to the original_shipping_title
and original_shipping_price
columns. If values are included with shipping title or shipping price, Recharge will set the delivery method on the subscription to Shipping and will ignore the value passed in the delivery_method_type
field.For stores using local delivery and pickup, you must include the delivery method type and delivery method location ID columns to ensure migrated orders retain their delivery methods:
-
delivery_method_type
- The delivery method used for order fulfillment. One of the following values should be included:-
LOCAL
- The order is delivered using a local delivery service. -
PICK_UP
- The order uses pickup as its delivery method. -
SHIPPING
- The order uses shipping as its delivery method. -
NONE
- No delivery is needed.
-
-
delivery_method_location_id
- Represents a location where product inventory is held.- This column is only required for orders using the
PICK_UP
delivery method type, otherwise, it can be left blank. - To find the location ID in your Shopify Admin, click Settings, select Locations, and click a location. On the location page, copy the location ID from the end of the URL.
- This column is only required for orders using the
If you add local delivery and pickup columns to a migration, we will import the delivery method and create purchase records with the proper delivery_method_type
configured. If you fail to add these columns, migrated orders will default to SHIPPING
for their delivery method.
For example, if you want to migrate a customer with a delivery method of PICK_UP
, you must include the location ID for the pickup location. If the location ID is missing from a PICK_UP
migration, the delivery method will be reverted back to SHIPPING
.