Skip to main content

How can we help?

Migration template explained

Shopify Checkout integration Recharge Checkout on BigCommerce Recharge Checkout on Shopify BigCommerce Checkout Integration
Sections

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

external_product_name (optional)

 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.

external_variant_name (conditional)

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

external_product_id

 The product ID of the original product (not the hidden, auto-renew product).

external_variant_id (required for Shopify)

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.   

BigCommerce doesn't allow you to export the variant ID. If your products have variants you must enter the variant title exactly as it is spelled in BigCommerce. You can leave this field blank if you don't have variant IDs. 

quantity

 How many of each product the customer will order each renewal date (or shipping date for prepaid orders).

recurring_price

 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.

interval_unit

 This is the type of unit used to schedule charges. There are three options to be added here: month, week, or day.

charge_interval_frequency

 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.

order_frequency

 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.

is_prepaid (optional)

 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? 

charge_on_day_of_month (optional)

 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.

last_success_charge
(only for prepaid subscriptions)

 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? 

next_charge_scheduled_at

 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.

customer_created_at (optional)

 This is the customer's creation date in your old system. The format should be YYYY-MM-DD.

shipping_email

 The email address for the customer's account in Recharge and Shopify.

shipping_first_name (optional)

 The first name of the shipping recipient. Do not include any strange or special characters.

shipping_last_name

 The last name of the shipping recipient. Do not include any strange or special characters.

shipping_phone (optional)

 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.

shipping_address_1

 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.

shipping_address_2 (optional)

 The secondary street address of the shipping recipient.

shipping_city

 The city of the shipping recipient.

shipping_province

 The state/province of the shipping recipient.

shipping_zip

 The zip or postal code of the shipping recipient. US zip codes should be only the first 5 digits with leading zeros

shipping_country

 The country of the shipping recipient.

shipping_company (optional)

 Company name associated with the shipping address.

billing_first_name (optional)

 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.

billing_last_name (optional)

 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.

billing_address_1 (optional)

 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.

billing_address_2 (optional)

 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.

billing_city (optional)

 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.

billing_postalcode (optional)

 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.

billing_province_state (optional)

 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.

billing_country (optional)

 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.

billing_phone (optional)

 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

Note: Refer to Understanding the migration process to learn more about where your customer's payment methods are stored. 

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.

Note: Recharge does not have support for other status types, such as paused subscriptions. You will need to re-assign these subscriptions as either cancelled/inactive (by indicating cancelled in the status column) or active.
  • 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.

Note: The shipping rate entered in these columns will be used for all recurring orders for this subscription.

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

Note: Fixed discount codes on Multi-currency addresses will be auto converted to the customer’s presentment currency.
Multi-currency is not available for Braintree users.
  • 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.

Note: If the 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.location ID.png

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.

Was this article helpful?
2 out of 2 found this helpful

Related articles

Didn’t find what you’re looking for?

Contact us