How to set up dunning in Recurly
How Recurly handles failed payments: dunning campaigns and cycles, Intelligent Retries, dunning emails, past due and failed invoices, billing updates and webhooks.
By Florian
Recurly has one of the more complete native dunning setups among subscription billing platforms. Retries, emails, end-of-cycle actions and customer billing pages are all built in, and most of the work is choosing sensible settings and wiring the right webhooks into your app. This guide walks through each piece and gives you a setup checklist you can apply today.
Everything Recurly-specific here comes from Recurly’s own documentation: Dunning campaigns, Intelligent retries, Static retries, Dunning 101: Understanding dunning windows, Hosted account management and the webhooks reference (all accessed November 2026). Recurly also sells a separate product, Recurly Commerce, with its own dunning settings; this guide covers Recurly Subscriptions.
How Recurly splits the work: retries and dunning
Recurly treats two things separately:
- Retries decide when a declined charge is attempted again.
- Dunning decides what the customer hears, for how long, and what happens to the invoice and subscription at the end.
Both run on the same invoice at the same time, but you configure them in different places. Keeping that split in mind makes the rest of the settings easier to reason about.
Retries: Intelligent Retries and static retries
Intelligent Retries
According to the Intelligent retries documentation, Recurly uses a machine learning model to choose when to retry declined recurring card payments. It focuses on soft declines (such as insufficient funds). The documented limits:
- Retries stop at 20 total transaction attempts or 60 days from invoice creation, whichever comes first.
- Intelligent Retries does not apply to direct debit methods such as ACH and SEPA. Recurly documents those separately under direct debit retries.
- Hard declines are generally treated as final and are not retried automatically, with a few documented exceptions, for example when the customer or the Account Updater changes the billing information.
One thing to check in your own account: a Recurly changelog entry from August 2026 describes soft declines being retried up to 20 times per 30-day period to align with card network rules. That wording differs from the 60-day window on the main page, so confirm which limit applies to you with Recurly before you rely on either.
Static retries
Recurly also documents a non-ML option, static retries, driven by gateway decline codes and merchant advice codes. It stops after 7 transaction declines, 20 total attempts or 60 days since invoice creation, whichever comes first, or earlier if the dunning cycle ends first.
Whichever logic you use, retries never outlast the dunning cycle. If your dunning window is short, it caps your retries too.
Dunning campaigns and cycles
A dunning campaign is the set of rules Recurly applies to an unpaid invoice. Every site has a default campaign, and on eligible plans you can create additional campaigns and assign them to specific plans or accounts. The dunning campaigns page notes that multiple campaigns require a Professional or Elite plan. Campaigns live under Configuration, then Dunning Management. Dunning settings are versioned, so editing a campaign does not change invoices already in dunning.
Each campaign contains up to three cycle types, each with its own schedule and emails:
| Cycle type | Applies to | Default email template |
|---|---|---|
| Payment Declined | Automatically collected invoices that fail | Payment Declined |
| Invoice Past Due | Manually collected invoices past their net terms | Invoice Past Due |
| Post-Trial Payment Declined | Invoices that fail right after a free trial | Post-Trial Payment Declined |
For manual invoices, the dunning period starts the day after the invoice exceeds its net terms.
How long should a cycle be?
Recurly’s dunning windows guide recommends:
- Monthly billing: a 27-day window, so the cycle ends before the next invoice, even in February.
- Quarterly and annual billing: about 60 days.
- Weekly billing: 7 days.
These are recommendations, not hard limits. The idea behind them is sound: if a monthly cycle runs longer than a month, a second invoice lands on top of the first one, and you are now chasing two unpaid invoices from a customer who may never return.
What happens at the end of the cycle
For each cycle you choose what happens to the invoice and subscription if the customer has not paid. By default Recurly marks the invoice failed. You can also expire the subscription, keep it active, or set invoices to never fail automatically, which leaves them past due indefinitely.
A few behaviours from Recurly’s support articles that often surprise teams:
- Subscription state and invoice state are separate. A subscription can be active while its invoice is past due (support article). Base access decisions on the invoice too, not only the subscription.
- Failing an invoice does not cancel the subscription. If you want billing to stop, cancel the subscription separately (support article).
- Cancelling a subscription does not stop dunning on open invoices. Use Stop Collection on the invoice for that (support article).
- There is no native pause option in the dunning configuration.
Dunning emails
Each step of a cycle can send an email. Recurly ships base templates (Payment Declined, Invoice Past Due, Post-Trial Payment Declined and Subscription Expired for Non-Payment) that cannot be deleted, and you can create your own and attach them to campaign steps.
The default Payment Declined email already links the customer to their hosted account management page. Each account has two hosted URLs: an Account Management URL that signs the customer in, and an Edit Billing Information URL that opens only the billing form. If you host your own billing page, you can edit the template to point there instead, using the account’s hosted login token from the API.
A sensible email plan for a monthly campaign:
| Day | Goal | |
|---|---|---|
| 0 | Payment declined | Inform, one clear link to update billing |
| 3 | Reminder | Restate the link, say what happens next |
| 10 | Reminder | Short, mention access is at risk |
| 20 | Final notice | Give the exact date the subscription ends |
| End | Expired for non-payment | Confirm the end, offer a way back |
Keep each email short and focused on the billing link. Do not repeat the raw decline reason to the customer.
Billing updates trigger an immediate retry
This is one of the most useful native behaviours. According to Recurly’s docs, when a customer updates billing information, Recurly retries collection on all overdue invoices for that account. This applies to hard declines too: a new card is the one event that makes a hard-declined invoice worth retrying. For direct debit, switching to a new bank account resets the retry counter.
In practice, this means your dunning emails do not need a separate “pay now” step. Getting the customer to the billing form is the whole job.
Webhooks to listen to
Recurly’s webhooks reference and the dunning documentation list the events that matter during dunning. Which ones you receive depends on your site configuration:
| Event | When it fires | What to do in your app |
|---|---|---|
failed_payment |
After each failed payment | Flag the account, show an in-app banner |
successful_payment |
After a successful payment | Clear the flag, restore access |
new_dunning_event |
When invoices enter and remain in dunning | Track dunning state per account |
charge_invoice.past_due |
A charge invoice becomes past due (sites with credit invoices) | Start your own reminders if any |
charge_invoice.failed |
A charge invoice fails, directly or at the end of dunning | Decide on access, stop reminders |
subscription_expired |
Recurly expires a subscription, including for non-payment | Remove access |
Sites without credit invoices receive Recurly’s legacy invoice notifications instead, with different names. Check which set your site sends before writing your handlers.
A setup checklist
- Pick your retry logic. Intelligent Retries for most card businesses; check how direct debit is retried if you accept ACH or SEPA.
- Set cycle length by billing frequency. Start from Recurly’s 27-day (monthly) and 60-day (annual) recommendations.
- Choose the end-of-cycle action deliberately. Decide whether the subscription expires or stays active, and whether invoices fail. Write it down so support knows.
- Write the emails. One link per email, to the Edit Billing Information page or your own billing form.
- Add a post-trial campaign if you run free trials. The first charge after a trial fails differently from a renewal: the customer has never paid you.
- Wire the webhooks. Base access on invoice state, not only subscription state.
- Add an in-app banner for logged-in customers with a past due invoice. Emails are easy to miss; the product is not.
- Review monthly. Look at invoices that failed at the end of dunning and the decline codes behind them.
Doing this with NoChurn
Recurly’s native retries and dunning are solid, and NoChurn does not replace them: retries, invoicing and the charge itself stay in Recurly. NoChurn connects with a Recurly API key, follows Recurly webhooks and adds AI-written recovery emails that you review before they go out, with a link for the customer to update billing info. It also covers what dunning does not: cancel flows with reasons and offers (a coupon, a pause or a plan change on the Recurly subscription) and a one-click cancel button that is always visible, win-back emails at day 30, 60 and 90 based on the cancel reason, and a churn score from 0 to 100. Chargebacks come from the gateway behind Recurly; with Stripe or Braintree, NoChurn gathers the evidence and drafts a reply for you to review. See NoChurn + Recurly.