Implementing usage-based billing

This tutorial describes best practices for implementing usage-based billing using the ChartMogul API.

ChartMogul was built with fixed-priced advance billing in mind. However, businesses with usage-based billing can still benefit from using ChartMogul’s powerful subscription metrics and analytics. Learn more about how usage-based billing works with ChartMogul.

If your business bills products/services using usage-based billing, follow these steps:

1. Set up plans to separate usage-based billing components

To accurately report the amount of MRR from fixed and usage-based components, create separate plans.

Segment MRR by plan to determine the amount usage-based billing contributes to your MRR. If you have multiple usage-based plans, create a plan group for easier segmentation.

For example, Adam Smith has a monthly subscription billed for a fixed amount every month in addition to being billed for his monthly usage. ChartMogul reports Adam as having two active subscriptions: one for the fixed amount and another for his monthly usage.

Here’s how these plans are set up using the example above:

# Example fixed price 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": "Fixed-amount Plan",
           "interval_count": 1,
           "interval_unit": "month",
           "external_id": "plan_0001"
         }'
         
         # Example usage-based 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": "Usage-based Plan",
           "interval_count": 1,
           "interval_unit": "month",
           "external_id": "plan_0002"

2. Backdate invoice service periods

A key characteristic of usage-based billing subscriptions is that customers pay at the end of the service period, rather than the beginning. This means that usage-based service periods must be backdated, i.e. the service period in October is billed in November.

For Adam Smith in the example above, his November invoice includes a line item for the fixed plan in November (sub_0001) as well as a line item for the usage-based plan in October (sub_0002).

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": "INV0001",
          "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": 5000,
              "tax_amount_in_cents": 900
            },
            {
              "type": "subscription",
              "subscription_external_id": "sub_0002",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2022-10-01 00:00:00",
              "service_period_end": "2022-11-01 00:00:00",
              "amount_in_cents": 600,
              "tax_amount_in_cents": 80
            }
          ],
          "transactions": [
            {
              "date": "2022-11-05 00:14:23",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     }'