ChartMogul Developer Hub

Welcome to the ChartMogul Developer Hub. You'll find comprehensive guides and documentation to help you start working with ChartMogul as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Merging customers using the API

This tutorial describes how you can merge customers using the ChartMogul API.

Sometimes, one of your customers may be reported as two or more customers in ChartMogul because their billing data is imported from different data sources. For example, this can happen when you migrate from using one billing system to another. ChartMogul will then show all your customers churning, and all of them getting created again as new business, at the time of migration.

To have these separate customer records reported as a single customer with a single subscription history, you can merge them using the Merge Customers endpoint.

Example

Let us imagine that you were invoicing your customer Adam Smith using Stripe, and then switched him over to Recurly. This would result in two customers being reported in ChartMogul,

  • Adam Smith (Stripe), based on billing data we receive from your connected Stripe account, and
  • Adam Smith (Recurly), based on billing data we receive from your connected Recurly account.

You would now 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 the invoice belongs to and which customer to tight the data to.

Updated about a year ago

Merging customers using the API


This tutorial describes how you can merge customers using the ChartMogul API.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.