Implementing usage-based billing

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"
                  }
                ]   
              }
            ]
        }'