Adding subscription events for 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:

1. Immediate Subscription Events — changes to a subscription that has 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.

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:

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

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.

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:

1. 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"
              }
        }'

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