Help Center

Migrating billing systems

This tutorial describes how to maintain accurate reporting during a billing system migration using the ChartMogul API.

Suggest Edits

A billing system migration typically involves canceling subscriptions in one billing system and starting them in another, for example when switching from Stripe to Recurly.

During a billing system migration, you’ll notice the following changes in ChartMogul:

  • Duplicate customer profiles, as the same customer is reported in both the new and old billing system.
  • Canceling all subscriptions in your old billing system results in a large number of churn movements, inflating the amount of reported churn MRR.
  • Starting subscriptions in your new billing system results in a large number of new business movements, inflating the amount of reported new business MRR.

For accurate reporting, merge a customer’s records in the new and old billing systems and then connect their subscriptions programmatically via our API:

1. Identify duplicate customer profiles

Locate duplicate customer records using the customer’s ID.

If you don’t have an existing record of customer IDs, use the list customers endpoint or export a CSV of your customers to extract their IDs. Then, match the customer profiles in ChartMogul with customer data in your system (such as email address) to identify the profiles that need to be merged.

2. Merge duplicate profiles

Once you have the list of customers to merge, use the merge customers endpoint. This endpoint accepts customer UUID pairs or a combination of data source UUIDs and external IDs.

❗️

Merge duplicate profiles before connecting subscriptions

It is recommended to merge ALL duplicate profiles before connecting subscriptions (instead of merging customers and connecting subscriptions at the same time). This is to allow time for ChartMogul to process, as the API call for merging customers works asynchronously.

# Example using Customer UUIDs for merging customers

curl -X POST "https://api.chartmogul.com/v1/customers/merges" \
       -u YOUR_API_KEY: \
       -H "Content-Type: application/json" \
       -d '{
             "from": {"customer_uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012"},
             "into": {"customer_uuid": "cus_ab223d54-75b4-431b-adb2-eb6b9e234571"}
           }'
           
# Example using Data Source UUIDs and External IDs for merging customers

curl -X POST "https://api.chartmogul.com/v1/customers/merges" \
       -u YOUR_API_KEY: \
       -H "Content-Type: application/json" \
       -d {
             "from": {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                      "external_id": "cus_187544"},
             "into": {"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
                      "external_id": "34916129"}
           }

3. Connect subscriptions

Finally, use the connect subscriptions endpoint to remove the churn and new business movements and have a customer’s subscription reported accurately. Note that one of the two subscriptions being connected must be canceled beforehand.

ChartMogul will connect subscriptions using either a combination of data source UUIDs and external IDs, or subscription UUIDs. Retrieve subscription UUIDs using the List Customer Subscriptions endpoint.

📘

Connecting subscriptions for customers on a freemium plan

Your billing system may have subscriptions for customers on a freemium plan. In ChartMogul, these customers are classified as leads, as they have never had an invoice for more than $0. You may encounter a 404 error in ChartMogul if you try to connect subscriptions for these customers using their external IDs.

# Using data_source_uuid and subscription external_id to connect two subscriptions
curl -X POST "https://api.chartmogul.com/v1/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/connect_subscriptions" \
       -u YOUR_API_KEY: \
       -H "Content-Type: application/json" \
       -d '{
                 "subscriptions": [
                                      {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                                       "external_id": "sub_001"
                                      },
                                      {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                                       "external_id": "sub_002"
                                       }
                 ]
           }'
           
# Or using data_source_uuid and subscriptions uuid to connect two subscriptions

curl -X POST "https://api.chartmogul.com/v1/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/connect_subscriptions" \
       -u YOUR_API_KEY: \
       -H "Content-Type: application/json" \
       -d '{
                 "subscriptions": [
                                      {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                                       "uuid": "d1c0c885-add0-48db-8fa9-0bdf5017d6b0"
                                      },
                                      {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                                       "uuid": "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4"
                                       }
                 ]
           }'

Updated over 1 year ago