Adding paused subscriptions
This tutorial describes how to implement paused subscriptions using the ChartMogul API.
If your business stops issuing invoices to customers while their subscriptions are paused, ChartMogul classifies these customers as Past due and they continue to generate MRR. Subscriptions are active in ChartMogul until they are explicitly canceled. To classify customers with a paused subscription as Active and no longer contributing to MRR, use the following steps:
1. Create a paused plan
Create a plan for paused subscriptions using the Create a Plan endpoint:
# Example paused plan
curl -X POST "https://api.chartmogul.com/v1/import/plans" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"name": "Paused",
"interval_count": 1,
"interval_unit": "month",
"external_id": "plan_0001"
}'
2. Add a $0 invoice
Use the Import Invoices endpoint to add a $0 invoice with the paused plan created in Step 1. Keep in mind the following:
- Set
amount_in_cents
to 0 or thediscount_amount_in_cents
to be equal to theamount_in_cents
, resulting in a 100% discount. - Use the
UUID
of the plan created in Step 1. - Use the
subscription_external_ID
of the subscription you are pausing. This allows ChartMogul to track the subscription moving to a free plan.
# Example paused plan
curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"invoices":
[
{
"external_id": "INV123",
"date": "2022-11-01 00:00:00",
"currency": "USD",
"due_date": "2022-11-15 00:00:00",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"line_items": [
{
"type": "subscription",
"subscription_external_id": "sub_0001",
"plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
"service_period_start": "2022-11-01 00:00:00",
"service_period_end": "2022-12-01 00:00:00",
"amount_in_cents": 0
}
]
}
]
}'
ChartMogul reports the switch as Contraction and continues to classify the customer as Active.
A $0 invoice only needs to be sent once. When a customer unpauses their subscription, issue a new invoice updating the plan UUID
and amount_in_cents
so they contribute to MRR. If a customer cancels their subscription, send a cancellation event to classify the subscription as Cancelled.
Review your data settings
Review your Handling Past-due Subscriptions and Free Customer Handling data settings, as these may unintentionally churn customers with paused subscriptions.
Track customers with paused subscriptions by segmenting your customers by plan and creating a saved list. While it’s also possible to track customers with paused subscriptions using custom attributes or tags, these methods won’t allow ChartMogul to report MRR movements.
Updated 3 months ago