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"
}
]
}
]
}'
Updated 3 months ago