Stripe Subscription Billing and Dunning: What It Really Costs to Build

What this becomes once real cards start failing

The demo version is forty lines. Create a Checkout Session, listen for checkout.session.completed, set is_paid to true. It works. It keeps working for roughly ninety days, which is about how long it takes for the first cohort of cards to expire.

The failure we get called in to fix most often: a customer's card expires on the 1st. Stripe fires invoice.payment_failed. The team wired that event to suspend the account, which felt responsible. Stripe's Smart Retries then attempt the charge again on day 3 and it succeeds, because the issuer reissued the card and the card network account updater pushed the new number into Stripe automatically. Stripe fires invoice.payment_succeeded. Nobody listened for that event, because in the original build the only path to "paid" was checkout.session.completed, and a renewal never emits one. The customer is now paying full price and locked out of the product. They do not file a ticket. They open a dispute, which costs $15 plus the transaction, and they leave. The team finds out three weeks later when finance cannot reconcile the month.

None of that is a Stripe bug, it is all documented behaviour. It happens because subscription billing is a distributed state machine running between Stripe's ledger and your database, and the naive build treats it as an event handler.

Webhooks are at least once and out of order. Your handler is neither.

Two facts from Stripe's own documentation that almost no quote accounts for.

Delivery is at least once. Stripe retries failed webhook deliveries with exponential backoff for up to three days in live mode. If your endpoint returns a 500, or is slow enough that Stripe times out the attempt, you receive that event again. If the first attempt did the work and then died on the response, you do the work twice. That is how customers get double credits, duplicate seats, and two invoices for one month.

Ordering is not guaranteed. Stripe states plainly that events may not arrive in the order they were generated. A customer.subscription.updated carrying the new price can land before the one carrying the old price. Apply them in arrival order and you write stale state permanently, because no third event arrives to correct you.

A competent build does four specific things. It keeps a processed_events table with a unique constraint on the Stripe event ID, and inserts that row inside the same database transaction as the state change, so "we handled this" and "the handling" commit or roll back together. It verifies the signature with the endpoint secret and a timestamp tolerance, so a replayed payload is rejected. It returns a 2xx immediately and does the real work off a queue, because the handler's job is acknowledgement rather than business logic. And it never treats the webhook payload as truth for ordering: either re-fetch the object from the API when processing, or store the event created timestamp per object and discard anything older than what is already applied. Every outbound write to Stripe carries a deterministic idempotency key, which Stripe honours for 24 hours, so a retried job does not create a second subscription.

Dunning is a state machine, not a retry loop

Stripe already retries. Smart Retries makes up to four attempts across a window you configure in Billing settings. The retrying is free. The decisions around it are what you are paying for.

Decline codes split into two families and you must treat them differently. insufficient_funds and try_again_later are soft: retry them. stolen_card, lost_card and pickup_card are hard: never retry them, because hammering an issuer with a known bad card damages your acceptance rate across your whole account, not just that customer.

past_due, unpaid and canceled are three different endings. Which one a failed subscription lands in is a setting in your Stripe Billing configuration. Most teams never open that screen and inherit a default that does not match their product. Decide it on purpose.

An off session renewal on a European card can return requires_action, not a decline. Under PSD2 and strong customer authentication, the issuer can demand a 3D Secure step even on a merchant initiated charge. There is no code path that fixes this server side. Your only move is to send the customer the hosted_invoice_url and have them authenticate. If your dunning treats requires_action as a failure, you cancel customers who were trying to pay you.

Pre dunning beats dunning. The card expiry month is on the PaymentMethod object. Email at 30 days and 7 days before expiry. The cheapest recovery is the charge that never fails.

Channel matters more than copy. Across the SaaS products we bill for, a persistent in app banner with a one click update card link recovers materially more than an email only sequence. The email goes to whoever signed up two years ago. The banner goes to whoever is using the product today.

Then design the grace window explicitly: what can a past_due account do on day 1, day 7, day 21. Full access for a week, read only after, suspended at the end of the retry window is a defensible default. Deleting data at any point is not.

Entitlements are where the product breaks, not the payment

The question that decides your architecture: where does "this user is allowed in" live? It cannot be a Stripe API call on every request. That couples your login page to Stripe's uptime and your rate limits.

Cache the state in your own table: plan, status, current_period_end, seat count, and the event ID that last wrote it. Everything in the product reads that row. Then run a nightly reconciliation sweep that compares your table against Stripe and alerts on drift. Every book we have audited has had drift, usually a handful of accounts that are free forever because one webhook was dropped during a deploy eighteen months ago.

Plan changes are the second trap. An upgrade should charge now, a downgrade should take effect at period end. That is proration_behavior and billing_cycle_anchor on one path and Subscription Schedules on the other, and choosing wrong turns into refund conversations. Seat sync is the third: if you push quantity to Stripe every time someone adds a user, you will generate $0.37 proration invoices at random hours. Batch it.

Never hardcode price IDs. Use lookup keys, because grandfathered prices live forever and you will be running four generations of pricing at once. For usage based charges, Stripe's Billing Meters replaced the old usage records API, and meter events aggregate asynchronously, so your in app usage counter and the invoice will disagree for a window. Decide now which number you show the customer.

Tax, invoices and what surfaces in month four

Stripe Tax calculates. It does not register you. Nexus and VAT registration are your legal obligation, and no code fixes that. EU business to business reverse charge needs VAT ID validation against VIES, and VIES goes down regularly, so you must decide whether an outage blocks checkout or you accept and validate asynchronously. Some jurisdictions require gapless sequential invoice numbering per legal entity, which constrains how you configure Stripe's numbering. If you sell into India, the RBI e-mandate rules for recurring card payments add pre debit notification and authentication requirements that are weeks of work on their own.

Refunds and credit notes are not the same thing and finance cares which one support clicks. Early fraud warnings arrive before a dispute does, and refunding on the warning avoids the dispute and the fee. And build the four admin buttons: comp a month, extend a trial, refund a line, change a plan. Teams that skip them pay a developer to run scripts against production forever.

What it costs and how long it takes

These are Digital Heroes delivery bands from more than 2,000 projects.

Focused build inside an existing product: $15,000 to $60,000, typically 4 to 8 weeks. Checkout or Elements, the webhook layer done properly, entitlement caching, the dunning state machine, test coverage with Stripe test clocks, and the admin tooling. The bottom of that band is three flat plans, one currency, one country. The top is seats plus annual plus trials plus coupons.

Part of a first release: $50,000 to $130,000 in 10 to 16 weeks. Here billing is entangled with auth, roles, the pricing page, and a product that is still moving under it.

Full platform: $150,000 to $350,000 over 6 to 12 months. Usage metering, multi currency, multi entity, revenue recognition feeds, invoicing with purchase orders and ACH, and a finance dashboard.

What drives this specific capability's number up, in order of impact. First, migrating existing paying subscribers from another system or another price structure. You cannot break live billing, so it needs shadow running, reconciliation and a rollback plan, and it can double the estimate on its own. Second, plan shape: flat is cheap, seats are moderate, hybrid seats plus usage plus overage is expensive because every proration and every mid cycle change multiplies. Third, tax jurisdictions. Fourth, self serve upgrade and downgrade, because every path a customer can take alone is a path you must make safe. Fifth, annual and monthly together, which doubles the proration surface.

Separately, budget the running fees. Stripe's standard card rate is 2.9% plus 30 cents in the US, Stripe Billing adds a percentage of recurring volume on top depending on your plan tier, and Stripe Tax is charged per transaction. Check current list pricing before you model margins.

When you should NOT build this

Two honest cases.

If you sell three flat plans, one currency, no seats, no usage, do not hire anyone. Stripe Checkout plus the Stripe Customer Portal plus Stripe's built in Smart Retries and its own dunning emails, wired to one idempotent webhook that flips a status field, is two to four days of work. Everything in this article still applies, but Stripe's hosted pieces already implement most of it. Anyone quoting you $40,000 for that is selling you a state machine you do not need yet.

If your actual problem is global tax, buy a merchant of record. Paddle or Lemon Squeezy become the seller of record and file the VAT and sales tax returns for you. You pay roughly 5% plus a fixed fee instead of 2.9% plus 30 cents. Under a few million in ARR selling digital products worldwide, that spread is far cheaper than registering in twenty jurisdictions and staffing the filings. The tradeoff is real: you lose control of the checkout, payout timing, and some data. Take it anyway if tax is your bottleneck.

Similarly, if your problem is usage metering at serious scale, Orb or Metronome exist and are better than what you will build. Build on Stripe directly when your pricing is your product strategy, when you need entitlements woven into the app, or when you already have subscribers on Stripe and are fixing what is there.

How to brief and vet a developer for this

Give them three things in the brief: your full price list including the plans you are embarrassed by, the exact list of what a past_due account should still be able to do, and whether existing paying customers must be migrated. Those three decide the estimate.

Then ask these.

"How do you make a webhook handler idempotent?" The answer must include a unique constraint on the event ID committed in the same transaction as the state change. "Stripe signs the payload" is a wrong answer to a different question.

"Stripe does not guarantee event order. How do you avoid writing stale subscription state?" Re-fetch the object, or version by event created timestamp. Anything else means they have not hit it.

"Walk me through your test clock setup." If they have not heard of Stripe test clocks, they have never tested a renewal, a trial ending, or a dunning cycle. They tested a first purchase and shipped.

"Which decline codes do you never retry, and why?" and "What happens when an off session charge returns requires_action?"

"Where does entitlement live, and how do you detect drift?" Listen for a reconciliation job. Nobody who has run billing for a year is without one.

"How do you handle a mid cycle downgrade?" Subscription Schedules and period end should appear in the first sentence.

Finally, ask for a redacted webhook handler from a real project. Thirty seconds of reading it tells you more than an hour of conversation.