Changing a customer's churn history
Subscriptions in ChartMogul can be cancelled and re-activated an infinite number of times. Each subscription cancellation that you submit to ChartMogul adds to that subscription's cancellation history. While API users submit cancellations using the cancelled_at
attribute, ChartMogul returns the full history of a subscription's cancellations in the cancellation_dates
attribute.
Subscription property | Format | Description |
---|---|---|
cancelled_at | timestamp | The time at which the subscription was cancelled. Must be an ISO 8601 formatted time in the past. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise. |
cancellation_dates | array of timestamps | Array of ISO 8601 Timestamps representing all cancellations in the subscription's lifetime. Can be an empty array. |
This article explains how you can use the endpoint for cancelling a subscription, to also change a subscription's cancellation history.
Changing a subscription's cancellation history
As described in the Getting started tutorial, you can cancel a subscription at any time by submitting a cancelled_at
timestamp.
ChartMogul registers contraction/churn of the subscription MRR at each of the above timestamps. In some cases, you might want to change or remove a cancellation that you have submitted. You can do so by specifying the full history of the subscription's cancellations in the cancellation_dates
attribute.
Let's imagine that:
- One of your subscriptions was cancelled automatically by your billing system on
January 1st, 2017
because the customer did not renew in time. - Your integration with ChartMogul automatically propagated this cancellation to ChartMogul and contraction MRR was registered.
- The customer pays eventually on
January 15th, 2017
and the subscription gets re-activated, but you want to remove the cancellation registered in ChartMogul so that the churn and re-activation does not show.
To do this, you must remove the January 1st, 2017
timestamp from the cancellation_dates
attribute and submit it to the PATCH subscription endpoint.
Note - For the purposes of this example, we are using sub_e6bc5407-e258-4de0-bb43-61faaf062035
as the UUID of the subscription.
curl -X PATCH "https://api.chartmogul.com/v1/import/subscriptions/sub_e6bc5407-e258-4de0-bb43-61faaf062035" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"cancellation_dates": []
}'
customer = ChartMogul::Customer.all(external_id: "cus_0001").first
subscription = customer.subscriptions.last
subscription.update_cancellation_dates([])
ChartMogul.Subscription.cancel(
config,
"sub_e6bc5407-e258-4de0-bb43-61faaf062035",
{ cancellation_dates: [] }
);
$subscription = new ChartMogul\Subscription([
"uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035"
]);
$cancellationDates = [];
$subscription = $subscription->setCancellationDates($cancellationDates);
api.CancelSubscription(
"sub_e6bc5407-e258-4de0-bb43-61faaf062035",
&cm.CancelSubscriptionParams{
CancellationDates: []string{}
}
)
chartmogul.Subscription.cancel(
config,
uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035",
data={"cancellation_dates": []},
)
The value you send for cancellation_dates
will completely replace the existing cancellation history of a subscription. Therefore, if the subscription has other cancellation timestamps in it's history which you want to retain, then you must include those timestamps in the value for cancellation_dates
. For example, let us say that you want to retain a cancellation dated January 1st, 2016
but remove the one dated January 1st, 2017
.
curl -X PATCH "https://api.chartmogul.com/v1/import/subscriptions/sub_e6bc5407-e258-4de0-bb43-61faaf062035" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"cancellation_dates": ["2016-01-01 00:00:00"]
}'
customer = ChartMogul::Customer.all(external_id: "cus_0001").first
subscription = customer.subscriptions.last
subscription.update_cancellation_dates([Time.utc(2016, 1, 1)])
ChartMogul.Subscription.cancel(
config,
"sub_e6bc5407-e258-4de0-bb43-61faaf062035",
{ cancellation_dates: ["2016-01-01T00:00:00.000Z"] }
);
$subscription = new ChartMogul\Subscription([
"uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035"
]);
$cancellationDates = ["2016-01-01T00:00:00.000Z"];
$subscription = $subscription->setCancellationDates($cancellationDates);
api.CancelSubscription(
"sub_e6bc5407-e258-4de0-bb43-61faaf062035",
&cm.CancelSubscriptionParams{
CancellationDates: []string{"2016-01-01T00:00:00.000Z"}
}
)
chartmogul.Subscription.cancel(
config,
uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035",
data={"cancellation_dates": ["2016-01-01T00:00:00.000Z"]},
)
This functionality to update a subscription's cancellation history should give API users complete control over recognition of contraction/churn MRR in ChartMogul.
Please note that no service_period_start
value can be the same as any cancelled_at
value for a given subscription, so the system can build a deterministic order of events. If you wish to cancel immediately after the start of a period, please shift the time stamp by one second forwards. In case, it should be canceled before the date, shift it one second into the past.
Note - If cancellation_dates
is specified in a request to this endpoint, ChartMogul will ignore any value specified for cancelled_at
. If you want a cancelled_at
value to be included for a subscription in the same request, you can specify it as part of the cancellation_dates
array itself.
Updated 9 days ago