Merging customers
This tutorial describes how you can merge customers using the ChartMogul API.
A customer may be reported as two (or more) customers in ChartMogul when their billing data is imported from different data sources. For example, this can happen when you migrate billing systems.
To have these separate customer records reported as a single customer with a single subscription history, use the Merge Customers endpoint.
Example
Let's imagine that you were billing your customer Adam Smith using Stripe, and are currently billing him using Recurly. This would result in two customers being reported in ChartMogul:
- Adam Smith (Stripe), based on billing data imported from your Stripe account, and
- Adam Smith (Recurly), based on billing data imported from your Recurly account.
You'll want to merge the old Adam Smith (Stripe) customer record, into the new Adam Smith (Recurly) record, so that his subscription history is consolidated, and new updates are attributed correctly to the same customer.
Note - For the purposes of this example, we are using the following Customer UUIDs:
- ChartMogul UUID of the old Adam Smith (Stripe) -
cus_de305d54-75b4-431b-adb2-eb6b9e546012 - ChartMogul UUID of the new Adam Smith (Recurly) -
cus_ab223d54-75b4-431b-adb2-eb6b9e234571
# Example using Customer UUIDs
curl -X POST "https://api.chartmogul.com/v1/customers/merges" \
-u <token>:<secret>
-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 Customer UUIDs
from_customer = ChartMogul::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
into_customer = ChartMogul::Customer.retrieve('cus_ab223d54-75b4-431b-adb2-eb6b9e234571')
from_customer.merge_into!(into_customer)
// Example using Customer UUIDs
ChartMogul.Customer.merge(config, {
"from": {
"customer_uuid": "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"
},
"into": {
"customer_uuid": "cus_2123290f-09c8-4628-a205-db5596bd58f7"
}
})
<?php
// Example using Customer UUIDs
ChartMogul\Customer::merge([
"customer_uuid" => "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"
], [
"customer_uuid" => "cus_2123290f-09c8-4628-a205-db5596bd58f7"
]);
?>
// Example using Customer UUIDs
api.MergeCustomers(&cm.MergeCustomersParams{
From: cm.CustID{CustomerUUID: "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"},
To: cm.CustID{CustomerUUID: "cus_2123290f-09c8-4628-a205-db5596bd58f7"},
})
# Example using Customer UUIDs
chartmogul.Customer.merge(config, data={
"from": {
"customer_uuid": "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"
},
"into": {
"customer_uuid": "cus_2123290f-09c8-4628-a205-db5596bd58f7"
}
})
Instead of using Customer UUIDs to identify customer records for merging, you can also identify customer records by using a combination of Data Source UUIDs and External IDs.
You can lookup your Data Source UUIDs using the List Data Sources endpoint.
# Example using Data Source UUIDs and External IDs
curl -X POST "https://api.chartmogul.com/v1/customers/merges" \
-u <token>:<secret>
-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"}
}
# Example using Data Source UUIDs and External IDs
from_customer = ChartMogul::Customer.all(data_source_uuid: "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213", external_id: "cus_187544").first
into_customer = ChartMogul::Customer.all(data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430", external_id: "34916129").first
from_customer.merge_into!(into_customer)
// Example using Data Source UUIDs and External IDs
ChartMogul.Customer.merge(config, {
"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"
}
})
<?php
// Example using Customer UUIDs
ChartMogul\Customer::merge([
"data_source_uuid" => "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
"external_id" => "cus_187544"
], [
"data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"external_id" => "34916129"
]);
?>
// Example using Data Source UUIDs and External IDs
api.MergeCustomers(&cm.MergeCustomersParams{
From: cm.CustID{
DataSourceUUID: "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
ExternalID: "cus_187544",
},
To: cm.CustID{
DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
ExternalID: "34916129",
},
})
# Example using Data Source UUIDs and External IDs
chartmogul.Customer.merge(config, data={
"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"
}
})
Merging is done asynchronously
Once a valid request is received by the API, it will respond with
202 - Accepted, and the merging function will proceed to work asynchronously.The merged customer will have the ChartMogul Customer UUID, email address, and location of Adam Smith (Recurly). Both customers’ external IDs, tags, custom attributes, and notes will be preserved. Subscriptions, MRR movements and transactions will be collated and ordered by date. If both customers have the same custom field, the value retained for the field will be that of the customer specified in
into.You can see the merged customer reported in your ChartMogul account.
Note on importing invoices for merged customers
In case you have two or more customers that have been merged into one, you need to specify the data_source_uuid and customer_external_id when sending an invoice for the merged customer. This way ChartMogul knows which data source and customer the invoice belongs to.
Updated about 1 month ago