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 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 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",
  },
});
// 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 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"
              }
           }
# 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",
  },
});
// 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.

📘

Unmerging customers

Use the Unmerge Customers endpoint to unmerge previously merged customers.

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.