Billing is the part of a cloud platform that nobody wants to build and everybody underestimates. It's not the invoice PDF generation — that's trivial. It's the metering, the rating, the proration, the edge cases, and the reconciliation that will consume your engineering team for months.
We've been through it. Here's what we learned building PLATFORMA's billing engine from zero to 500+ tenants.
The Four Pricing Models
Our platform supports four pricing dimensions simultaneously: monthly recurring (fixed price per month), hourly on-demand (pay-per-hour for compute), per-unit usage (storage per GB, bandwidth per GB), and annual commitments (monthly price with long-term discount).
A single product can use multiple models. A VPS might have a monthly base price plus per-GB storage charges plus per-GB bandwidth overage. The billing engine needs to handle all of these independently and combine them into a single line item on the invoice.
Real-Time Metering
Every 60 seconds, our metering service samples resource utilization across all tenants. CPU time, memory allocation, storage consumption, network bytes — everything that could affect billing is tracked. These samples are aggregated into hourly buckets and stored with the tenant ID and resource ID.
The challenge is accuracy at scale. With 500 tenants and thousands of resources, we're processing millions of metering events per day. A 1% error rate means hundreds of incorrect invoices. We chose Kafka for the metering pipeline because we cannot afford to lose events — every dropped meter reading is lost revenue.
The Proration Problem
What happens when a customer upgrades from a 2-core VPS to a 4-core VPS on day 15 of a 30-day billing cycle? They should pay half the month at the old rate and half at the new rate. Sounds simple, but multiply this by 4 pricing models, multiple resources, and customers in different timezones, and you have a combinatorial nightmare.
Our solution: every resource change creates a 'billing event' that splits the current period into segments. Each segment is rated independently, and the invoice shows the breakdown. Customers can see exactly why their bill changed and when.
Stripe Integration
We don't build payment processing — that's Stripe's job. Our billing engine generates invoices and pushes them to Stripe for payment collection. The integration handles subscription creation, usage record reporting, invoice finalization, and webhook processing for payment status.
The tricky part is keeping our billing records and Stripe in sync. We use an idempotent sync process that runs every hour, comparing our invoice records with Stripe's. Any discrepancies are flagged for manual review. In practice, discrepancies are rare (< 0.1%) and usually caused by timing issues in webhook delivery.
Lesson: Build Billing Reports Early
The biggest mistake we made was building billing reports as an afterthought. When a customer disputes an invoice, you need to show them exactly how every line item was calculated — which resources, which hours, which pricing model, which rates. Build this visibility from day one, not after your first billing dispute.