Imports

The subscriptions import tool will allow you to import new subscriptions into Advanced Billing from a CSV file. The tool does not allow you to update existing subscriptions via this method. The CSV subscription import feature is strictly for creating new subscriptions.

Subscriptions can also be imported using API. Please see subscriptions API import for more information.

This is an advanced feature that is only recommended for merchants with technical experience in mapping data in CSV format. Limited support will be provided.

If you do not feel comfortable with the procedures laid out below, please open a support ticket or contact our support team at support@maxio.com

Support for the subscriptions import feature is available Monday - Thursday during the hours of 9 am-5 pm Eastern. In the event an unexpected error occurs, please contact support@maxio.com.

Feature Compatibility

Certain Advanced Billing features are not compatible with the subscription import tool at this time:

Customer hierarchies
Importing subscribers that utilize the WhoPays feature

Sample XLSX Files

Advanced Billing requires that you use one of the following example files to input data using the subscription import tool.

Advanced Billing does not permit you to import files you have previously exported from the merchant login area, such as the subscriptions tab. In order for an existing subscription export report to be validly used for importing subscriptions, the data must be reformatted and placed in one of the spreadsheets below.

If you have the customers’ credit card details on file (usually merchants who are new to Advanced Billing):
Sample XLSX with Card Numbers

If your customers’ payment details are stored in the secure vault of one of our supported gateways (new and existing Advanced Billing merchants):

Sample XLSX with Vault Tokens

If you do not have your customers’ payment details and plan on requesting them later or are subscribing them to a free product (new and existing merchants).

Sample XLSX with No Payment Profiles

XLSX files will need to be saved as CSV with UTF-8 formatting prior to upload.

Sample CSV Files

Editing CSV files in Excel or Numbers can cause formatting issues. If you wish to edit the files using these programs, please use the XLSX files above, and save them as CSV prior to import.

Important Notices and Disclaimers

When a subscription is imported that contains a product with a trial period, the trial period will be omitted.
Subscription imports will either create a subscription with a subscription state of Active or Canceled depending on if the conditions for importing a canceled subscription are met.
The activated date of the subscription will be the date that the subscription is imported. Unless you are importing a canceled subscription, you can absolutely set the “next_billing_date” to a time in the future.
API Users: Use the subscription override endpoint to align Advanced Billing data with your existing data.
You must disable all email notifications related to subscription creation if you do not want to alert your customers that you have created the active subscription (signup emails, receipts, statements, and billing portal invitations). For canceled subscriptions, an email will not be sent regardless of these settings.
We recommend that you limit the number of subscriptions in each import to 100.
We recommend that you use the tool when our technical specialist team is available to help with any issues (normally Monday-Thursday, 9a-5p Eastern).
A billing address cannot be provided unless vault tokens or full card numbers are provided as the billing address is stored with the payment profile. If you are not importing vault tokens or full card numbers, please be sure your product settings do not require a payment method or billing address at signup. Once the import is complete, you can re-enable the required fields in your product settings so new signups must enter this information.
Authorize.net requires the last four digits of the credit card number to process refunds. Please include the last four digits of the credit card number when importing with vault tokens only.
CyberSource requires a billing address to process successful transactions. You will not be able to import subscriptions without a vault token or full card number for this gateway.
When working with credit card data in Excel, long strings of digits are converted into scientific notation. Excel will always convert a long series of digits into scientific notation when you open the source data in Excel (double-clicking the file and opening it in Excel). To get around the scientific notation conversion, you have to import your CSV file into Excel and define the column of digits as text so that Excel will not convert it to scientific notation. In addition, Excel only records numbers up to 15 digits if they are not entered as text. Any additional digits are reset to 0.

Cross section of good / bad credit card numbers in Excel

We do not recommend importing multiple Subscriptions which use the same vault token.

Advanced Billing Overview

The following is a list of required fields for subscription creation via the import tool. They must be in CSV format.

Minimum requirements for active subscription creation

product_handle or product_id (Can be found under the Setup tab, beneath the name of each product)
customer_first_name (The customer’s first name - will become the default for payment profile first name)
customer_last_name (The customer’s last name - will become the default for payment profile last name)
customer_email
customer_id (You may use customer ID if it exists. In this case, omit all other customer fields)
next_billing_at (The first time you will bill your customer - see format)

Minimum requirements for canceled subscription creation

product_handle or product_id (Can be found under the Setup tab, beneath the name of each product)
customer_first_name (The customer’s first name - will become the default for payment profile first name)
customer_last_name (The customer’s last name - will become the default for payment profile last name)
customer_email
customer_id (You may use customer ID if it exists. In this case, omit all other customer fields)
canceled_at (The time that the subscription was canceled - see format)

Required if you are importing credit card details

payment_profile_full_number
payment_profile_cvv (Optional)
payment_profile_expiration_month
payment_profile_expiration_year
payment_profile_card_type (Optional, see allowed values)

Required if you are importing existing vault information

payment_profile_current_vault (see allowed values)
payment_profile_vault_token (see format)
payment_profile_customer_vault_token (Only used for certain gateways such as Authorize.Net, Square (legacy only), Adyen and GoCardless)
payment_profile_last_four
payment_profile_expiration_month
payment_profile_expiration_year
payment_profile_card_type (Optional, see allowed values)

Recommended for billing

payment_profile_first_name (otherwise customer_first_name is used)
payment_profile_last_name (otherwise customer_last_name is used)
payment_profile_billing_address
payment_profile_billing_address_2
payment_profile_billing_city
payment_profile_billing_state (see format)
payment_profile_billing_zip
payment_profile_billing_country (see format)
payment_collection_method (see payment collection method)
currency (if multi-currency is enabled; the currencies must already be configured within your site)

Recommended if you also ship physical product

customer_address
customer_address_2
customer_city
customer_state (see format)
customer_zip
customer_country (see format)
customer_phone

Components (optional)

Detailed information on importing components. However here are examples of what will work:

metered_component_id[123] or metered_component_id[123]price_point_id[1]
quantity_component_id[456] or quantity_component_id[456]price_point_id[2]
on_off_component_id[789] or on_off_component_id[789]price_point_id[3]

Optional

customer_reference
customer_vat_number (see format and information)
coupon_code
previous_billing_at (see format and information)
product_price_point_handle or product_price_point_id (If included subscription will be created with that specific product price point instead of the default price for the product)
subscription_metafield_id
customer_metafield_id (see format and information)
import_mrr (true or false, requires future next_billing_at, defaults to false) (see MRR section for more information)
activated_at (The original date that the subscription was activated - see format)

Additional Optional fields for canceled subscriptions

cancellation_message (A message provided by the customer as to why they canceled)
reason_code (The churn reason code associated with the cancellation)

Customer references must be unique.

Date Format

The following date formats are equivalent and will work as input to next_billing_at, activated_at, previous_billing_at, and canceled_at:

Aug 06 2030 11:34:00 -0400
Aug 06 2030 11:34 -0400
2030-08-06T11:34:00-04:00
8/6/2030 11:34:00 EDT
8/6/2030 8:34:00 PDT
2030-08-06T15:34:00Z

You may also pass just a date, in which case we will assume the time to be noon: 2030-08-06

Next Billing At

If you enter NOW for next_billing_date, your customer will be charged immediately upon import.

Setup Fee

Subscriptions that are created at a later date will not charge the initial/setup fee if created using this mechanism. If you have a product with a setup fee you must use the value of now for next_billing_date in order to collect the setup fee.

Trial Period

Additionally, if there is a trial period on the purchased product, the trial period will be omitted. In the case of any missed fees, due to the omitted setup fee, use the feature to Add Charge if you wish to include any additional fees to the subscription.

Previous Billing At

The optional previous_billing_at attribute is used to help backdate existing subscriptions that are being migrated from another billing management tool. It will set the current_period_starts_at and activated_at fields on the subscription. While activated_at is a display-only field, current_period_starts_at will allow for the correct proration for ‘existing’ subscriptions.

For example, ordinarily, a subscription imported today will have their billing period set to today. By passing a previous_billing_at, it’s possible to backfill the beginning of the period. Let’s say a subscription’s period started on Jan 1 2019 and ends on Jan 1 2020. The date today is July 6 2019. previous_billing_at will set the period start date on the subscription to Jan 1 2019, rather than the default behavior of July 6 2019.

The previous_billing_at date must be before the current time and before the specified next_billing_at. We recommend putting the subscription on a product whose recurring period matches the length of the subscription’s period. See the how to format this field.

Payment Collection Method

Advanced Billing allows you the option of importing invoice-based subscriptions. The payment collection method can be specified for each individual subscription and may consist of one of the following values: “automatic,” “invoice,” or “remittance.” If no method is specified within the CSV file, Advanced Billing will use your site defaults, but no changes need to be made to the site settings in order to import a variety of payment collection methods.

“remittance” is manual invoice billing for our new Relationship Invoicing architecture. For the legacy statement architecture, use “invoice.”

Card Types

The payment_profile_card_type field is optional. If supplied, it must be one of:

american_express
dankort
diners_club
discover
forbrugsforeningen
jcb
laser
master
maestro
solo
switch
visa

Subscriptions with Paypal proflies payment methods may not be created with the Advanced Billing import tool. Additionally, subscribers with ACH as a payment method may not be created via import. If you'd like to create subscriptions with either of these payment methods, please use the subscription import API method.

Vaults

The payment_profile_current_vault field is required if you are supplying vault tokens, and must be one of:

authorizenet
beanstream (Bambora merchants: use beanstream due to a merger.)
bpoint
braintree_blue
cybersource
elavon
eway
eway_rapid_std
firstdata
litle (Vantiv merchants: use litle due to a merger.)
moneris
nmi
orbital
payment_express
pin
quickpay
square (legacy only)
stripe_connect
trust_commerce
adyen
gocardless

Alternately, if you are importing subscriptions to an existing site that is using a legacy gateway such as “PayPal Website Payments Pro (Legacy)” or “eWAY Rapid 3.1 (Legacy)” then you can supply paypal or eway_rapid, respectively, as the payment_profile_current_vault. If you are unsure, please open a support ticket and we’ll be glad to help.

Vault Token Examples

The following are example Vault Tokens showing the format used by each of the payment processing gateways:

Gateway	`payment_profile_vault_token` Example	`customer_vault_token` Example
Authorize.net	123456789	123456789
Beanstream/Bambora:	A1234FE123f123456F12DF1CDA1234a1
Braintree Blue (v2)	60428388 *1
Chase Paymentech Orbital	123456789
CyberSource	1234567890123456789012
Elavon	1234567890123456
eWay Rapid	0000010012345678
First Data	0123456789012345
Litle&Co Vantiv	[unknown]
Windcave	0000020000123456
PinPayments	cus_cAlS1vLNjRh1fFBk1-Abcf
QuickPay	12345678
Square (legacy only)	CABCDP9UzqXumx8uC_iAtQhdXjIgAQ”
Stripe Connect	cus_1ie1SbGBevCW0A
TrustCommerce	Z1RYBA
Moneris Solutions	[unknown]
NMI	783765937
Adyen	1415816459891180	chargify_14 *2
GoCardless	MD000B2S6QED0V	CU000BDK60TJWA
BlueSnap	`1111\|VISA\|21112765` *2	`28436055` *3

*1 For Braintree Blue, please provide the vault_token parameter with the value from Braintree’s “Customer ID” rather than the “Payment Method Token”. *2 For Adyen, Advanced Billing created payment profiles will have customer_vault_token set to chargify_ then the ID of the customer. This corresponds to the shopper_reference in Adyen, so if you are importing existing recurring profiles from Adyen ensure you map shopper_reference to the customer_vault_token field.

*2 For BlueSnap, the vault_token is the last-4 and card type plus the merchant managed subscription id. Please contact support if you do not already have merchant-managed subscriptions stored in BlueSnap.

*3 For BlueSnap, please provide the vaulted shopper id as the customer_vault_token.

Required Country Format

Advanced Billing requires that you use the ISO standard country codes when formatting the import file.

Countries should be formatted as 2 characters. For more information, please see the following Wikipedia article on ISO_3166-1.

Required State Format

Advanced Billing requires that you use the ISO standard state codes when formatting the import file.

US States (2 characters): ISO_3166-2
States outside the US (2-3 characters): To find the correct state codes outside of the US, please go to ISO_3166-1 and click on the link in the “ISO 3166-2 codes” column next to the country you wish to populate.

Component Format

At this time we only support importing components via ID's.

In order for the import tool to handle importing components we require the headers to be formatted in a specific way:

kind_ then component_id then the id of the component between []

Altogether it looks something like:

quantity_component_id[123]

Supported kind_’s are:

metered / quantity / on_off

The kind, along with the component_id can be found when viewing your list of components:

In addition to allocating to a component you can optionally pass price_point_id[] to allocate to a specific price point. As an example of how to include price point:

quantity_component_id[123]price_point_id[1]

The id for a price point can be found when editing the component itself (Catalog -> Products -> Click edit button on component)

If price_point_id[] isn’t passed in the header we will utilize the default price point for the component.

Required Custom Fields Format

Custom Fields need to be imported in a format: resource - customer or subscription, depending on which resource is the custom field attached to, then metafield_id, then [] with the id of the custom field inside the brackets. All together it will look like: subscription_metafield_id[1234] or customer_metafield_id[4567] Supported resources are: subscription and customer.

You can find the ID and the resource type when viewing the list of Custom Fields:

If the custom field ID or resource will be incorrect, the subscription and/or customer will be created without the custom field that had an error.

Example Field Values

The following is an example of the fields for each column of the CSV file for a basic import of subscriptions with existing tokens using the Advanced Billing test gateway.

`product_handle`	basic
`customer_first_name`	John
`customer_last_name`	Doe
`customer_email`	johndoe@chargify.com
`customer_address`	123 Main Street
`customer_city`	Anywhere
`customer_state`	NY
`customer_zip`	11111
`customer_country`	US
`customer_organization`	John Doe Inc
`payment_profile_first_name`	John
`payment_profile_last_name`	Doe
`payment_profile_billing_address`	123 Main Street
`payment_profile_billing_city`	Anywhere
`payment_profile_billing_state`	NY
`payment_profile_billing_zip`	11111
`payment_profile_billing_country`	US
`next_billing_at`	NOW
`payment_profile_current_vault`	bogus
`payment_profile_vault_token`	1
`payment_profile_last_four`	2345
`payment_profile_expiration_month`	11
`payment_profile_expiration_year`	2017
`payment_profile_card_type`	visa
`metered_component_id[123]`	22
`subscription_metafield_id[1234]`	Blue
`customer_metafield_id[4567]`	Orange

The system will reject all CSV files which are formatted incorrectly. The most common formatting issues related to illegal characters such as commas or foreign symbols/characters.

Import Process

Browse your computer for your CSV file and upload it

The CSV can take several minutes to completely process

Troubleshooting

Sometimes, the CSV file entered is formatted incorrectly, contains invalid headers, or is empty. In these cases, an error is returned when the CSV is initially submitted. The most common errors are this step are from non-UTF-8 CSV files.

If you are receiving an error such as the one above, it’s likely that the CSV file was opened, edited, and saved within a spreadsheet program, such as Excel or Numbers. When using these programs, please use the “Export” functionality to export a new UTF-8 CSV each time any changes are made. Alternatively, a text editor can be used for smaller updates, as it will maintain the UTF-8 CSV format.

Once the system has determined the file is valid, errors messages will be generated if any individual subscriptions fail. In the case of the screenshot below, Angela Test’s subscription on line number one was created successfully, but the subscription on line number two failed as their product handle does not exist.

Note: The import job is aborted if 10 successive entries fail to create a subscription. This can happen if the data is not formatted correctly, or if the gateway declines the initial authorization or charge.

When one or more subscriptions fail, you can upload the same CSV file after making corrections. The system will ignore any subscriptions which were imported successfully. There is no need to remove those entries from the CSV file.

Please open a support ticket if you require assistance. You can also reach us via email at support@maxio.com.