SaaS Billing Implementation Guide: Metered Usage, Proration, and Dunning That Actually Holds

Billing is the one system in your product that turns usage into money, and the one most teams underbuild. This guide walks the real decisions: how Stripe's meter-based usage billing works now, how proration math plays out on upgrades and downgrades, how to recover failed payments before they become churn, and the pitfalls that quietly leak revenue. It is written for founders and engineering leads who want billing that holds up at scale, not a toy integration.

6 min read8 sectionsJune 22, 2026

Pick your value metric before you write any code

The hardest part of SaaS billing is not the API. It is choosing what you charge for. A good value metric scales with the value the customer gets and is something they can estimate from information they already have. Seats, API calls, messages sent, GB processed, and active contacts are common. The test is simple: if a customer cannot roughly predict next month's bill in their head, the metric is wrong and you will spend support hours explaining invoices. Many B2B products land on a hybrid model, a per-seat base plus metered overage, for example 5 seats at $50/month with 1,000 included AI credits each and overages at $0.01 per credit. Decide this first, because the metric drives your data model, your meter aggregation, and your pricing tiers. Changing it later means migrating live subscriptions, which is one of the most painful operations in a SaaS business.

Stripe's meter model: what changed and how it works now

If you are following an older tutorial that calls subscriptionItems.createUsageRecord or sets usage_type: 'metered' with no Meter object, it is outdated. Since API version 2025-03-31.basil, metered billing is meter-centric and event-based. The chain is: a Meter defines the event and how to aggregate it, a Price links to that Meter and sets cost per unit, a Subscription ties a customer to that Price, and Meter Events are the raw usage you send whenever something billable happens. A practical upgrade over the old system is that meters do not require a subscription to exist before you record usage, so you can meter a free trial and attach billing on conversion. Aggregation is the consequential early call. Use sum for most billing, count when every event is equal weight, last for snapshot-style state. You cannot change a meter's event name, aggregation, or customer mapping after creation, so spend ten minutes on it now to avoid a six-month-later migration.

Send usage from your own ledger, not directly from every action

Do not fire one Stripe event per billable action. Keep an internal usage ledger as the source of truth, accumulate in something fast like Redis or a database table, then flush aggregated meter events on a schedule, every minute or every hour. This keeps you under rate limits, cuts API cost, and gives you a record you control for reconciliation and disputes. Send every event with a stable unique identifier so retries are idempotent; Stripe enforces uniqueness over a rolling window of at least 24 hours. Mind the timestamp rules: event time must be within the past 35 days and no more than 5 minutes in the future. Owning the ledger also matters for a structural risk in usage billing: usage happens now, payment lands at period end. For AI or infrastructure-heavy products where each call costs you real money, a customer can run up a large bill that fails to collect after you already spent the compute. Stripe meters usage but does not gate it, so any spend cap or hard limit is logic you build.

Proration: the math that surprises people

When a customer changes plans mid-cycle, Stripe prorates flat-fee items. Upgrade from a $10 plan to a $20 plan halfway through and the next charge reflects a -$5 credit for unused time plus $10 for the remainder, a net $5. Downgrades generate a credit applied to the next invoice rather than an automatic refund. Two behaviors trip teams up. First, by default prorations are created but not immediately invoiced; if you want to bill the difference now you invoice manually, and you can preview the amount before applying. Second, metered items are not prorated, because they bill in arrears for actual usage that simply accumulates under the new price. Switching price does not move the billing date or charge immediately unless you change the interval, like monthly to yearly. If you are on API version 2025-06-30.basil or later, flexible billing mode adds a proration_details object that ties each credit to the original debit, which makes reconciliation far cleaner. To avoid applying an upgrade when payment fails, combine the immediate invoice with pending updates so the change only sticks once paid.

Dunning: where most recoverable revenue is left on the table

Roughly 15% of recurring card payments get declined, often from expired cards rather than insufficient funds, and the median SaaS company sees payment failures on around 7% of renewals. Without a recovery system a large share of that becomes permanent loss, and involuntary churn from failed payments commonly runs 20-40% of total churn. The fix is structured dunning. Automated dunning recovers in the 60-80% range versus 10-20% for passive single retries. A solid baseline retry schedule is roughly Day 1, Day 3, Day 5, and Day 7, paired with 3-4 emails and at least one SMS over about two weeks. Prevention beats recovery: pre-dunning notifications that prompt customers to update an expiring card before the charge can stop a meaningful chunk of failures from happening at all. And messaging matters; reminding customers of the value they lose by lapsing tends to convert better than a generic 'update your payment method' note. Build retries, smart timing, and a card-update flow as first-class parts of billing, not an afterthought.

Invoices, tax, and revenue recognition you cannot skip

Once money moves you inherit compliance. After Wayfair, US states can require sales tax collection based on economic activity alone, with revenue thresholds catching sellers sooner as transaction-count thresholds disappear. Stripe Tax calculates and collects at roughly 0.5% per transaction and is easiest when Stripe is already your stack, but on its own it is calculation, not filing or remittance. Avalara and SaaS-native tools like Anrok handle deeper filing and multi-system nexus when complexity grows. On the accounting side, ASC 606 requires recognizing revenue as you deliver the service, not when you collect. An annual prepay becomes deferred revenue recognized monthly; usage charges need estimation rules; upgrades, downgrades, and non-refundable cancellations each change the schedule. The sequencing advice that saves audits later: document your accounting policy first, then configure tooling to enforce it. Budget for Stripe Billing's roughly 0.7% fee on usage-based subscriptions on top of processing fees when you model margins.

The pitfalls that quietly leak revenue

A few failure modes show up again and again. Webhooks are where billing silently breaks, so handle invoice.created and payment events with retry logic and verify signatures; the invoice.created event gives you about an hour before finalization to adjust. Expect no metered line items on a flexible-mode first invoice, because there is no prior usage, that is correct behavior. To fix over-reported usage you send a negative meter event to offset; net usage below zero just reports as zero quantity, there are no negative invoices. Above all, run reconciliation: sync your internal usage ledger against Stripe regularly to catch drift between what you metered and what you billed. Add in-product usage visibility and spend alerts so customers never get bill shock, which is a product problem, not a billing footnote. Each of these is cheap to build early and expensive to retrofit after you have thousands of live subscriptions.

How Pineido approaches a billing build

Billing is exactly the kind of system that benefits from a tight, fixed scope rather than an open-ended rebuild. In a Pineido 30-day sprint at $8,500 we treat billing as one system end to end: the usage ledger as source of truth, meter and pricing setup with the right aggregation locked in, proration behavior matched to how your customers actually change plans, a dunning sequence with retries and a card-update flow, webhook handling with reconciliation, and the reporting you need to trust the numbers. If you are pre-revenue and building the product around billing, that often pairs with MVP work; if you have a billing system that quietly leaks, stabilization is the better fit; and if you need someone to own the architecture decisions, fractional CTO covers it. The goal is the same: billing you can scale on without firefighting invoices every month.

Kostadin Stamboliev

Founder and Imaginator

LinkedIn

Founder and Imaginator at Pineido. Practitioner across IT consulting, app and web development, technical SEO, and AI / automation. Ships production code in 30-day sprints with fixed scope and clear ownership.

Frequently asked questions

Should I build billing in-house or use Stripe Billing?

For almost every SaaS, build on Stripe Billing rather than rolling payment retries, proration, and tax from scratch. The work that adds value is your usage ledger, your meter design, and your dunning and reconciliation logic on top. Reserve a heavier platform like Metronome for genuinely complex enterprise contracts, prepaid credits, and high-volume real-time metering.

How do I set up metered billing in Stripe today?

Create a Meter and choose its aggregation carefully, since name, aggregation, and customer mapping are fixed after creation. Link a Price to that Meter, attach it to a subscription, then send idempotent meter events from your own usage ledger on a batched schedule. The old createUsageRecord pattern is deprecated, so ignore tutorials that use it.

How much failed-payment revenue can dunning actually recover?

Automated dunning typically recovers 60-80% of failed payments, compared with 10-20% for passive single retries. A schedule around Day 1, 3, 5, and 7 plus a few emails and an SMS does most of the work, and pre-dunning card-update prompts prevent a meaningful share of failures before they happen. Since failed payments drive a large slice of churn, this is often several points of MRR.

How does proration work on upgrades and downgrades?

Stripe prorates flat-fee items: a mid-cycle upgrade nets a credit for unused time plus a charge for the remainder, while a downgrade creates a credit applied to the next invoice. Prorations are created but not billed immediately unless you invoice manually, and metered items are not prorated because they bill in arrears for actual usage. Use pending updates so an upgrade only applies once the new invoice is paid.

Do I need to handle sales tax and revenue recognition from day one?

You need a plan for both before you scale. Stripe Tax calculates and collects sales tax at about 0.5% per transaction but does not file or remit; Avalara or SaaS-native tools handle deeper filing as nexus grows. For accounting, ASC 606 means recognizing revenue as you deliver service, so annual prepays become deferred revenue. Document the policy first, then automate it.

What are the most common SaaS billing mistakes?

Unreliable webhook handling, firing one Stripe event per action instead of batching from a ledger, no reconciliation between metered and billed usage, no spend caps on usage-based plans, and treating dunning as an afterthought. Each is cheap to build early and expensive to retrofit once thousands of subscriptions are live.

Ready to ship?

Tell us where you are stuck. We will review it and send a focused recommendation within one business day.

Get operations insights weekly

Join service-business operators who get one actionable insight on ops, automation, and growth every week.

Checking that you're human. You can send in a moment.

No spam. Unsubscribe anytime.

You’re subscribed! Look for our next issue in your inbox.