Connecting subscriptions using the API

This tutorial describes how you can connect subscriptions using the ChartMogul API.

When you change billing systems for a customer, a new customer profile is created in ChartMogul under the new billing system. These 2 customer profiles are then merged using the Merge Customers end-point to retain all information under a single customer profile. However, merging the customers results in having 2 or more subscriptions for the same user.

While it's not mandatory, usually, the subscription in the previous billing system is cancelled since all new payments will be received in the new billing system. However, this will incorrectly show a churn since the customer did not really cancel their subscription. Connecting the subscriptions will remove the false churn or contraction originating from the customer deactivating in one billing system then activating in another. You can use the Connect Subscriptions end-point to do this.

Example

Adam Smith was switched from being billed in Stripe to being billed in Recurly and the 2 customer profiles were already merged in ChartMogul. In the customer page, there will be 2 subscriptions:

  • The previous subscription from Stripe
  • The new subscription from Recurly

To merge subscriptions, you will need the customer UUID, datasource UUID and the external ids of the subscriptions to be merged.

Note - For the purposes of this example, we are using the following datasource uuid and subscription external IDs:

  • Customer UUID - cus_f466e33d-ff2b-4a11-8f85-417eb02157a7
  • Datasource UUID - ds_ade45e52-47a4-231a-1ed2-eb6b9e541213
  • External ID of the Stripe subscription - d1c0c885-add0-48db-8fa9-0bdf5017d6b0
  • External ID of the Recurly subscription - 9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4
curl -X POST "https://api.chartmogul.com/v1/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/connect_subscriptions" \
       -u <token>:<secret> \
       -H "Content-Type: application/json" \
       -d '{
                 "subscriptions": [
                                      {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                                       "external_id": "d1c0c885-add0-48db-8fa9-0bdf5017d6b0"
                                      },
                                      {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                                       "external_id": "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4"
                                       }
                 ]
           }'
customer = ChartMogul::Customer.retrieve('cus_f466e33d-ff2b-4a11-8f85-417eb02157a7')
first_sub = customer.subscriptions.first
second_sub = customer.subscriptions.last

first_sub.connect(customer.uuid, [second_sub])
ChartMogul.Customer.connectSubscriptions(config, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
    "subscriptions": [{
            "data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
            "external_id": "d1c0c885-add0-48db-8fa9-0bdf5017d6b0"
        },
        {
            "data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
            "external_id": "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4"
        }
    ]
})
<?php

ChartMogul\Customer::connectSubscriptions("cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", [
    "subscriptions" => [
        [
            "data_source_uuid" => "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
            "external_id" => "d1c0c885-add0-48db-8fa9-0bdf5017d6b0",
        ],
        [
            "data_source_uuid" => "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
            "external_id" => "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4",
        ],
    ]
]);
?>
api.ConnectSubscriptions("cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",[]cm.Subscription{
  {
    DataSourceUUID: "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
    ExternalID:     "d1c0c885-add0-48db-8fa9-0bdf5017d6b0",
  },
  {
    DataSourceUUID: "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
    ExternalID:     "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4",
  },
})
chartmogul.Customer.connectSubscriptions(config, uuid='cus_f466e33d-ff2b-4a11-8f85-417eb02157a7', data={
  'subscriptions': [
    {
      "data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
      "external_id": "d1c0c885-add0-48db-8fa9-0bdf5017d6b0"
    },
    {
      "data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
      "external_id": "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4"
    }
  ]
})

Merging more than 2 subscriptions is possible, simply add all external ids into the subscriptions array.

You can lookup your Data Source UUIDs using the List Data Sources endpoint.

📘

Connecting subscriptions is done asynchronously

Once a valid request is received by the API, it will respond with 202 - Accepted, and the subscriptions will be connected asynchronously.

🚧

Connecting recently created subscriptions

If a subscription with the specified identifiers cannot be found, this endpoint will return the HTTP status 404. In this context, it is important to note that invoices that have been imported recently, may not have been fully processed, and related subscriptions not yet generated. It is thus recommended to wait for all imported invoices to be completely processed and reported in the dashboard, before placing API requests for connecting subscriptions.