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.

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.