Adding paused subscriptions

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 the discount_amount_in_cents to be equal to the amount_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.

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.