Guides
Help Center

Connecting subscriptions using the API

This tutorial describes how to connect subscriptions using the ChartMogul API

Suggest Edits

When you migrate billing systems, you'll have duplicate customer profiles in ChartMogul, as the same customer is reported in both the new and old billing system. Merge the duplicate profiles using the Merge Customers endpoint to report all data in a single customer profile. However, when customers are merged, they'll have two (or more) subscriptions.

Usually, the subscription in the old billing system is cancelled since all new payments will be received in the new billing system. ChartMogul classifies this as churn, even though the customer didn't really cancel their subscription. Use the Connect Subscriptions endpoint to accurately report the customer's subscription history and remove the false churn (or contraction).

Example

Before following the steps in this tutorial, you'll need to merge customers using the API.

Adam Smith was previously billed in Stripe and is now billed in Recurly. His two customer profiles were merged in ChartMogul and he has two subscriptions:

  • The previous subscription in Stripe
  • The current subscription in Recurly

To merge subscriptions, you'll 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
  • Data source 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 YOUR_API_KEY: \
     -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",
      },
    ],
  }
);

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 two subscriptions is possible, simply add all external ids into the subscriptions array.

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.

Updated 4 months ago