Metered billing gotchas nobody warns you about

The hardest metered-billing bugs aren't in the pricing math. They live in the seams — idempotency, late events, clock boundaries, and proration — and none of them throw an error. They just produce a slightly wrong invoice that erodes trust and revenue. Here are the ones that catch teams most often.

Double-counting and idempotency

If a usage event can be delivered twice — and at scale, it will be — you'll bill twice unless every event carries a stable idempotency key. The key has to come from the event itself (a request ID, a job ID), not from the time it was received. Retried webhooks, at-least-once queues, and client re-sends all funnel into this one problem.

Late and out-of-order events

Usage doesn't always arrive before the billing period closes. An event generated at 11:59pm on the last day of the month might land in your system at 12:02am the next day. Decide explicitly: does it bill to the period it occurred in or the period it arrived in? Both are defensible; silently mixing them is not. Whatever you choose, make sure your aggregation window and Stripe meter event timestamps agree.

Clock boundaries and timezones

Billing periods have edges, and edges are where money leaks. A customer in UTC+10 who upgrades "on the 1st" may be on the 31st as far as your server is concerned. Anchor every period calculation to a single timezone (usually UTC), store timestamps with timezone information, and never derive a billing boundary from a user's local clock.

Proration is where trust is won or lost

When a customer upgrades mid-cycle, they expect to pay the difference — not a full new charge, and not nothing. Stripe can prorate for you, but only if you let it manage the subscription lifecycle. The moment you start manually cancelling and recreating subscriptions, you own proration yourself, and customers will notice when it's off by a few dollars.

Test with real invoice previews

The single most effective metered-billing test is to create a preview invoice and reconcile it against your raw usage events for that period. If the two don't match to the cent, you've found a bug before your customer did. Do this in CI for a handful of representative accounts and you'll catch most of the gotchas above automatically.

Metering accuracy, proration, and dunning are exactly the work I specialize in. If you'd rather not learn these the expensive way, a Billing Teardown is a good place to start.