Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 38 ยท Subscriptions and Billing

Billing Portal, Failed Payment Retries and Dunning

Reduce churn from failed payments. Set up the Stripe Customer Portal, understand Smart Retries and dunning emails, handle invoice.payment_failed, and build a runnable retry schedule simulation.

Subscription businesses lose revenue in two ways: customers who decide to leave (voluntary churn) and customers whose payment fails by accident (involuntary churn): an expired card, a replaced card number, a temporary lack of funds, a bank that wants authentication. Involuntary churn can be a surprising fraction of all cancellations, and it is the easiest kind to win back. This lesson covers the tools Stripe gives you: the Customer Portal for self-service, retries for automatic recovery, and dunning (the sequence of reminders) for the customers who need to act.

The Customer Portal

Building a page where customers update their card, change plan, download invoices and cancel is tedious and security-sensitive. The Customer Portal is a hosted page that does all of it. You create a portal session for a signed-in customer and redirect them to its URL.

JavaScript
// Real Stripe usage (read-only).
app.post("/billing", requireLogin, async (req, res) => {
  const session = await stripe.billingPortal.sessions.create({
    customer: req.user.stripeCustomerId,       // from YOUR session, never from the request body
    return_url: "https://example.com/account",
  });
  res.redirect(303, session.url);
});

In the Dashboard you configure what the portal allows: update payment methods, view invoices, switch between products you list, change quantities, apply cancellation reasons, offer a retention coupon before cancelling, and choose cancel-at-period-end or immediate. Changes made there reach your server as the usual subscription webhooks, so you write no extra code beyond the redirect.

Always take the customer ID from your authenticated session. If the browser can send a customerId, anyone can open another person's billing portal.

What happens when a renewal fails

sequenceDiagram
  participant S as Stripe
  participant C as Customer
  participant M as Your server
  S->>S: Renewal invoice, charge fails
  S-->>M: invoice.payment_failed
  S-->>C: Email: update your card (optional)
  S->>S: Smart Retry after a few days
  S->>S: Retry again...
  alt retry succeeds
    S-->>M: invoice.paid, subscription active
  else all retries fail
    S-->>M: subscription canceled or unpaid
  end

Subscription status is past_due during the retry period.

Each failed attempt records a decline code, and Stripe decides what to do:

  • Soft declines (insufficient funds, generic issuer decline, authentication required) may succeed later, so Stripe retries them.
  • Hard declines (stolen card, closed account, invalid number) will never succeed with that card; retries are pointless and the customer must supply a new method.

Smart Retries use machine learning on aggregate payment data to choose the retry time most likely to succeed, for example just after typical payday, rather than a fixed schedule. You configure the policy in the Dashboard: how many attempts over how long (commonly up to about two weeks), and what to do when they run out: cancel the subscription, mark it unpaid, or leave it past_due.

Dunning: asking the customer to help

Dunning means communicating with customers about overdue payments. Stripe can send these emails for you: failed-payment notices with a link to the hosted invoice page where the card can be fixed (and 3D Secure completed), plus upcoming-renewal and expiring-card reminders. Even if you use your own email, the link target is the same: the hosted invoice URL or a portal session.

A good dunning sequence is firm but kind:

  1. Day 0: "Your payment didn't go through. Update your card here."
  2. Day 3: a reminder with the same link and what will happen.
  3. Day 7: a warning that access will be paused.
  4. Final: confirmation of cancellation and an easy way to come back.

Recover failed payments

Smart Retries Retry at likely-success times
Dunning emails Ask the customer to help
Portal Self-service card update
1 / 2

Simulating retries and dunning

This stand-in shows how a recovery policy behaves. The success probabilities are invented, and the schedule is not Stripe's; use it to reason about what a retry window buys you.

Node.js A retry schedule simulation (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Handling invoice.payment_failed in your app

Your webhook receives invoice.payment_failed. Typical reactions:

  • Mark the account past_due and show a banner with a link to the portal.
  • Keep access during the grace period, since a customer who will fix the card tomorrow should not be locked out today.
  • Do not send your own duplicate email if Stripe already does, or customers get two.
  • Log the decline code for analytics.
Node.js Reacting to payment failures (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Reducing failures before they happen

  • Card updater: networks can refresh expired or reissued card details automatically for many cards. Stripe enables this where supported.
  • Expiring-card emails: remind customers a month before expiry.
  • Offer several payment methods (a bank debit such as SEPA or ACH fails less often than cards).
  • Authenticate on-session at signup (see Strong Customer Authentication and 3D Secure).
  • Measure: track involuntary churn separately and watch decline codes.

What comes next

You now have all the pieces of taking one-time payments and running subscriptions: keys, the API, Checkout and PaymentIntents, customers, retries, prices and invoices. The rest of this course adds webhooks, marketplaces, testing, fraud and compliance. Return to the course overview at any point to continue.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which decline should NOT be retried automatically?

    Hard declines never succeed with that card. The customer must provide another one.
  2. 2. Where should the customer ID for a portal session come from?

    Using a client-supplied ID would let anyone open another customer's portal.
  3. 3. What is dunning?

    Dunning is the sequence of reminders that asks customers to fix a failed payment.
  4. 4. During the retry period, which subscription status do you expect?

    past_due marks an unpaid latest invoice while Stripe keeps retrying.

Summary

  • The Customer Portal gives customers hosted self-service for cards, invoices, plan changes and cancellation; build it from your session's customer ID.
  • Failed renewals are retried (Smart Retries) for soft declines; hard declines need a new card.
  • Dunning emails with a hosted-invoice or portal link recover many failed payments.
  • React to invoice.payment_failed with a banner and grace period, and to invoice.paid by clearing it.
  • Prevent failures with card updater, reminders and multiple payment methods.

Next: Webhooks Basics