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 propertyFormatDescription
cancelled_attimestampThe 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_datesarray of timestampsArray 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.