Data Migration to Chargify

About

This help article applies to customers who are migrating to Chargify with the assistance of Chargify's Onboarding Team.


The 3 Phases of Data Migration

  1. Prepare Your Data in Chargify Smart Templates. Once there are no red errors in your Smart Template, this phase is complete.
  2. Chargify runs your Test Import(s), you fix any data errors, and confirm the results using these helpful tips. Once the result is confirmed, this phase is complete.
  3. Chargify runs your Live Import

Chargify Smart Templates

Smart Templates help validate your existing data, so it is compatible with Chargify. Make a copy to your own Google Drive Account. Do not delete columns, modify column names, or add new columns, unless specifically documented.

Screen_Shot_2021-10-20_at_3.04.05_PM.png

Migration Type Description Templates & Samples
Standard Customers and Subscriptions The standard import template. Best when your business model is: 1 customer, 1 subscription, with 1 optional payment profile.

Templates (2):
Create Subscriptions (standard)
Create Subscriptions w/ Custom Pricing (standard)

Samples:
View samples

Advanced Customers and Subscriptions Any customer/subscription migration scenario that falls outside the standard. Most commonly used for Customer Hierarchies and Subscription Groups. First, your customers are imported. Then, your subscriptions are imported. Templates (3):
Create Customers (advanced)
Create Subscriptions (advanced)
Create Subscriptions w/ Custom Pricing (advanced)


Samples:
Customer Samples
Subscription Samples
Catalog Products, Product Price Points, Components, Component Price Points, and Coupons.

Templates (5):
Products
Components
Coupons
EBB Segments
Product Families

Samples:
See templates for examples

Invoices Import backdated ad-hoc invoices, and optionally attempt a charge.

Important:
If you also use SaaSOptics, use the SaaSOptics invoice import. Ask your Implementation Consultant for more details. 

If you are a Chargify-only user, or need to import an invoice that will be charged by a payment gateway, use this invoice import.

Templates (1):
Invoices

Samples:
See templates for examples

Template Documentation

Subscriptions - Create Subscriptions (standard)
Field Name Description Validation
Status
Do not edit
The import result is logged here. Allowed values: success, error, pending, or blank.
Result
Do not edit
The import result is logged here. If success, a link to the created Chargify object is listed. If error, the error message is listed.  
ChargifyNextRenewal
Do not edit
The amount that will be charged to the subscription on the next renewal. For example, $10.00 will simply show as "10.00". Compare this to your Expected Renewal Amount. See Comparing Next Billing Amounts for more information.  

YourExpectedRenewal
Optional, but recommended

The amount that you expect to charge the subscription on the next renewal. If you have these values, it is highly recommended to put them here. See Comparing Next Billing Amounts for more information.  
create_subscription
Required
When this field is set to TRUE, it expresses intent to create a subscription record in Chargify. Set to TRUE to enable Smart Template Validation.
organization_name
Optional
The organization name.  
customer_reference
Optional
The unique customer value to assign the customer. Must be unique
first_name
Required
The primary contact's first name  
last_name
Required
The primary contact's last name  
email
Required
The primary contact's email address Must be a valid email address format.
cc_emails
Optional
A comma separated list of email addresses, up to 5 allowed. Must be a comma separated list of emails, all with valid email address format.
phone
Optional
The primary contact's phone number  
shipping_address
Optional
Shipping Address. For example, 123 Main St.  
shipping_address
Optional
Shipping Address 2. For example, Suite 101.  
shipping_address_2
Optional
If shipping_address has a value, this field is required.  
shipping_city
Conditionally required
If shipping_address has a value, this field is required. The value must be the 2 letter ISO CODE with capital letters. For example, CA for California, or NY for New York. Don't have ISO codes?
shipping_state
Conditionally required
If shipping_address has a value, this field is required.  
shipping_zip
Conditionally required
If shipping_address has a value, this field is required. If vat_number has a value, this field is required. The value must be the 2 letter ISO CODE with capital letters. For example, US for United States, or FR for France. Don't have ISO codes?
tax_exempt
Optional
If a customer is tax exempt Allowed values: TRUE, FALSE.
vat_number
Optional
The VAT number. Chargify does not attempt validate the actual VAT number itself until the first billing of the subscription. Please make sure this value is correct. If you provide this value, you must provide a shipping_country. When imported, Chargify will strip the letters (DE123456789 becomes 123456789). The value must be a valid VAT number format (eg: DE123456789)
verified
Optional
If a customer is verified for ACH payments. Allowed values: TRUE, FALSE.
locale
Optional
Handles language settings for invoices. To view these values, go to Config > Settings > Language Settings in Chargify. Must have the syntax aa or aa-BB. For example, fr is French and fr-CA is French Canada.
custom_field_
customer[Name]
Optional
Custom Fields attached to the Chargify Customer Record. For example, if your Custom Field has the name "System Setting", the column header would be custom_field_customer[System Setting]. Add more Custom Field columns as needed. Make sure that these custom fields are already created in your Chargify Site.  
create_payment_profile
Required
When this field is set to TRUE, it expresses intent to create a payment profile record in Chargify for this customer. Allowed values: TRUE, FALSE. Set to TRUE to enable Smart Template Validation for payment profile fields.
If create_payment_profile TRUE, the following fields apply:
payment_profile_type
Required
Determines the type of payment profile to be created. Based on the type, fill out the relevant fields in the Smart Template. Allowed values: credit_card, bank_account, paypal_account.
current_vault
Required
Must be set to the correct gateway. Allowed values: bogus, authorizenet, beanstream, bpoint, braintree_blue, cybersource, elavon, eway, eway_rapid_std, firstdata, litle, moneris, nmi, payment_express, pin, quickpay, square, stripe_connect, trust_commerce, adyen, gocardless
gateway_handle
Conditionally required
If using the multigateway feature in Chargify, set the gateway_handle to route the payment method to the specific gateway. Note: this field is only used for live imports, and is ignored for test imports.  
vault_token
Required
The vault token from the gateway. See vault token examples.
  • stripe_connect - must begin with cus_, followed by letters/numbers

  • bluesnap - must follow {last 4}|{card type}|{integer}

  • braintree_blue (and several others) - must be all numbers

  • all else - cannot be blank and cannot contain spaces

customer_vault_token
Conditionally required
If current_vault is authorizenet, square, adyen, or gocardless, a customer vault token is required.  
credit_card_first_name
Conditionally required
The credit card holder's first name. Required if payment_profile_type is credit_card.  
credit_card_last_name
Conditionally required
The credit card holder's last name. Required if payment_profile_type is credit_card.  
last_four
Conditionally required
The last four digits on the credit card. Required if payment_profile_type is credit_card. Must be 4 digits, with a value between 0000-9999.
card_type
Conditionally required
The card type. Required if payment_profile_type is credit_card. Allowed values are: american_express, discover, master, visa, jcb, diners_club, forbrugsforeningen, dankort, maestro, switch, solo.
exp_month
Conditionally required
The expiration month of the credit card. Required if payment_profile_type is credit_card. Must be a number between 1 and 12.
exp_year
Conditionally required
The expiration year of the credit card. Required if payment_profile_type is credit_card. Must be a 4 digit year.
bank_account_first_name
Conditionally required
Bank account first name. Required if payment_profile_type is bank_account.  
bank_account_last_name
Conditionally required
Bank account last name. Required if payment_profile_type is bank_account.  
bank_name
Conditionally required
The name of the bank where the customer’s account resides. Required if payment_profile_type is bank_account.  
bank_account_last_four
Optional
The last four digits of the bank account number.  
bank_routing_last_four
Optional
The last four digits of the bank routing number.  
billing_address
Conditionally required
The address of the payment profile. Required if your subscription' require Billing Address. If a value is present, validations for other billing address fields will show in the spreadsheet.
billing_address_2
Conditionally required
The address2 of the payment profile. eg: Suite 101. Required if your subscriptions require Billing Address.  
billing_city
Conditionally required
The city of the payment profile. Required if your subscriptions require Billing Address.  
billing_state
Conditionally required
The state or province of the payment profile. Required if your subscriptions require Billing Address. The value must be the 2 letter ISO CODE with capital letters. For example, CA for California, or NY for New York. Don't have ISO codes?
billing_country
Conditionally required
The country of the payment profile. Required if your subscriptions require Billing Address. The value must be the 2 letter ISO CODE with capital letters. For example, US for United States, or FR for France. Don't have ISO codes?
billing_zip
Conditionally required
The zip code of the payment profile. Required if your subscriptions require Billing Address.  
The following fields apply to all subscriptions:
currency
Required
The 3 letter currency code.  

payment_collection_method
Required

Determines payment collection method. Allowed values: automatic, remittance, prepaid.
previous_billing_at
Optional, but recommended
Not required, but recommended. Must be a date in the past, yesterday or earlier.
next_billing_at
Required
The next renewal date of the subscription. Must be a date in the future, tomorrow or later.
net_terms
Optional
If set, must be a number, 0 to 180. Blank means no net terms apply.  
service_credit_balance
Optional
The service credit balance - added to the subscription after it is created. If set, must be a number larger than 0. For example, if the amount is $10.12, enter "10.12". If no service credit should be applied, leave this field blank.  
prepayment_balance
Optional
The prepayment balance - added to the subscription after it is created. If set, must be a number larger than 0. For example, if the amount is $10.12, enter "10.12". If no prepayment should be applied, leave this field blank.  
product_handle
Required
The handle of the product.  
product_price_
point_handle
Optional
The product price point handle of the product. If blank, the default product price point will be used.  
coupon_code_1
Optional
The coupon code to apply to the subscription. If more than 1 code is needed, insert a new column after this one, and call it coupon_code_2.

Allowed values:

Letters, numbers, %@+-\_, or .

component_1
Optional
The component handle or ID.  
componentPricepoint_1
Optional
The component pricepoint handle or ID. A blank value can represent the default pricepoint.  
componentQuantity_1
Conditionally required

This field determines if the subscription is assigned component_1. If this value is blank, the subscription is not assigned the component.

 
custom_field_
subscription[Name]
Optional
Custom Fields attached to the Chargify Subscription Record. For example, if your Custom Field has the name "Previous System Subscription ID", the column header would be custom_field[Previous System Subscription ID]. Add more Custom Field columns as needed. Make sure that these custom fields are already created in your Chargify Site.  
Subscriptions - Create Subscriptions w/ Custom Pricing (standard)

This import type introduces custom per unit component pricing. The key fields are below. For all other fields, see Subscriptions - Create Subscriptions (standard). 

Supported:
- Custom per unit component pricing (eg: 1.50/unit, supports up to 8 decimal places)
- Import custom rates and catalog rates (eg: a subscription has 2 line items, one with a custom rate, and one with a catalog rate)

Unsupported:
- Custom product pricing (this will be added in the future when the custom product UI is available)
- Custom on/off component pricing. Use a quantity-based component instead.

Field Name Description Validation
component_1
Required
The component handle or ID.  
componentPricepoint_1
Optional
The component pricepoint handle or ID. A blank value can represent the default pricepoint.  
componentCustomPrice_1
Optional
The custom per unit price for a component. Supports up to 8 decimal places. Do not use a currency symbol, only enter the number, such as 5, 5.00, 5.55, or 0.00375. If the currency you are using, such as EUR, is expressed with a comma (such as 5,55), still pass a decimal value of 5.55  
componentQuantity_1
Conditionally required

This field determines if the subscription is assigned component_1. If this value is blank, the subscription is not assigned the component.

 
Customers - Create Customers (advanced)
Field Name Description Validation
Status
Do not edit
The import result is logged here. Allowed values: success, error, pending, or blank.
Result
Do not edit
The import result is logged here. If success, a link to the created Chargify object is listed. If error, the error message is listed.  
create_customer
Required
When this field is set to TRUE, it expresses intent to create a customer record in Chargify. Set to TRUE to enable Smart Template Validation.
organization_name
Optional
The organization name.  
import_identifier_
customer_reference
Required
The primary identifier that represents the customer. This field will also be used when creating subscriptions. This field will also map to the Chargify customer_reference value. Must be unique
customer_type
Required
Determines the type of customer to migrate. Allowed values: normal, child, parent, grandparent.
has_parent
Required

Determines if a customer has a parent. If you are migrating a normal customer, set this value to FALSE. If you are importing a child/parent customer that has a parent/grandparent respectively, set this value to TRUE. The parent will be assigned based on the parent_reference value.

Allowed values: TRUE, FALSE.
parent_name
Optional
Use this value to put the parent organization name. This field is only meant to help you fill out the CSV file.  
parent_reference
Conditionally required
If has_parent is TRUE, this field is required. This field indicates the reference value of the parent. For example, if you are importing a child customer with reference 123, and want to attach it to the parent with reference 456, you would set this fields value to 456.  
first_name
Required
The primary contact's first name  
last_name
Required
The primary contact's last name  
email
Required
The primary contact's email address Must be a valid email address format.
cc_emails
Optional
A comma separated list of email addresses, up to 5 allowed. Must be a comma separated list of emails, all with valid email address format.
phone
Optional
The primary contact's phone number  
shipping_address
Optional
Shipping Address. For example, 123 Main St.  
shipping_address_2
Optional
Shipping Address 2. For example, Suite 101.  
shipping_city
Conditionally required
If shipping_address has a value, this field is required.  
shipping_state
Conditionally required
If shipping_address has a value, this field is required. The value must be the 2 letter ISO CODE with capital letters. For example, CA for California, or NY for New York. Don't have ISO codes?
shipping_zip
Conditionally required
If shipping_address has a value, this field is required.  
shipping_country
Conditionally required
If shipping_address has a value, this field is required. If vat_number has a value, this field is required. The value must be the 2 letter ISO CODE with capital letters. For example, US for United States, or FR for France. Don't have ISO codes?
tax_exempt
Optional
If a customer is tax exempt Allowed values: TRUE, FALSE.
vat_number
Optional
The VAT number, such as DE123456789. Chargify does not attempt validate the actual VAT number itself until the first billing of the subscription. Please make sure this value is correct. If you provide this value, you must provide a shipping_country. When imported, Chargify will strip the letters (DE123456789 becomes 123456789). The value must be a valid VAT number format (eg: DE123456789)
verified
Optional
If a customer is verified for ACH payments. Allowed values: TRUE, FALSE.
locale
Optional
Handles language settings for invoices. To view these values, go to Config > Settings > Language Settings in Chargify. Must have the syntax aa or aa-BB. For example, fr is French and fr-CA is French Canada.
custom_field[Name]
Optional
Custom Fields attached to the Chargify Customer Record. For example, if your Custom Field has the name "System Setting", the column header would be custom_field[System Setting]. Add more Custom Field columns as needed. Make sure that these custom fields are already created in your Chargify Site.  
create_payment_
profile
Required
When this field is set to TRUE, it expresses intent to create a payment profile record in Chargify, and associate it with the customer. Set to FALSE if the customer has no payment profile. Allowed values: TRUE, FALSE. If TRUE, Smart Template Validation is enabled.
If create_payment_profile TRUE, the following fields apply:
payment_profile_type
Required
Determines the type of payment profile to be created. Based on the type, fill out the relevant fields in the Smart Template. Allowed values: credit_card, bank_account, paypal_account.
current_vault
Required
Must be set to the correct gateway. Allowed values: bogus, authorizenet, beanstream, bpoint, braintree_blue, cybersource, elavon, eway, eway_rapid_std, firstdata, litle, moneris, nmi, payment_express, pin, quickpay, square, stripe_connect, trust_commerce, adyen, gocardless
gateway_handle
Conditionally required
Set the gateway_handle to route the payment method to the specific gateway. Required if using the multigateway feature in Chargify. Note: this field is only used for live imports, and is ignored for test imports.  
vault_token
Required
The vault token from the gateway. See vault token examples.
  • stripe_connect - must begin with cus_, followed by letters/numbers

  • bluesnap - must follow {last 4}|{card type}|{integer}

  • braintree_blue (and several others) - must be all numbers

  • all else - cannot be blank and cannot contain spaces

customer_vault_token
Conditionally required
If current_vault is authorizenet, square, adyen, or gocardless, a customer vault token is required.  
credit_card_first_name
Conditionally required
The credit card holder's first name. Required if payment_profile_type is credit_card.  
credit_card_last_name
Conditionally required
The credit card holder's last name. Required if payment_profile_type is credit_card.  
last_four
Conditionally required
The last four digits on the credit card. Required if payment_profile_type is credit_card. Must be 4 digits, with a value between 0000-9999.
card_type
Conditionally required
The card type. Required if payment_profile_type is credit_card. Allowed values are: american_express, discover, master, visa, jcb, diners_club, forbrugsforeningen, dankort, maestro, switch, solo.
exp_month
Conditionally required
The expiration month of the credit card. Required if payment_profile_type is credit_card. Must be a number between 1 and 12.
exp_year
Conditionally required
The expiration year of the credit card. Required if payment_profile_type is credit_card. Must be a 4 digit year.
bank_account_first_name
Conditionally required
Bank account first name. Required if payment_profile_type is bank_account.  
bank_account_last_name
Conditionally required
Bank account last name. Required if payment_profile_type is bank_account.  
bank_name
Conditionally required
The name of the bank where the customer’s account resides. Required if payment_profile_type is bank_account.  
bank_account_last_four
Optional
The last four digits of the bank account number.  
bank_routing_last_four
Optional
The last four digits of the bank routing number.  
billing_address
Conditionally required
The address of the payment profile. Required if your subscription' require Billing Address.  
billing_address_2
Conditionally required
The address2 of the payment profile. eg: Suite 101. Required if your subscriptions require Billing Address.  
billing_city
Conditionally required
The city of the payment profile. Required if your subscriptions require Billing Address.  
billing_state
Conditionally required
The state or province of the payment profile. Required if your subscriptions require Billing Address. The value must be the 2 letter ISO CODE with capital letters. For example, CA for California, or NY for New York. Don't have ISO codes?
billing_country
Conditionally required
The country of the payment profile. Required if your subscriptions require Billing Address. The value must be the 2 letter ISO CODE with capital letters. For example, US for United States, or FR for France. Don't have ISO codes?
billing_zip
Conditionally required
The zip code of the payment profile. Required if your subscriptions require Billing Address.  
Subscriptions - Create Subscriptions (advanced)
Field Name Description Validation
Status
Do not edit
The import result is logged here. Allowed values: success, error, pending, or blank.
Result
Do not edit
The import result is logged here. If success, a link to the created Chargify object is listed. If error, the error message is listed.  
ChargifyNextRenewal
Do not edit
The amount that will be charged to the subscription on the next renewal. For example, $10.00 will simply show as "10.00". Compare this to your Expected Renewal Amount. See Comparing Next Billing Amounts for more information.  

YourExpectedRenewal
Optional, but recommended

The amount that you expect to charge the subscription on the next renewal. If you have these values, it is highly recommended to put them here. See Comparing Next Billing Amounts for more information.  
create_subscription
Required
When this field is set to TRUE, it expresses intent to create a subscription record in Chargify, and attach it to the assigned import_identifier_customer_reference. Set to TRUE to enable Smart Template Validation.
organization_name
Optional
The organization name. This field is ignored when importing subscriptions, but can be helpful as a read-only value to help you fill out the template.  
import_identifier_
customer_reference
Required
The primary identifier that represents the customer. This field will also be used when creating subscriptions. This field will also map to the Chargify customer_reference value.  
who_pays
Required
Determines the payer. If not using hierarchies, always set to 'self'. Allowed values: self, parent, eldest.
invoice_type
Required
Determines the invoice type. Allowed values: normal, consolidated.
align
Optional

If who_pays is true, and invoice_type is consolidated, align is used. If TRUE, all subscriptions in the group will be aligned to the same billing date (most common). If FALSE, the subscription will use its own next billing date. Defaults to TRUE.

Allowed values: TRUE, FALSE.
receive_invoice_emails
Required
TRUE or FALSE Allowed values: TRUE, FALSE.
subscription_reference
Optional
If used, must be unique for each subscription.  
currency
Required
The 3 letter currency code.  
payment_collection_
method
Required
Determines the payment collection method for the subscription.

If this field is set to automatic, and the subscription requires a payment method, the payment method on file for who_pays will be used. Otherwise, if no payment method is required, the subscription will still be created.
Allowed values: automatic, remittance, prepaid.
previous_billing_at
Optional, but recommended
Not required, but recommended. Must be a date in the past, yesterday or earlier.
next_billing_at
Required
The next renewal date of the subscription. Must be a date in the future, tomorrow or later.
net_terms
Optional
If set, must be a number, 0 to 180. Blank means no net terms apply.  
service_credit_balance
Optional
The service credit balance - added to the subscription after it is created. If set, must be a number larger than 0. For example, if the amount is $10.12, enter "10.12". If no service credit should be applied, leave this field blank.  
prepayment_balance
Optional
The prepayment balance - added to the subscription after it is created. If set, must be a number larger than 0. For example, if the amount is $10.12, enter "10.12". If no prepayment should be applied, leave this field blank.  
product_handle
Required
The handle of the product.  
product_price_
point_handle
Optional
The product price point handle of the product. If blank, the default product price point will be used.  
coupon_code_1
Optional
The coupon code to apply to the subscription. If more than 1 code is needed, insert a new column after this one, and call it coupon_code_2.

Allowed values:

Letters, numbers, %@+-\_, or .

component_1
Optional
The component handle or ID.  
componentPricepoint_1
Optional
The component pricepoint handle or ID. A blank value can represent the default pricepoint.  
componentQuantity_1
Conditionally required

This field determines if the subscription is assigned component_1. If this value is blank, the subscription is not assigned the component.

 
custom_field[Name]
Optional
Custom Fields attached to the Chargify Subscription Record. For example, if your Custom Field has the name "System Setting", the column header would be custom_field[System Setting]. Add more Custom Field columns as needed. Make sure that these custom fields are already created in your Chargify Site.  
Subscriptions - Create Subscriptions w/ Custom Pricing (advanced)

This import type introduces custom per unit component pricing. The key fields are below. For all other fields, see Subscriptions - Create Subscriptions (advanced). 

Supported:
- Custom per unit component pricing (eg: 1.50/unit, supports up to 8 decimal places)
- Import custom rates and catalog rates (eg: a subscription has 2 line items, one with a custom rate, and one with a catalog rate)

Unsupported:
- Custom product pricing (this will be added in the future when the custom product UI is available)
- Custom on/off component pricing. Use a quantity-based component instead.

Field Name Description Validation
component_1
Required
The component handle or ID.  
componentPricepoint_1
Optional
The component pricepoint handle or ID. A blank value can represent the default pricepoint.  
componentCustomPrice_1
Optional
The custom per unit price for a component. Supports up to 8 decimal places. Do not use a currency symbol, only enter the number, such as 5, 5.00, 5.55, or 0.00375. If the currency you are using, such as EUR, is expressed with a comma (such as 5,55), still pass a decimal value of 5.55  
componentQuantity_1
Conditionally required

This field determines if the subscription is assigned component_1. If this value is blank, the subscription is not assigned the component.

 
Catalog - Products
Field Name Description Validation
Status
Do not edit
The import result is logged here. Allowed values: success, error, pending, or blank.
Result
Do not edit
The import result is logged here. If success, a link to the created Chargify object is listed. If error, the error message is listed.  
product_name
Required
The name of the product. When a value is present, Smart Template validation is enabled.
description
Optional
The description of the product.  
product_family_id
Required
The ID of the product family.   
taxable
Required
Determines if the product, and all its price points, are taxable. Allowed values: TRUE, FALSE.
tax_code
Conditionally required
The tax code of the product. Required if taxable TRUE. Allowed values: digital, physical, or a specific Avalara Tax Code.
require_payment_method
Required
Determines if a payment method is required to subscribe to the product. Allowed values: TRUE, FALSE.
require_billing_address
Required
Determines if a billing address is required to subscribe to the product. Allowed values: TRUE, FALSE.
require_shipping_address
Required
Determines if a shipping address is required to subscribe to the product. Allowed values: TRUE, FALSE.
auto_create_signup_page
Required
Determines if a Chargify Public Signup Page (payment page) will be created for this product. Allowed values: TRUE, FALSE.
handle
Required
The API handle of this product. For example, if your product is "Bronze Plan" make your API handle "bronze-plan".  
attach_to
Required
When creating a new price point for a product, the attach to represents the handle of the product. The intent of this field is, "attach this new price point to...".  
price_point_name
Required
The name of the price point.  
price_point_handle
Required
If your price point is "10 each", enter a simple handle such as "pp_10_each". The handle must start with a letter.  
price
Required
The price of the price point.  
renew_every
Required
The number (interval) of renewal. If renewing every 1 month, this value should be "1".  
month_or_day
Required
The interval unit. If renewing every 1 month, this value should be "month". Allowed values: month, day.
trial_price
Conditionally required
The price of a trial period. If a free trial, enter 0.  
trial_interval
Conditionally required
The number (interval) of trial. If trial is 14 days, enter "14".  
trial_month_or_day
Conditionally required
The trial interval unit. If trial is 14 days, enter "day". Allowed values: month, day.
trial_type
Conditionally required
Determines how the trial behaves when complete. Allowed values: no_obligation, payment_expected.
expiration_interval
Optional
The number (interval) of expiration. If the product price point expires in 12 months, put "12".  
expiration_month_or_day
Conditionally required
The expiration interval unit. If the product price point expires in 12 months, put "month". Allowed values: month, day.
setup_fee_price
Optional
The setup fee of the price point.  
Catalog - Components
Field Name Description Validation
Status
Do not edit
The import result is logged here. Either success, error, pending, or blank.  
Result
Do not edit
The import result is logged here. If success, a link to the created Chargify object is listed. If error, the error message is listed.  
component_name
Required
The name of the component. When a value is present, Smart Template validation is enabled.
component_type
Required
The type of component to create. Allowed values: quantity_recurring, quantity_onetime, metered, on_off, event_based, prepaid_usage.
description
Optional
The description of the component.  
unit_name
Required
The unit name of what you sell. For example, if this component is "Messages", put "message" (singular, not plural).  
product_family_id
Required
The ID of the product family.   
metric_id
Conditionally required
If component_type is event_based, put the metric_id here. The metric_id value can be found in your Chargify account when viewing the metric.  
taxable
Required
Determines if the component, and all its price points, are taxable. Allowed values: TRUE, FALSE.
tax_code
Conditionally required
The tax code of the component. Required if taxable TRUE. Allowed values: digital, physical, or a specific Avalara Tax Code.
allow_fractional_quantities
Required
Determines you can allocate fractional quantities to a subscription with this component. For example, if you sell Licenses, and sometimes sell 4.5 licenses, put TRUE. Otherwise, put FALSE. Allowed values: TRUE, FALSE.
hide_date_range
_on_invoice
Required
Determines if the billing period's date range shows under this line item on the invoice. Allowed values: TRUE, FALSE.
allow_billing_
portal_updates
Required
Determines if a user can increase/decrease the quantity of this component in the Billing Portal. (This field is ignored for metered components and event based components) Allowed values: TRUE, FALSE.
upgrade_charge
Optional
Controls mid-period upgrades for this component. Set full, prorated, or none. Leave blank to use your default site settings. This field only applies to quantity-based components (recurring and one-time), and on-off components. For example, if a user license costs $10/ea, and your customer adds 1 license mid-period, full would charge $10, prorated would charge a prorated amount, and none would be free. Allowed values: full, prorated, none.
downgrade_credit
Optional

Controls mid-period downgrades for this component. Set full, prorated, or none. Leave blank to use your default site settings. This field only applies to quantity-based components (recurring and one-time), and on-off components. For example, if a user license costs $10/ea, and your customer removes 1 license mid-period, full would credit $10, prorated would credit a prorated amount, and none would not apply a credit.

Allowed values: full, prorated, none.
handle
Required
The API handle of this component. For example, if your component is "Premium Licenses" make your API handle "premium-licenses".  
attach_to
Required
When creating a new price point for a component, the attach to represents the handle of the component. The intent of this field is, "attach this new price point to...".  
price_point_name
Required
The name of the price point.  
price_point_handle
Required
If your price point is "10 each", enter a simple handle such as "pp_10_each". The handle must start with a letter.  
pricing_scheme
Required
The pricing scheme of the component price point.

-- If On/Off Price Point --
If importing an on/off price point, leave the pricing_scheme blank. Smart template may show red, but the imported record will succeed.
Allowed values: per_unit, volume, tiered, stairstep.
per_unit_price
Conditionally required
If pricing scheme is per_unit (or the component type is on_off), enter the per_unit price.

-- If EBB Segments --
The price listed here will become your default segment price if no segment match is found.
 
starting_quantity_1
Conditionally required
If pricing scheme is volume, tiered, or stairstep, put the starting quantity of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "1" here. If more brackets are needed, copy paste these 3 columns and title the header "starting_quantity_2".  
ending_quantity_1
Conditionally required
If pricing scheme is volume, tiered, or stairstep, put the ending quantity of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "5" here. If more brackets are needed, copy paste these 3 columns and title the header "ending_quantity_2".  
price_1
Conditionally required
If pricing scheme is volume, tiered, or stairstep, put the price of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "10" here. If more brackets are needed, copy paste these 3 columns and title the header "price_2".

-- If EBB Segments --
The price listed here will become your default segment price if no segment match is found.
 
Prepaid components 
You can skip or delete these fields if not importing prepaid components. If you are importing them, the following fields apply.
auto_renew_units
Required
The number of units applied to the subscription will auto-renew (replenish) each billing cycle. If TRUE, a subscription signs up with 5 units, uses the 5 units, and the next billing cycle will start with 5 units. If FALSE, the subscription will start the next billing cycle with 0 units. Allowed values: TRUE, FALSE.
allow_rollover
Required
Rollover allows unused units to rollover into the next billing cycle. If TRUE, a subscription signs up with 5 units, uses the 3 units, and the next billing cycle will start with 7 units (the auto renew of 5, plus the 2 rollover). If FALSE, the subscription will start the next billing cycle with 5 units (the auto renew of 5, plus 0 rollover). Allowed values: TRUE, FALSE.
expire_after
Optional
If units expire, set the expiration. For example, if units expire in 90 days, put "90" in this field, and "day" in the month_or_day field.  
month_or_day
Conditionally required
If you set expire_after, set this field to "month" or "day". For example, if units expire in 90 days, put "90" in expire_after, and "day" in this field. Allowed values: month, day.
overage_pricing_scheme
Required
The overage pricing scheme of the prepaid usage price point. Allowed values: per_unit, volume, tiered, stairstep.
overage_per_unit_price
Conditionally required
If overage pricing scheme is per_unit, enter the per_unit price.  
overage_starting_quantity_1
Conditionally required
If overage_pricing_scheme is volume, tiered, or stairstep, put the starting quantity of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "1" here. If more brackets are needed, copy paste these 3 columns and title the header "overage_starting_quantity_2".  
overage_ending_quantity_1
Conditionally required
If overage_pricing_scheme is volume, tiered, or stairstep, put the ending quantity of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "5" here. If more brackets are needed, copy paste these 3 columns and title the header "overage_ending_quantity_2".  
overage_price_1
Conditionally required
If overage_pricing_scheme is volume, tiered, or stairstep, put the price of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "10" here. If more brackets are needed, copy paste these 3 columns and title the header "overage_price_2".  
Catalog - Coupons
Field Name Description Validation
Status
Do not edit
The import result is logged here. Either success, error, pending, or blank.  
Result
Do not edit
The import result is logged here. If success, a link to the created Chargify object is listed. If error, the error message is listed.  
name
Required
The name of the coupon. When a value is present, Smart Template validation is enabled.
code
Required
The coupon code. This value must be unique across all coupon codes in your Chargify Site.  
description
Optional
The description of the coupon.  
product_family_id
Required
The ID of the product family.   
percentage_discount
Conditionally required
If your coupon is a percentage based discount, enter an integer value 1 to 100 here. If you have a 100% off coupon, enter "100".  
flat_discount
Conditionally required
If your coupon is a flat rate discount, enter a money value such as "10.50". The currency will be determined by your primary currency in your Chargify Settings.  
stackable
Required
Determines if the coupon can be stacked (combined) with other coupons on a single subscription. Allowed values: TRUE, FALSE.
recurring
Required
Determines if the coupon is always used on a recurring basis (TRUE) or if it is only used once (FALSE). Allowed values: TRUE, FALSE.
review_after_import
Optional
If you want to modify the coupon after import, enter TRUE. When viewing your imported coupons in Chargify, the name will contain the word "EDIT" so you can see which ones you need to review. Allowed values: TRUE, FALSE.
Catalog - EBB Segments
Field Name Description Validation
Status
Do not edit
The import result is logged here. Either success, error, pending, or blank.  
Result
Do not edit
The import result is logged here. If success, a link to the created Chargify object is listed. If error, the error message is listed.  
component_name
Required
The name of the component. When a value is present, Smart Template validation is enabled.
metric_id
Required
The id of the metric in Chargify. View the metric to find this value.  
component_handle
Required
The handle of the EBB component.  
pricepoint_handle
Required
The handle of the EBB component pricepoint with which the segment should be associated.  
property_1
Required
The segment's first property.  
property_2
Optional
The segment's second property.  
property_3
Optional
The segment's third property.  
property_4
Optional
The segment's fourth property.  
pricing_scheme
Required
The pricing scheme of the segment.  Allowed values: per_unit, volume, tiered, stairstep.
per_unit_price
Conditionally required
If pricing scheme is per_unit, enter the per_unit price.  
starting_quantity_1
Conditionally required
If pricing scheme is volume, tiered, or stairstep, put the starting quantity of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "1" here. If more brackets are needed, copy paste these 3 columns and title the header "starting_quantity_2".  
ending_quantity_1
Conditionally required
If pricing scheme is volume, tiered, or stairstep, put the ending quantity of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "5" here. If more brackets are needed, copy paste these 3 columns and title the header "ending_quantity_2".  
price_1
Conditionally required
If pricing scheme is volume, tiered, or stairstep, put the price of the bracket here. For example, if the first bracket is "1 to 5 units is $10", put "10" here. If more brackets are needed, copy paste these 3 columns and title the header "price_2".  
Catalog - Product Families
Field Name Description Validation
Status
Do not edit
The import result is logged here. Either success, error, pending, or blank.  
Result
Do not edit
The import result is logged here. If error, the error message is listed.  
name
Required
The name of the Product Family.  
description
Optional
The description of the Product Family.  
handle
Optional
The API handle of the Product Family.  
Invoices - Create Invoices
Field Name Description Validation
Status
Do not edit
The import result is logged here. Either success, error, pending, or blank.  
Result
Do not edit
The import result is logged here. If error, the error message is listed.  
Amount
Do not edit
The total amount, of the imported invoice, will be placed here. Verify your import by coming this actual total amount value, to your expected amount value that you provided in the total_amount column.  
Customer Details
create_invoice
Conditionally required
When this field is set to TRUE, it expresses intent to create an invoice in Chargify. If you are just adding a line item entry, and attaching it to an invoice, leave this field blank. Set to TRUE to enable Smart Template Validation for Customer Details and Invoice Data fields.
customer
Optional
A read-only field to simplify filling out the CSV file. Use it to put the name of the customer or company.  
sub_reference
Required
The subscription reference, on the subscription in Chargify, that will have the invoice.  
Invoice Data
id
Required
A custom id, any value of your choice, that represents the invoice. This id will be mapped to attach_to, to determine which line items are included on the invoice.  
total_amount
Optional
The total invoice amount, of the invoice you are importing. This value is not included in the import itself, but should be used to verify that your invoice imports are the total amount you expect. Compare this value to column C, Amount, when your import is finished. If your invoice is $100.50, enter 100.50 without the currency symbol.  
issue_date
Required
By default, invoices will be created with a issue date set to today. issue_date alters that. Only dates in the past can be sent. Must be YYYY-MM-DD format.
due_date
Required
The due date of the invoice. Must be YYYY-MM-DD format.
net_terms
Required. Do not edit.
The net terms for the invoice. Do not edit this field. Auto calculated by due_date minus issue_date.
attempt_charge
Required
If you want to create the invoice with no charge, set to no (most common).

If you want to attempt to charge the default payment method on file immediately upon invoice import, set to yes_attempt_a_charge (less common). If the payment fails, the invoice will remain 'Open', and if the subscription is Automatic, a retry will be attempted upon next renewal.
Allowed values: yes_attempt_a_charge, no.
Line Item Data
name
Required
The line item name that will appear on the invoice. Enables Smart Template Validation for line item fields.
quantity
Required
The quantity of the line item.   
unit_price
Required
The per unit cost, of each quantity, of the line item.  
Line Item Data Revenue Recognition
start_date
Required
The start date of the revenue recognition period, for the line item. Must be YYYY-MM-DD format.
end_date
Required
The end date of the revenue recognition period, for the line item. Must be YYYY-MM-DD format.
Attach Line Item to Invoice
attach_to
Required
The invoice id, from the id field. This field will map your line items to a specific invoice.  

 

Tips to Confirm Your Test Migration

Chargify will help you migrate the data in a Test Migration, and it is ultimately your responsibility to confirm the results, prior to the Live Migration. Below are some tips to help:

Tip Notes
Review Errors Chargify will provide the successes and errors in your Smart Template. Successes will contain a link to the newly created object so you can review them. If you have many, pick some that are representative of the whole. For errors, the exact error message will be listed and are typically self explanatory. 

Screen_Shot_2021-11-03_at_1.05.08_PM.png

Compare Next Billing Amounts

In your Smart Template results, compare the ChargifyNextRenewal to Your YourExpectedRenewal. Start by summing the columns individually and looking at the totals. If you know what the expected total should be, you can easily compare to the Chargify total. If it doesn't match, you can now find which one(s) do not match. Then, determine why using other methods in this Tips to Confirm Your Migration section. Typical reasons are: you missed data on a subscription, missed a coupon, assigned the wrong product, etc. 

Screen_Shot_2021-11-12_at_1.15.34_PM.png

Note: If you use multicurrency, and use automatic exchange rates, keep in mind that the ChargifyNextRenewal value is the next renewal at the time of the subscription creation. 

Compare Next Billing Amounts via Exports In your Chargify Site, go to Config on the left menu > Settings > CSV Exports and checkmark "Next Billing Amount".

Screen_Shot_2021-11-03_at_1.09.14_PM.png

Then, go to Billing on the left hand menu > Subscriptions and click Export. Allow time for this export to complete.

Screen_Shot_2021-11-03_at_1.11.31_PM.png

In the exported file, find the column named Estimated Renewal Amount. You can now use these values to compare to what you have in your current system. If you find discrepancies, view the record in Chargify and you can typically determine the cause. 
Compare the next billing amounts on a single subscription When viewing a subscription, you can see the next billing amount and the next renewal date.

Screen_Shot_2021-11-03_at_1.17.55_PM.png

Filter imported subscriptions for specific renewal dates Go to Billing on the left hand menu > Subscriptions. Using the filter, "Period Ends" of "01/01/2022 to "01/31/2022" means "filter for Jan 2022 renewals". From there, view subscriptions, run exports, etc. Feel free to use any other filters as well.
Screen_Shot_2021-11-03_at_1.19.30_PM.png

Preview the Next Invoice If you need to examine a subscription's next billing, try viewing the proforma invoice. When viewing the subscription simply click "Preview Proforma". You'll now see a preview invoice, and can easily spot if it is correct, if it's not, and why.

Screen_Shot_2021-11-12_at_10.38.06_AM.png
Preview the Next Invoice for Grouped Subscriptions Go to the group, scroll down, click 'Create New Proforma Invoice'. This will generate an invoice preview of the first group renewal.

 

FAQ

  • Can Chargify help me verify my data in test mode before the actual migration?
    Yes, that is the intent. Think of it like this: errors are hiding in your data. Chargify Smart Templates are the first level of unlocking these hidden errors. As you fill out the template(s) with your data, errors will emerge, and you can fix them. Once there are no Smart Template errors, Chargify will perform a test import and help uncover the additional errors hiding in your data, and put those errors back in your Smart Template for your review. From there, you can use these Tips To Confirm Your Test Migration. The intent is for Chargify to help you uncover as many errors as possible, so you fix them. As a result, the live migration will be as smooth as possible.

  • Can Chargify fill out the template(s) for me?
    No.
  • My current state and country data only has full names, not ISO Codes. What should I do?
    If you have "United States" instead of "US", and/or "California" instead of "CA", you can convert these in your Smart Template by hand, or do a ctrl+f replace.

  • Can "next billing at" be imported to schedule future billing once Chargify Smart Template subscription import occurs?
    Yes
     
  • Can a tokenized card be imported at the time using Chargify Smart Template customer/subscriptions import?
    Yes
Was this article helpful?
0 out of 0 found this helpful