Customer Data Migration and Import
1. Two General Types of Migration/Import
1.1 Direct Import
If you have been using a Cheddar-compatible gateway with your existing solution, or you are able to transfer your customers' credit card numbers, it may be possible to migrate to Cheddar without requiring that your customers update their billing information. Using the Customer Import API method, it's possible to import existing customers along with their payment method without knowing full credit card numbers. Contact us for more information about migrations.
1.2 Natural Migration
A natural migration is the way to go if your current payment processing solution is incompatible with Cheddar or your current provider disallows transfer of your customers' card numbers. You may choose to start using Cheddar immediately for all customers or to develop a hybrid process wherein your customers are moved over to Cheddar over time as they update their method of payment. Contact us for more information about migrations.
Migrate All Customers at One Time
- Make sure your Cheddar account is set to allow new customers on paid plans without payment method. The default setting is to require a payment method. This option can be changed here: https://cheddargetter.com/admin/configuration/settings
- Using the API or GUI, create customer accounts in Cheddar without a payment method. In other words, just create the customers and subscribe them to one of your pricing plans. All you need to tell Cheddar is the basic info for a customer: name, email, planCode. See the official API doc for more info on the requirements: https://cheddargetter.com/developers#add-customer
- When creating an account, set the customer's first bill date in Cheddar to align with the customer's next bill date in your current solution. The relevant API parameter is
subscription[initialBillDate]. - Instruct your customers to update their billing information via your Cheddar solution prior to their next bill date.
- Email them directly with a link to their account page on your site or to a hosted payment page, depending on your solution.
- Or, use Cheddar's Bill Reminder auto-email.
- If a customer does not update their billing information prior to the next bill date, Cheddar will auto-cancel the customer's account. The customer can be re-enabled by updating their billing information.
Migrate Customers Over a Transition Period
This method requires some additional development in your application. The concept is similar to above but your application would continue billing customers via your old solution until they choose to update their method of payment. When the customer updates their payment method, the customer is moved to Cheddar.
Migrate Existing Customers in Cheddar to a New Payment Processor
If you're currently using Cheddar and have existing subscribers, there may come a time when you'd like to change your back-end payment processor but continue using Cheddar to bill those subscribers. In this case, we can set up a payment processor migration for you in a way that will facilitate natural migration to the new payment processor without requiring your subscribers to reenter their method of payment. Your existing subscribers will continue to be billed on the current payment processor but will be moved to the new payment processor as they update their method of payment. Any new subscribers will be added directly to the new payment processor. If you'd like to set up payment processor migration mode, please contact our support team and we'll get you going.
Depending on your current payment processor and your choice of new processor, it might be possible to accelerate this migration. Just ask and we'll work through the details with you.
2. Using the API to Import Customers
The API method customers/import may be used for both type of imports above. More information on the API call is available here.
2.1 Nested List
Up to 100 customers may be imported in one API call. Even if 1 customer is imported at a time, the data must be contained in a nested list. For example, here is how url encoded POST data for two customers might look:
cust_0%5Bcode%5D=cust_0&cust_0%5BgatewayToken%5D=imported_token&cust_0%5BfirstName%5D=First&cust_0%5BlastName%5D=Imported&cust_0%5Bemail%5D=first%40example.com&cust_0%5Bsubscription%5D%5BplanCode%5D=plan_code&cust_0%5Bsubscription%5D%5BinitialBillDate%5D=2012-08-29T13%3A04%3A17%2B00%3A00&cust_0%5Bsubscription%5D%5BgatewayToken%5D=imported_token&cust_0%5Bsubscription%5D%5BccLastFour%5D=9999&cust_0%5Bsubscription%5D%5BccExpiration%5D=02%2F2002&cust_0%5Bsubscription%5D%5BccFirstName%5D=First&cust_0%5Bsubscription%5D%5BccLastName%5D=Imported&cust_1%5Bcode%5D=cust_1&cust_1%5BgatewayToken%5D=imported_token&cust_1%5BfirstName%5D=Second&cust_1%5BlastName%5D=Imported&cust_1%5Bemail%5D=first%40example.com&cust_1%5Bsubscription%5D%5BplanCode%5D=plan_code&cust_1%5Bsubscription%5D%5BinitialBillDate%5D=2012-08-29T13%3A04%3A17%2B00%3A00&cust_1%5Bsubscription%5D%5BgatewayToken%5D=imported_token&cust_1%5Bsubscription%5D%5BccLastFour%5D=9999&cust_1%5Bsubscription%5D%5BccExpiration%5D=02%2F2002&cust_1%5Bsubscription%5D%5BccFirstName%5D=Second&cust_1%5Bsubscription%5D%5BccLastName%5D=Imported
In PHP, you might use a nested array:
$data = array(
'cust_0' => array(
'code' => 'cust_0',
'gatewayToken' => 'imported_token',
'firstName' => 'First',
'lastName' => 'Imported',
'email' => 'first@example.com',
'subscription' => array(
'planCode' => 'plan_code',
'initialBillDate' => date('c', strtotime('+ 1 week')),
'gatewayToken' => 'imported_token',
'ccLastFour' => '9999',
'ccExpiration' => '02/2002',
'ccFirstName' => 'First',
'ccLastName' => 'Imported'
)
),
'cust_1' => array(
'code' => 'cust_1',
'gatewayToken' => 'imported_token',
'firstName' => 'Second',
'lastName' => 'Imported',
'email' => 'first@example.com',
'subscription' => array(
'planCode' => 'plan_code',
'initialBillDate' => date('c', strtotime('+ 1 week')),
'gatewayToken' => 'imported_token',
'ccLastFour' => '9999',
'ccExpiration' => '02/2002',
'ccFirstName' => 'Second',
'ccLastName' => 'Imported'
)
)
);
You may alternatively choose to post a JSON body with the Content-type header set to application/json. Here's an example:
{
"cust_0": {
"code": "cust_0",
"gatewayToken": "imported_token",
"firstName": "First",
"lastName": "Imported",
"email": "first@example.com",
"subscription": {
"planCode": "plan_code",
"initialBillDate": "2015-07-08T13:29:32+00:00",
"gatewayToken": "imported_token",
"ccLastFour": "9999",
"ccExpiration": "02/2002",
"ccFirstName": "First",
"ccLastName": "Imported"
}
},
"cust_1": {
"code": "cust_1",
"gatewayToken": "imported_token",
"firstName": "Second",
"lastName": "Imported",
"email": "first@example.com",
"subscription": {
"planCode": "plan_code",
"initialBillDate": "2015-07-08T13:29:32+00:00",
"gatewayToken": "imported_token",
"ccLastFour": "9999",
"ccExpiration": "02/2002",
"ccFirstName": "Second",
"ccLastName": "Imported"
}
}
}
2.2 Imported in the Background
Customer data is validated on import. If any customer fails validation, the entire API call fails. If validation passes for all customers, all customers are queued for import in the background. It can take approximately 30-60 seconds to import 100 customers.
2.3 Email Notifications
Email notifications are disabled for imported customers. If you'd like to send your own notification or otherwise would like to be notified when a customer is successfully imported, you may use the subscriptionsImported webhook. Please contact us for more information about this webhook.
2.4 Setup Fees
When the subscribed pricing plan includes a setup fee on the initial invoice, the setup fee will be added to the initial invoice upon import. If the setup fee is configured to bill immediately on signup but the initial recurring invoice is configured to be billed later, the setup fee is ignored during import.
If you'd like to avoid charging a configured setup fee, you have a couple of options:
- You might consider removing the setup fee configuration from your pricing plans until after you've completed the import. The setup fee configuration is only in play during initial import. If you add setup fee configuration later, your existing customer records in Cheddar will not be affected.
- You may alternatively add it as a custom credit to the initial invoice during import to make the net setup fee amount zero.