How to recover failed payments in Chargebee

Chargebee has a mature dunning system: it classifies payment errors, retries on its own schedule or yours, emails customers with a link to update their card, and applies a final action when nothing works. Most of the recovery you can get from Chargebee comes down to a handful of settings and how well your emails are written. This guide explains those settings and what to add around them.

It sticks to Chargebee’s own documentation: Dunning, Smart and manual dunning, What is Smart Dunning, which webhook fires during dunning, the Invoices API, the payment_failed event, the Self-Serve Portal and how customers update their payment method (all accessed November 2026). Chargebee has two generations of dunning; this guide describes the current one and flags where the older version differs.

How Chargebee dunning works

When an automatic renewal charge fails, the invoice enters dunning. Chargebee then retries the payment and sends reminder emails during a dunning period: the number of days the invoice stays in dunning before the final action is carried out. Retries only happen inside that window.

With auto-collection on, the subscription stays Active during dunning. What happens after depends on your settings.

Two retry modes

Chargebee’s Dunning page describes two modes:

	Smart mode	Custom mode
Who picks the timing	Chargebee, based on the gateway error	You, as days after the first failure
Maximum retries	Up to 12	Up to 5
Hard declines	Not retried until the payment method changes	The docs describe retries on the days you set
Exact dates	Not guaranteed	Fixed

Smart mode classifies gateway error codes as hard or soft declines. Hard declines wait for the customer to update their payment method. For soft declines, Chargebee chooses a time to retry based on the error category and the chances of recovery. Chargebee’s docs say exact retry dates cannot be guaranteed in this mode. A manual “Collect Now” also counts as a retry. One Chargebee help article notes that Smart Dunning is available from specific plans, so check yours.

Custom mode lets you set retry days. Chargebee’s example: with an 8-day dunning period and a retry frequency of “1,4,8”, retries run 1, 4 and 8 days after the first failure.

Chargebee also markets Revive, a machine-learning retry mode that runs inside Smart Dunning’s limits. Check with Chargebee for availability on your plan.

3D Secure failures

Whichever mode you pick, Chargebee says payments that failed because of 3D Secure are retried only the day before the dunning period ends, if the customer has not acted. Those customers need to complete authentication themselves, so the email is what recovers them, not the retry.

The final action

When all retries fail, you choose what happens to:

• the subscription: cancel it, or keep it active;
• the invoice: mark it not paid, write it off, or void it.

Cancelling is the strict option; keeping the subscription active with the invoice unpaid gives you more time to reach the customer, at the cost of serving someone who has not paid. Choose on purpose rather than leaving the default.

Dunning v1

Older sites may still be on Dunning v1. Chargebee’s own help articles give different retry counts for v1, so if your site uses it, check the settings in your dashboard rather than relying on an article, and consider moving to the current version.

Dunning emails and the card update link

Chargebee sends dunning emails during the retry attempts, and those emails include a link where the customer can update their payment method on Chargebee’s hosted pages (update payment method guide). Chargebee can also notify customers when a card is about to expire, has expired or becomes invalid.

There are three other ways to get a new payment method:

1. Request payment method. From a customer or subscription page in the dashboard, staff can send a secure link to Chargebee’s hosted page.
2. Self-Serve Portal. Once enabled under Settings › Configure Chargebee › Checkout and Self-Serve Portal, customers can manage payment methods and pay unpaid invoices (Self-Serve Portal).
3. API. The hosted pages API for managing payment sources returns a URL you redirect the customer to, if you want the link inside your own app or emails.

The default email templates are a starting point. Edit them so the customer recognizes your brand, understands what failed, and sees one clear button.

Events and webhooks

Chargebee’s guidance for following dunning is to listen to payment_failed and read the invoice’s dunning_status:

dunning_status	Meaning
in_progress	The invoice is in dunning, retries remain
exhausted	The last retry failed; the dunning period is over
success	A payment was collected during dunning
stopped	Dunning was stopped for this invoice

Each failed attempt during dunning generates a payment_failed event; only the last one carries exhausted (which event marks the end of dunning). payment_succeeded fires when a payment is collected. Use these to keep your own records in sync, to stop any extra communication the moment a payment succeeds, and to know when the final action has happened.

A recovery setup, step by step

1. Pick a retry mode. Smart mode is the sensible default for card payments if your plan includes it, since it skips pointless retries on hard declines. Use Custom mode if you need predictable dates, for example to match when your customers are paid.
2. Set the dunning period to fit your billing cycle. A monthly plan cannot wait as long as an annual one.
3. Choose the final action for the subscription and the invoice deliberately.
4. Turn on and rewrite the dunning emails. Send the first one on the first failure, with the update link. For hard declines, the email is the only thing that will recover the payment.
5. Handle 3D Secure separately. Tell those customers that their bank needs them to confirm the payment, and send them the link right away.
6. Enable the Self-Serve Portal so customers who ignore the email can still fix their card from your app.
7. Turn on card expiry notices to catch failures before they happen.
8. Listen to payment_failed and payment_succeeded and log the outcome by error type, so you can see which failures your setup recovers and which it does not.

What to add on top

Chargebee’s retries and emails cover the basics well. What it leaves to you is mostly communication: emails that read like they come from a person, in the customer’s language, that say what to do for the specific failure; replies that reach someone; and a follow-up for customers who were lost so you can try to win them back.

Doing this with NoChurn

NoChurn connects to your Chargebee site with an API key and follows its webhooks. It runs next to your Chargebee dunning settings: it sends recovery emails written by AI, reviewed by you, with a link for the customer to update their payment method, and it adds cancel flows, win-back emails at day 30, 60 and 90, and a churn score from 0 to 100. Invoicing, the charge itself and your payment gateway stay with Chargebee. Disputes come from the gateway behind Chargebee; with Stripe or Braintree, NoChurn gathers the evidence and drafts a reply that is sent only after you review it. NoChurn is free under $300 MRR. See NoChurn + Chargebee.