Usage Metering and Billing
By the Syncfusion DevTutorials team · Last updated
Bill exactly what each customer used: usage events with ids, deduplication, late events billed as adjustments instead of edited invoices, and prorated plan changes.
Customers Pay for What They Use
Northwind charges per seat and per use: $30 a seat on Pro, and 2 cents for every 1,000 API calls. That sounds like simple arithmetic. It is not, because the numbers arrive through a distributed system: events are retried, servers go offline and catch up days later, and customers change plans halfway through the month.
A billing bug is unlike other bugs. Bill too much, and you have broken trust with a customer's finance team. Bill too little, and you lose money nobody will ever report. Change an invoice after it was sent, and the customer's books no longer match yours.
The main idea: record usage as events with unique ids, count each id once, total by the period the usage happened in, never edit a sent invoice (bill late usage as an adjustment on the next one), and prorate plan changes by day.
TL;DR
- Every unit of usage is an event: unique id, tenant, quantity, the time it happened.
- Deduplicate by id. Senders retry, so the same event can arrive twice.
- Total by the time the usage happened, not when it arrived.
- Never change a sent invoice. Late usage goes on the next invoice as a labelled adjustment.
- Prorate plan changes by day: credit the unused part of the old plan, charge the new plan for the rest.
A Real-World Example
A cloud vendor's usage pipeline was rerun after an outage. The rerun re-read a day of usage events that had already been counted, and nothing removed the duplicates. Thousands of customers were charged twice for that day. Refunds took weeks and needed a public apology. The fix was a unique id on every usage event and a dedupe step before counting.
What You Will Learn
- How usage becomes an invoice line.
- Why every event needs a unique id.
- What to do with usage that arrives late.
- How to prorate a plan change.
From Event to Invoice
Events carry ids; the meter drops duplicates and totals by the period the usage happened in. Usage that misses the cut goes on the next invoice, clearly labelled.
Keep the raw events, not just the totals. When a customer asks "why was I charged for 17,490 units?", you can list the events behind the number. That one feature turns a billing dispute into a short email.
Counting Each Event Once
Keep seen ids at least as long as a sender might retry, usually a few days. A unique constraint on (tenant, event_id) in the usage table does the job.
Usage That Arrives Late
Decide a cut-off and stick to it: for example, an invoice is built 24 hours after the period ends, to catch most late events. Anything later becomes an adjustment. Waiting "until everything has arrived" means never sending an invoice, because some device is always offline.
Plan Changes Mid-Month
Proration rules belong in the contract and on the pricing page: by day or by second, whether seat decreases get a credit, and what happens on a downgrade. Billing systems such as Stripe Billing apply them for you, but you still decide the policy.
Try It: Bill Acme Retail Exactly Right
- Start with no fixes. How many units are billed, and how many did Acme actually use?
- Deduplicate by id. Then try each choice for the four late events.
- Try each way to bill the plan change. Which one matches the contract?
Pass rule: no event counted twice, October's units billed exactly once in total, no sent invoice changed, and the plan change charged at the prorated $411.67.
Seats are usage too. Decide whether a seat is billed at its peak count, its count at the end of the period, or by day, and meter seat changes as events (seat added, seat removed) the same way, so every seat charge can be explained.
Check Yourself
Common mistakes
| Mistake | Wrong | Correct | Why it happens |
|---|---|---|---|
| No event ids | Retries double the count | Unique id per event, dedupe | Counters are simpler to send |
| Arrival time used | Late October usage billed in November without a label | Usage period from the event's own time | The arrival time is the one you have |
| Editing sent invoices | October invoice changed on Nov 2 | Adjustment on November's invoice | It feels more correct |
| Dropping late events | Usage that misses the cut is lost | Bill it as an adjustment | Late data looks like noise |
| Ad-hoc proration | Full-month charge on upgrade | Credit the old plan, charge the new, by day | The edge case is found by customers |
Practice
What to Remember
- Usage is events with unique ids, totalled by the time the usage happened.
- Deduplicate before counting.
- Never change a sent invoice; bill late usage as an adjustment.
- Prorate plan changes by day: credit the old, charge the new.
Further Reading
- Stripe: Usage-based billing: meters, events and their identifiers.
- Stripe: Prorations: how plan changes are credited and charged.
- OpenMeter documentation: an open-source usage metering service, with deduplication and late events.
Next: Cloud, Private Cloud and On-Premises. Globex wants Northwind in its own data centre, with no internet. You make one build run in all three places, without a fork.