Adding subscription events for CMRR
How to import subscription events and how this information is used for calculating committed monthly recurring revenue (CMRR)
Subscription Events API Overview
The Subscription Events API is a subset of ChartMogul API endpoints used for creating, updating, deleting, and listing subscription events in ChartMogul.
Subscription events represent any event that alters the subscription for a customer. Whenever a customer's subscription is created, updated, or canceled, use the API to import a subscription event into ChartMogul.
ChartMogul classifies subscription events into three categories:
- Immediate Subscription Events — changes to a subscription that has already taken place.
- Scheduled Subscription Events — changes to a subscription that are expected or scheduled to take place in the future. Scheduled events contribute to CMRR.
- Retracted Subscription Events — A scheduled subscription event may become retracted when the expected or scheduled change to the subscription is subsequently canceled. Retracted events no longer contribute to CMRR.
Stripe supports Started and Updated Immediate 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.
Subscription events are classified into ten subscription event types:
Subscription Event | Subscription Event Type in API | Category | Description |
---|---|---|---|
Started | subscription_start | Immediate | Sent when a subscription begins immediately before an invoice is generated. This invoice will be generated at the start of the next billing cycle. |
Start (Scheduled) | subscription_start_scheduled | Scheduled | Sent when the subscription is scheduled to start on a future date. |
Start (Retracted) | scheduled_subscription_start_retracted | Retracted | Sent when a scheduled start to a new subscription is subsequently withdrawn. |
Canceled | subscription_cancelled | Immediate | Sent when the subscription is canceled. |
Cancellation (Scheduled) | subscription_cancellation_scheduled | Scheduled | Sent when the subscription is scheduled to be canceled on a future date. |
Cancellation (Retracted) | scheduled_subscription_cancellation_retracted | Retracted | Sent when a scheduled cancellation to a subscription is subsequently withdrawn. |
Updated | subscription_updated | Immediate | ent when a 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. |
Update (Scheduled) | subscription_update_scheduled | Scheduled | Sent when an update of an existing subscription is scheduled for a future date. |
Retracted | subscription_event_retracted | Retracted | Sent when a scheduled event is retracted before it takes effect on the subscription. |
Event Date vs. Effective Date
To create a subscription event in ChartMogul, you’ll need to provide two dates:
Event date — the date a subscription change is requested or triggered.
Effective date — the date a subscription change will be implemented.
Scheduled subscription events normally have an event date set in the past and an effective date set in the future.
Calculating CMRR Metrics Using Subscription Events
Scheduled subscription events with an effective date set in the future and a change in their subscription will impact CMRR metrics in ChartMogul.
Started
and Updated
Immediate events that change the subscription with an effective date set in the future (i.e, the future invoice creation date) will also impact CMRR metrics in ChartMogul.
CMRR is calculated using subscription events and MRR is calculated using invoice data. When viewing MRR Movements, movements dated in the future contribute to CMRR calculations and movements dated in the past contribute to MRR calculations.
When a Subscription Start is Scheduled for a Future Date
- If the customer is a new subscriber, first create their customer record using the Create a Customer endpoint. Skip this step if the customer is scheduled to reactivate a past subscription or start an additional subscription, as their customer record already exists in ChartMogul.
- If the subscription plan that the customer subscribed to does not yet exist in ChartMogul, create a new plan object using the Create a Plan endpoint.
- Create a
Start (Scheduled)
subscription event using the Create a Subscription Event endpoint, specifying customer, plan, subscription external id, amount, etc.
curl -X POST "https://api.chartmogul.com/v1/subscription_events" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"subscription_event":
{
"external_id": "evnt_001",
"customer_external_id": "scus_022",
"data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"event_type": "subscription_start_scheduled",
"event_date": "2022-03-30",
"effective_date":"2022-04-01",
"subscription_external_id":"sub_0001",
"plan_external_id":"gold_monthly",
"currency":"USD",
"amount_in_cents":"1000"
}
}'
When a Subscription Update is Scheduled for a Future Date
When an existing customer's subscription is scheduled to update on a future date, such as due to a plan change, the price they pay increases or decreases. Simply Create a Subscription Event with a subscription_update_scheduled
event type and the same subscription_external_id
to reflect the scheduled change.
curl -X POST "https://api.chartmogul.com/v1/subscription_events" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"subscription_event":
{
"external_id": "evnt_002",
"customer_external_id": "scus_022",
"data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"event_type": "subscription_update_scheduled",
"event_date": "2022-03-31",
"effective_date":"2022-04-15",
"subscription_external_id":"sub_0001",
"plan_external_id":"gold_quarterly",
"currency":"USD",
"amount_in_cents":"2500"
}
}'
When a Subscription Cancellation is Scheduled for a Future Date
When an existing customer's subscription is scheduled to cancel on a future date, create a Subscription Event with a subscription_cancellation_scheduled
event type and the same subscription_external_id
to reflect the cancellation.
curl -X POST "https://api.chartmogul.com/v1/subscription_events" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"subscription_event":
{
"external_id": "evnt_003",
"customer_external_id": "scus_022",
"data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"event_type": "subscription_cancellation_scheduled",
"event_date": "2022-04-03",
"effective_date":"2022-04-30",
"subscription_external_id":"sub_0001"
}
}'
When a Scheduled Event Gets Canceled
When a scheduled subscription event (scheduled creation, update or cancellation) becomes invalid or gets canceled, create a Subscription Event with a subscription_event_retracted
event type and a reference to a subscription event which becomes invalid.
curl -X POST "https://api.chartmogul.com/v1/subscription_events" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"subscription_event":
{
"external_id": "evnt_004",
"customer_external_id": "scus_022",
"data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"event_type": "subscription_event_retracted",
"event_date": "2022-04-10",
"effective_date":"2022-04-10",
"retracted_event_id":"evnt_003"
}
}'
This retracted event will mark the previously scheduled subscription cancellation (evnt_003
) as invalid, which will remove the Churn MRR Movement (dated in the future) for subscription with subscription_external_id
set to sub_0001
.
Alternatively, a scheduled subscription event (scheduled creation, update, or cancellation) can be made invalid by sending the corresponding retracted event.
Example:
- Subscription Update is Scheduled for a Future Date
curl -X POST "https://api.chartmogul.com/v1/subscription_events" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"subscription_event":
{
"external_id": "evnt_005",
"customer_external_id": "scus_023",
"data_source_uuid": "ds_1bn4fgac-32d7-82ec-clf4-3cg9mbe71cdc",
"event_type": "subscription_update_scheduled",
"event_date": "2022-06-30",
"effective_date":"2022-07-15",
"subscription_external_id":"sub_0007",
"plan_external_id":"gold_monthly",
"currency":"USD",
"amount_in_cents":"1000"
}
}'
- Retract the scheduled update of a subscription
curl -X POST "https://api.chartmogul.com/v1/subscription_events" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"subscription_event":
{
"external_id": "evnt_006",
"event_type": "scheduled_subscription_update_retracted",
"event_date": "2022-07-01",
"effective_date":"2022-07-01",
}
}'
The retracted event will only invalidate the last scheduled subscription update event. In this case, it will invalidate the event with external id evnt_005
.
Updated about 1 month ago