Understanding subscription events

A subscription event is any change to a subscription that affects the subscription’s calculated MRR. They become realized when an invoice is generated.

Here’s what we cover in this article:

Resources and further reading:

Subscription Event Lifecycle

In the normal course of business, scheduled subscription events eventually become MRR movements on the scheduled subscription event’s Effective Date. That is, a change to a subscription that is expected or scheduled to take place in the future becomes realized when an invoice is generated.

For example, on April 4, a customer communicates that they would like to add a new (or upgrade an existing) subscription at the start of their next billing cycle, May 15. The Update (Scheduled) event would have an effective date of May 15.

On May 15, when the next invoice is generated, ChartMogul would register the net increase in subscription MRR as   Expansion.

Subscription event types

In ChartMogul, there are three types of subscription events: immediate, scheduled, and retracted.

Immediate

Immediate subscription events are changes to a subscription (resulting from a billing activity, i.e., invoice) that take place presently.

Immediate subscription events happen when:

  • Canceled — a subscription ended.

Stripe supports Started and Updated events. These events happen when:

  • Started — a customer signs up, and their subscription begins immediately before an invoice is generated. This invoice will be generated at the start of the next billing cycle.
  • Updated — a customer’s subscription is upgraded or downgraded and the change is effective immediately before an invoice is generated. This invoice will be generated at the start of the next billing cycle.

Scheduled

Scheduled subscription events are changes to a subscription that are expected or scheduled to take place in the future. Scheduled events contribute to committed monthly recurring revenue (CMRR).

Scheduled subscription events are dated in the future and happen when:

  • Start (Scheduled) — a customer signs up, and their subscription begins on a future date.
  • Cancellation (Scheduled) — a customer cancels, and their subscription ends on a future date (e.g., at the end of the billing cycle).
  • Update (Scheduled) — a customer’s subscription is upgraded or downgraded, and this change is effective at a future date (e.g., at the start of the next billing cycle).

Retracted

A scheduled subscription event may become retracted when the expected or scheduled change to the subscription is subsequently canceled or withdrawn. Retracted events are dated in the past and no longer contribute to CMRR.

  • Start (Retracted) — a scheduled start to a new subscription is subsequently withdrawn.
  • Cancellation (Retracted) — a scheduled cancellation to a subscription is subsequently withdrawn.
  • Update (Retracted) — a scheduled update (e.g., upgrade or downgrade) to a subscription is subsequently withdrawn.

Adding subscription events

If you use Stripe or Recurly, ChartMogul imports subscription events automatically — no setup required. Learn more:

For custom sources, there are three options for uploading subscription events:

  • Manually — Add subscription events directly to your custom source.
  • CSV — Upload subscription events as CSV to your custom source.
  • Subscription Events API — Import subscription events using our API.
Was this article helpful?

We’re sorry to hear that. Would you like to share more feedback?


Thanks for your feedback!