Understanding subscription events

Subscription Events in ChartMogul track upcoming changes to a subscription — upgrades, downgrades, and cancellations — and show how those changes affect MRR (Monthly Recurring Revenue) before they appear on an invoice. There are three types: immediate events (take effect right away), scheduled events (dated in the future, they contribute to Committed MRR, or CMRR), and retracted events (a previously scheduled change that has been withdrawn). Pause and resume events record when a subscription is temporarily paused and when it resumes.

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.

How Subscription Event Types Work

In ChartMogul, there are three types of subscription events (immediate, scheduled, and retracted), plus pause and resume events.

Immediate

Immediate subscription events are changes to a subscription that take effect right now, triggered by a billing activity — that is, when an invoice is generated.

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 set to take effect on a future date. They contribute to committed monthly recurring revenue (CMRR) 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 retracted event is a scheduled subscription event where the planned change was later canceled or withdrawn. Retracted events are dated in the past and no longer count toward CMRR (Committed Monthly Recurring Revenue).

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.

Paused and resumed

Pause and resume events mark when a customer temporarily stops paying for a subscription and when they start again:

Paused — the customer paused the subscription. ChartMogul shows the subscription as Paused from the event’s effective date.
Resumed — the customer resumed the paused subscription. A new payment for the subscription also ends the pause, even without a resume event.

How a pause affects MRR and churn depends on the When a subscription is paused option in Data Settings. Learn more about handling paused subscriptions.

How to Add Subscription Events

ChartMogul imports subscription events automatically from select billing systems — no setup required. Learn more:

For custom sources (data you import yourself, outside of a native billing integration), you have three options:

Manually — add subscription events directly to your custom source.
CSV — upload subscription events as a CSV file to your custom source.
Subscription Events API — import subscription events programmatically using our API.

For pause and resume events, the API event types are subscription_paused and subscription_resumed . For manual subscriptions, use manual_subscription_paused and manual_subscription_resumed .