Imports

The Subscriptions Import tool will allow you to import new subscriptions into Chargify 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 the API. Please see Subscriptions API Import for more information.

This is an advanced feature which 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@chargify.com or by phone at (800) 401-2414.

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

Sample XLSX Files

Chargify requires that you use one of the following example files to input data using the Subscription Import Tool.

Chargify 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 your customers’ payment details are stored in the secure vault of one of our supported gateways (new and existing Chargify merchants):

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).

XLSX files will need to be saved as CSV 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 create a subscription with a subscription state of Active.

  • You must disable all email notifications related to subscription creation if you do not want to alert your customers that you have created the subscription (signup emails, receipts, statements and billing portal invitations)

  • We recommend that you limit the number of subscriptions in each import to 100.

  • We recommend that you use the tool when our Tier 2 team is available to help with any issues (normally Monday-Thursday, 9a-5p Eastern).

  • 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 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.

  • CyberSource requires 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.

Chargify 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 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 default for payment profile first name)
  • customer_last_name (the customer’s last name - will become default for payment profile last name)
  • customer_email
  • next_billing_at (the first time you will bill your customer - 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 (Authorize.Net only)
  • payment_profile_last_four
  • payment_profile_expiration_month
  • payment_profile_expiration_year
  • payment_profile_card_type (Optional, see allowed values)
  • 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)
  • customer_address
  • customer_address_2
  • customer_city
  • customer_state (see format)
  • customer_zip
  • customer_country (see format)
  • customer_phone

Optional

  • customer_reference
  • coupon_code

Next Billing Date Format

The following date formats are equivalent and will work as input to next_billing_at:

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

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

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

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 fee. If you use a date into the future, the setup fee will not be collected.

Card Types

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

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

Vaults

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

  • authorizenet
  • trust_commerce
  • payment_express
  • beanstream
  • braintree_blue
  • quickpay
  • eway
  • eway_rapid_std
  • stripe_connect
  • pin
  • wirecard
  • bpoint
  • firstdata
  • elavon
  • cybersource
  • paymill
  • litle
  • moneris
  • nmi

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  
CyberSource 1234567890123456789012  
Elavon 1234567890123456  
eWay Rapid 0000010012345678  
First Data 0123456789012345  
Litle&Co Vantiv [unknown]  
PaymentExpress 0000020000123456  
Paymill pay_123ae123bc12ae123456789f  
PinPayments cus_cAlS1vLNjRh1fFBk1-Abcf  
QuickPay 12345678  
Stripe Connect cus_1ie1SbGBevCW0A  
TrustCommerce Z1RYBA  
Wirecard C123456789012345678901  
Moneris Solutions [unknown]  
NMI 783765937  

*1 For Braintree Blue, please provide the vault_token parameter with the value from Braintree’s “Customer ID” rather than the “Payment Method Token”.

Country Format

Please use ISO Standard country codes when formatting the import file.

Countries (2 characters): ISO_3166-1

State Format

Please use 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 country you wish to populate.

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 Chargify 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

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

Import Process

To import your file:

  • Click on Subscriptions tab

  • Select Subscription Import

  • Select New Import

  • Browse your computer for your CSV file

  • Process CSV

  • Subscription Created Successfully

Troubleshooting

The system will generate error messages when individual subscriptions fail. In this case, the customer’s credit card information was not entered correctly.

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@chargify.com or by phone at (800) 401-2414.