Adding Subscription Events for CMRR

How to import subscription events and how this information is used for calculating committed monthly recurring revenue (CMRR)

📘

Committed monthly recurring revenue (CMRR) is currently in beta. During this time, subscription events and CMRR metrics are only visible in ChartMogul to customers who have CMRR enabled.

Subscription Events API Overview

The Subscription Events API is a subset of Import API endpoints used for creating, updating, deleting and listing subscription events in ChartMogul.

Subscription events represent any event that alters 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:

  1. Immediate Subscription Events — changes to a subscription that have already taken place.
  2. Scheduled Subscription Events — changes to a subscription that are expected or scheduled to take place in the future. Scheduled events contribute to CMRR.
  3. 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.

Subscription events are classified into five subscription event types:

Subscription Event

Subscription Event Type in API

Category

Description

Start (Scheduled)

subscription_start_scheduled

Scheduled

Sent when the subscription is scheduled to start on a future date.

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.

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.

📘

Our API has two additional immediate subscription event types: Started and Updated. These events can be imported, however, they will not impact any metrics in ChartMogul.

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

Only scheduled subscription events with an effective date set in the future and a change in MRR will 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

  1. 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.
  2. 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.
  3. 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.

📘

Following the beta launch of CMRR on April 21, 2022, we’re testing different approaches and architectures for retracting scheduled subscription events to align our API behavior with common billing system retraction mechanisms. Note that the behavior of Retracted events may change in future Subscription Event API updates.

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.