Usage based billing is replacing fixed tier pricing across SaaS. Companies like Twilio, Snowflake, and Vercel have proven that charging based on actual consumption aligns incentives, reduces churn, and captures more revenue from high value customers. But implementing usage based billing is significantly harder than flat rate subscriptions. You are not just processing payments. You are building a metering system, an aggregation pipeline, and an invoicing engine, all of which must be accurate to the penny and auditable under scrutiny.
We have built billing systems for products that meter API calls, storage consumption, compute minutes, and message volume. The architecture patterns are consistent regardless of what you are metering. This post covers the key decisions and the pitfalls that make billing one of the most error prone systems in any SaaS product.
Why Usage Based Billing Is Hard
With flat rate billing, you charge $49 per month. The payment provider handles the recurring charge. Usage based billing adds three layers of complexity that flat rate does not have.
Metering. You must accurately track every billable event in real time. If a customer makes 1,000,000 API calls, your system must count exactly 1,000,000, not 999,998 or 1,000,003. Billing disputes caused by inaccurate metering destroy customer trust faster than almost any other product failure.
Aggregation. Raw events must be aggregated into billable units on the correct billing cycle. A customer's billing period might start on the 15th, so all metering must align to that anchor date. Time zones add another layer of complexity. Does "daily usage" mean midnight UTC or midnight in the customer's time zone?
Invoicing. Aggregated usage must be converted into line items on an invoice, with correct pricing tiers, volume discounts, committed use credits, and taxes. The invoice must be generated, reviewed (optionally), and charged, all within a tight window at the end of each billing period.
Each of these layers can fail independently, and the failures compound. We covered the foundational payment integration patterns in our subscription billing architecture guide, and usage based billing builds directly on those concepts.
The Metering Pipeline
The metering pipeline is the foundation. Every billable event must be captured, deduplicated, and stored for aggregation. Here is the architecture we recommend.
Event ingestion. Billable events are emitted from your application as structured records. Each event includes a customer ID, event type, timestamp, quantity (usually 1 but can be variable for things like data transfer bytes), and an idempotency key. The idempotency key is critical. Network retries, duplicate webhooks, and application restarts can all cause the same event to be submitted multiple times. Without an idempotency key, you will double count and overcharge customers.
Buffered writes. Writing every individual event directly to your primary database will not scale. Instead, buffer events in a fast write store, Redis streams, Kafka, or even an in memory buffer that flushes periodically, and batch insert into your metering database. A typical pattern is to buffer events for 1 to 5 seconds, then batch insert. This reduces write load by 100x while keeping metering latency under 10 seconds.
Storage schema. Metering data needs a schema optimized for aggregation queries. We use a time series structure:
```
metering_events:
- customer_id (indexed)
- event_type (indexed)
- timestamp (indexed)
- quantity
- idempotency_key (unique)
- metadata (jsonb)
```
Partition this table by time (monthly partitions work well) so that aggregation queries only scan the relevant billing period. Without partitioning, queries slow down linearly as your event volume grows.
Pre aggregation. In addition to raw events, maintain running counters that update as events arrive. A table like `usage_summaries` with (customer_id, event_type, period_start, period_end, total_quantity) lets you answer "how much has this customer used this month?" without scanning millions of raw events. Update these summaries atomically with the event inserts, or run a reconciliation job that catches any drift between raw events and summaries.
Pricing Models
Usage based billing supports several pricing models, and your architecture must be flexible enough to handle all of them, because your pricing will change as your product matures.
Per unit pricing. The simplest model. $0.001 per API call, $0.10 per GB of storage. Multiply usage by unit price. Straightforward to implement and easy for customers to understand.
Tiered pricing. The first 10,000 API calls cost $0.002 each, the next 90,000 cost $0.001, and everything above 100,000 costs $0.0005. This is more complex because the price per unit depends on total volume. Your invoicing logic must apply the correct tier to the correct portion of usage.
Volume pricing. Similar to tiered, but the tier applies to all units, not just the marginal ones. If the customer uses 50,000 API calls and that lands in the $0.001 tier, all 50,000 are billed at $0.001. This is simpler to compute but can create cliff effects where a customer pays more by using slightly more.
Committed use. The customer pre purchases a usage block (e.g., 1 million API calls per month for $800) and pays overage for anything beyond the commitment. This requires tracking committed quantities separately from actual usage and billing only the delta.
Store your pricing configuration as structured data, not hardcoded logic. A pricing table with (plan_id, metric, tier_start, tier_end, unit_price) lets you modify pricing without code changes. Apply pricing changes only to future billing periods. Never retroactively change the price on usage that has already occurred.
Real Time Usage Visibility
Customers on usage based plans need to see their current consumption. They need to know how much they have used, how much it will cost, and whether they are approaching any limits or committed quantities. Waiting until the invoice arrives to learn what they owe creates billing shock, the number one cause of churn on usage based plans.
Build a real time usage dashboard that shows current period consumption, projected end of period cost, and comparison to previous periods. The pre aggregated usage summaries described above make this fast to query. Refresh these counters at least every few minutes so the dashboard stays current.
Alerts and thresholds are essential. Let customers set notifications for when they hit 50%, 80%, and 100% of a usage threshold. Proactive alerts prevent billing surprises and give customers the chance to adjust their behavior or upgrade their commitment before they incur expensive overage charges. This ties directly into building effective customer portals where usage visibility is a core feature.
Integration With Payment Providers
Stripe is the most common payment provider for usage based billing, and it has native support for metered billing through its Billing API. Here is how we integrate.
Stripe Meters (or usage records on older integrations) accept reported usage and handle aggregation and invoicing on Stripe's side. You report usage events to Stripe in near real time, and at the end of the billing period, Stripe generates the invoice based on the reported usage and your configured pricing.
The alternative is self managed invoicing, where you aggregate usage yourself, calculate the total, and create a Stripe invoice with explicit line items. This gives you more control over the invoice format and pricing logic but requires you to handle the aggregation pipeline end to end.
Our recommendation: use Stripe's built in metering for straightforward per unit pricing. Build your own aggregation for complex tiered pricing, committed use models, or when you need custom invoice formats. Either way, maintain your own metering records as the source of truth. Never depend solely on a payment provider's usage records, because you need the ability to audit, reconcile, and resolve disputes from your own data.
Handling Edge Cases
Usage based billing has edge cases that will bite you if you do not plan for them.
Credit card failures. When the invoice charge fails, you still have the usage data. Implement a retry schedule (day 1, day 3, day 7) and send the customer notifications at each step. If all retries fail, decide on your policy: suspend access, allow continued use with a past due flag, or downgrade to a free tier.
Mid cycle plan changes. A customer upgrades from a basic plan to an enterprise plan on the 15th of the month. You need to prorate the fixed components and apply the correct pricing to usage before and after the change. This is one of the most complex invoice generation scenarios and must be explicitly handled in your billing logic.
Refunds and credits. A customer reports that 50,000 of their 200,000 metered events were caused by a bug in their integration. You need to issue a credit for those events. Your system should support usage adjustments that modify the aggregated totals and flow through to the next invoice as a credit line item.
Time zone alignment. If your billing period is "monthly" and your customer's business operates in Tokyo, does the month end at midnight UTC or midnight JST? Define this clearly, communicate it to customers, and apply it consistently. We typically anchor billing periods to UTC and clearly state this in the billing documentation.
Auditing and Reconciliation
Because billing directly involves money, you need robust auditing. Every metering event, every aggregation computation, and every invoice line item should be traceable. When a customer asks "why was I charged $347.82 this month?" you should be able to produce a breakdown in minutes, not hours.
Run daily reconciliation jobs that compare raw metering events against pre aggregated summaries and flag any discrepancies. Run monthly reconciliation before invoice generation that validates the total usage against what the payment provider will charge. Catch errors before they become invoices.
Building a billing system this robust requires serious system architecture expertise. It touches your database, your event pipeline, your payment provider, your customer portal, and your support tools. For teams weighing custom development versus SaaS billing platforms, the decision often comes down to how central billing is to your product experience. If billing is a commodity feature, use a platform. If it is a core differentiator, build it.
If you are implementing usage based billing or transitioning from flat rate to consumption pricing, get in touch with us. We will help you build a metering and billing system that is accurate, scalable, and trustworthy.