Usage metering wired to Stripe's Meter API, tiers configured, proration logic tested, webhooks handled idempotently. Monthly subscription delivery.
- Scope
- Ship
- Iterate
monthly subscription
Who this is for
SaaS founder who has outgrown flat pricing and needs tiered, per-seat, or usage-based billing — but the logic is too complex to wire up in the Stripe dashboard without an engineer who has done it at scale before.
The pain today
- Usage events fire but Stripe records nothing — meter events lost, invoices wrong
- Mid-cycle seat additions not prorating correctly; customers getting surprise charges
- Webhook handler duplicating usage records on retry — no idempotency layer
- Customer portal missing credit balances, usage visibility, and retention-focused cancel flow
- Flat pricing leaving revenue on the table as power users consume far more than others
The outcome you get
- Stripe Meter API wired end-to-end: events in, accurate invoices out
- Tiers, proration, and mid-cycle plan changes configured and test-clocked
- Idempotent webhook handler with dead-letter queue for every billing event
- Self-serve portal: plan changes, usage display, payment methods, cancellation flow
- Dunning sequence and smart retry configured per plan tier
Subscription models by business type
Stripe handles four subscription shapes, and picking the wrong one creates rework. Flat subscription — one product, one monthly price — covers content SaaS and single-tier tools cleanly. Per-seat tiered (Starter/Pro/Enterprise with seat counts) is the right model for most B2B SaaS; Stripe prorates seat additions automatically when configured correctly. Metered usage — API calls, storage, compute minutes — uses Stripe's Meter entity to decouple event collection from pricing, then invoices at period end. Hybrid (base fee plus usage overages) is what most product-led SaaS grows into at scale.
I pick the model with you based on how your buyers actually decide to pay, then configure Stripe to match that. In 17 years I have never seen a billing architecture that saved money by being clever; the ones that stay maintainable are the ones that map directly to how the product is sold.
Stripe Meter API wired end-to-end: events in, accurate invoices out
Stripe Meter API and usage metering patterns
Stripe's Meter entity (introduced 2024) decouples usage collection from pricing — you can attach a new price to an existing meter without migrating historical data. Three patterns matter in practice.
Real-time meter events posted on every action: most accurate, higher Stripe API volume, right for high-value or low-frequency events like AI inference calls. Batched aggregation (hourly or daily jobs): lower API cost, acceptable latency for storage or compute models. Calculated at invoice time (your app owns the counter, writes once per period): simplest, works only when usage is additive and your database is the authoritative record.
For most SaaS teams, batched hourly hits the sweet spot. Stripe should not be your source of truth for usage — your database is. Stripe's meter summaries are for billing; your internal records are for debugging, auditing, and showing customers real-time usage in the product.
40+: Payment providers integrated.
Webhook handling and idempotency
Billing bugs almost never come from the Stripe configuration. They come from webhook handlers that process the same event twice. Every usage record call needs an idempotency key — a UUID generated by your system that Stripe uses to detect and discard replays. Without it, a network timeout on your side triggers a retry that Stripe honors, doubling the charge.
A production-grade billing webhook handler does four things: validates the Stripe signature before touching any data, returns 200 immediately and processes asynchronously, stores the raw payload for audit and replay, and routes failed events to a dead-letter queue rather than silently dropping them. I wire this up as a dedicated worker decoupled from your main application. The architecture pattern is identical to what kept bolttech's Payment Service at 99.9% uptime across 40+ payment providers — the scale is different, but the discipline is not.
Customer portal and self-serve billing UI
Stripe's hosted Customer Portal covers roughly 80% of self-serve needs: view invoices, update payment method, change plan to pre-configured options, cancel subscription. For the other 20% — custom cancellation flow with retention offers, real-time usage display, credit balance visibility, invoice download in specific formats — I build a custom UI on top of Stripe APIs.
The decision is straightforward: how much billing UX control do you need versus how fast do you need to ship? Most teams start with the hosted portal and add a custom layer only after churn data confirms that the cancellation flow is a retention lever worth engineering. I scope both options and give you the honest tradeoff before writing a line of code.
Testing billing before it goes live
Stripe Test Clocks let you simulate time-travel through a subscription lifecycle — advance the clock past a billing period, trigger a mid-cycle upgrade, simulate a payment failure — all without touching production. I run every subscription shape through Test Clocks before the first real customer is invoiced.
Typical test matrix: initial subscription creation, mid-cycle seat upgrade with proration check, downgrade scheduled at period end, usage meter overage invoice, failed payment triggering dunning sequence, and cancellation with grace period. Finding a proration bug in Test Clocks takes minutes. Finding it in production takes a customer complaint, a Stripe dispute, and a manual credit.
When Stripe Billing isn't the right tool
Stripe Billing covers around 90% of SaaS billing needs. Where it strains: invoice volumes above 100k per month (move to custom invoicing); revenue recognition separate from cash collection (integrate with NetSuite or a dedicated RevRec layer); marketplace payouts with complex split logic across many sellers (Stripe Connect, sometimes augmented with custom ledger logic).
For most teams the honest answer is that Stripe Billing does what they need and they have simply not configured it yet. Rebuilding billing infrastructure is expensive and disruptive. Un-used Stripe features cost nothing. I will tell you directly when you have outgrown Stripe versus when you are under-using it.
Pricing and timeline
Stripe Billing work sits in the Applications Standard tier at $4,999/mo for most subscription setups: tiered pricing, per-seat models, or single-meter usage billing. Complex multi-tenant usage metering, enterprise billing with custom invoicing, or marketplace payout splits moves to Pro at $5,499/mo.
First-version timelines in practice: tiered subscriptions with portal in 2 to 3 weeks; usage-based or hybrid with idempotent webhook architecture in 4 to 6 weeks. The subscription continues through refinement — dunning tuning, portal customization, new tier rollouts. Test coverage for every billing state transition ships as part of the delivery, not as an optional add-on. 14-day money-back, cancel anytime, Work Made for Hire.
Recent proof
A comparable engagement, delivered and documented.
Unified payment orchestration across Asia and Europe
Delivered the payment orchestration platform at bolttech, a $1B+ unicorn, with 40+ integrations across multiple regions.
Read the case studyFrequently asked questions
The questions prospects ask before they book.
The old metered billing tied usage records directly to a subscription item. The new Meter entity decouples event collection from pricing — you can attach a new price to an existing meter, create multiple price points from the same usage data, and start recording events before a subscription even exists. For most new SaaS builds I use the Meter API; the legacy approach is still viable for simpler models but will be phased out over time.
Yes. Many SaaS companies run flat plans for SMB accounts, usage-based for power users, and custom-quoted enterprise deals simultaneously. Stripe handles all three through separate Products and Prices, with customers subscribed to the combination matching their deal. The billing UI shows one unified view per customer. The complexity is in keeping the admin side manageable, which is why I build the plan configuration in code rather than clicking through the Stripe dashboard.
Stripe prorates automatically. On upgrade, the system issues an immediate credit for the unused portion of the old plan and a prorated charge for the new plan from the change date to period end. On downgrade, the common pattern is to schedule the change at period end to avoid a credit invoice. The behavior is configurable per plan-change type; I set and test sensible defaults in the first version so edge cases do not reach your support queue.
Stripe Smart Retries plus a custom dunning email sequence. A failed charge triggers up to three retries over one to three weeks, timed by Stripe's ML model. Each failure sends a branded email to the customer. After the final retry the subscription moves to past_due, then to canceled after a configurable grace period. I tune the retry window and email content per plan tier — annual subscribers get a longer grace period than monthly ones.
Stripe Test Clocks let you advance time through a subscription's full lifecycle in a sandbox. I run every model — initial charge, mid-cycle upgrade, downgrade, usage overage, payment failure, dunning, cancellation — through Test Clocks before go-live. Finding a proration misconfiguration in a test environment takes a few minutes. Catching it after invoicing a real customer takes a dispute, a manual Stripe credit, and a support conversation.
Yes. For deals closed by sales with custom terms, Stripe Invoices work alongside Subscriptions. Custom line items, NET-30 payment terms, purchase order references, and multi-line invoices are all supported. The admin UI I build lets account executives generate and send custom invoices without engineering involvement — which matters at the stage where deals are closing faster than the engineering team can keep up.
Stripe Subscription Schedules handle this. A customer commits to a 12-month term but pays monthly; cancellation honors the commitment period. The alternative is a single annual charge with monthly Subscription Items tracking seat usage for reporting — which model fits depends on how your sales team structures deals. Both patterns are supported; I scope the right one based on your contract templates.