Prerequisites

• An active Recurly account.
• Configuration user access.

Limitations

• Dunning settings are versioned — changes to a campaign won't affect invoices already in dunning.
• Maximum of 50 dunning campaigns for eligible merchants.

Definition

Key benefits

Dunning campaigns

Recurly's Dunning Management lets you create multiple collection strategies for different customer groups. Every account has a default dunning campaign. Merchants with access can create additional campaigns targeted at specific plans or accounts.

Navigate to Configuration → Dunning Management to access and manage your campaigns.

Default dunning campaign

Every site has one default dunning campaign, used for all invoices that don't have a separate campaign assigned at the account or plan level. The default campaign represents your standard collection process.

For sites with multiple dunning campaigns, you can change the default using the Campaign Actions button on the campaign details page. All plans and accounts currently set to the default will automatically switch to the new default.

Dunning configuration

Modify the default dunning campaign

Campaign details

The Campaign Name is visible when selecting dunning campaigns on Plan and Account pages in the Admin Console. The Campaign Code may only contain numbers, lowercase letters, dashes, pluses, and underscores.

Dunning cycles

Dunning cycles are categorized by invoice collection method:

• Payment Declined — for automatic invoices
• Invoice Past Due — for manual invoices
• Post-Trial Payment Declined — for invoices (automatic or manual) that fail after a free trial

Each dunning campaign can include all three cycle types, each with distinct email templates and schedules.

Automatic invoice dunning cycle

For automatic invoice failures, Recurly sends a Payment Declined email and retries on the schedule you configure. You can add, remove, or modify steps, and link each step to a specific email template.

Manual invoice dunning cycle

Manual invoice dunning works the same as automatic, but uses the Invoice Past Due email templates.

Users with authority to modify the Customer section can reopen failed manual invoices. If a failed manual invoice is reopened, dunning will not resume — no dunning emails are sent and the linked subscription is unaffected. A reopened manual invoice remains in an Open state until manually closed and marked paid or failed.

Trial dunning cycle

For invoices that remain unpaid after converting from a free trial to paid, Recurly can send a Post-Trial Payment Declined email. This cycle can be limited to automatic invoices or extended to both automatic and manual.

End of dunning cycle

For each dunning cycle, you can set what happens to the invoice and subscription if the customer doesn't pay by the end of the cycle. You can also customize the final email sent when a subscription expires.

By default, Recurly marks an invoice as failed at the end of the cycle if unpaid. A failed invoice is written off as bad debt, removing the balance from the customer's account. You can configure dunning to never auto-fail the invoice, leaving it overdue indefinitely.

If invoices remain overdue after dunning, two actions will send all overdue invoices on an account back into collections:

• The customer updates their billing details.
• A new subscription is added to the account (resubscribe).

Stop dunning

To pause dunning for a subscriber who needs a few extra days, open the overdue invoice and click Stop Dunning in Invoice Actions. The invoice remains in Past Due state, but retry attempts stop, dunning emails stop, and the End of Dunning Cycle action won't execute. Account Updater continues to run if active.

Stop collection & mark paid

To end the entire collection process for a past-due invoice, open the invoice and click either Stop Collection (marks the invoice failed) or Mark Paid (used when payment was received outside Recurly). Both options close the invoice, stop retry attempts, stop dunning emails, and bypass End of Dunning Cycle actions.

Email template configuration

Dunning email templates are managed under Configuration → Email Templates. All dunning-related templates are at the bottom of the Email Templates page. Access requires the Configuration user role.

For full email template editing details, see the email templates documentation.

Create a new dunning email template

Navigate to the Dunning Management section of Email Templates. Template types available:

• Payment Declined Templates — for automatic invoices
• Invoice Past Due Templates — for manual invoices
• Subscription Expired for Non-Payment Templates — for subscriptions unpaid at the end of any dunning cycle
• Payment Declined Due to 3DS2 — for 3DS2-related declines

Click New Email Template, select a base template to start from, and give the template a name. The name is referenced when linking the template to dunning steps.

Each dunning email shares the same aesthetic as other Recurly email templates but can have distinct content at each step. Escalating urgency through messaging at each step is an effective way to prompt subscriber action.

After creating a template, link it to dunning steps on the Dunning Management page. Once linked, the association is noted on the Email Templates page under each dunning email.

Delete a dunning email template

Before deleting a template, confirm it isn't linked to any dunning step. Navigate to Dunning Management, remove the template from any campaign steps, then return to Email Templates. If the template shows "Not being sent by any current Dunning Campaigns," it can be deleted. The base Payment Declined, Invoice Past Due, Post-Trial Payment Declined, and Subscription Expired for Non-Payment templates cannot be deleted.

Updating billing info

The default Payment Declined email includes a direct link to the customer's hosted account management page for billing updates. You can add this link to your own site using the hosted_login_token parameter from the Accounts API, or modify the template to link to your own billing update form.

When billing details are updated, Recurly retries collection on all overdue invoices for that account. Automated updates via Account Updater also trigger a collection attempt.

Multiple dunning campaigns

You can create up to 50 dunning campaigns for different scenarios. Your existing configuration becomes the Default campaign. On Starter plans, all overdue invoices follow the single default campaign.

Create a new dunning campaign

Assign a campaign to a plan or account

Edit dunning campaigns

Changes to a campaign — or reassigning a different campaign to a plan or account — only affect new invoices entering dunning. Invoices already in dunning continue using the settings that were active when they became overdue.

Disable dunning campaigns

Redundant campaigns can be deactivated and won't count toward your 50-campaign limit. The default campaign cannot be deactivated — set another campaign as default first if needed.

When a campaign is deactivated, it no longer appears in the dropdown on Plan and Account pages, and any plans or accounts using it will revert to the default campaign.

Campaign priority

When multiple campaigns could apply, Recurly uses this priority order: Account → Plan → Default.

Additional priority rules:

• If no additional campaigns exist, the default applies to all invoices.
• If a campaign is assigned to a plan, it applies to all overdue invoices for that plan's subscribers.
• If a campaign is assigned to an account, it applies to all past-due invoices for that account.
• For bundled subscriptions on a single invoice: if no account-level campaign applies and multiple subscriptions use different campaigns, the campaign of the oldest subscription is used.
• For Account Hierarchy: if the billed account (parent or child) has a campaign assigned, that campaign is used. Dunning settings on the unbilled account are ignored.

Dunning best practices

See tips for improving your dunning emails.

• Extended dunning windows produce better recovery rates.
• For monthly subscriptions, limit dunning to 27 days to avoid billing overlap in February and to maximize Intelligent Retry attempts.
• Direct debit payments can take 3+ days for a response — factor this into dunning window length.
• For high-value subscribers, most merchants prefer to keep the subscription active and invoice open rather than auto-expiring.
• Use different campaign messages and durations for different plan types. For example: 27 days for monthly plans, up to 60 days for quarterly, semi-annual, and annual plans.

Review settings history

Every invoice follows the dunning configuration that was active when it entered dunning. To review past configurations, click Settings History on any dunning campaign.

For analytics on each dunning version, click View Analytics on the Settings History page. Analytics role required. Analytics are currently available for automatic payment invoices only. See the dunning effectiveness report documentation for details.

Test dunning behavior

To accelerate the dunning process in sandbox mode for testing webhooks and email delivery:

Dunning notifications via webhooks

Use webhooks to synchronize your service with collection activity in Recurly. See the Webhooks documentation for full details.

• new_dunning_event — Sent when invoices enter and remain in dunning. Use this to send custom emails or reach customers through other channels (SMS, in-app notifications, etc.).
• failed_payment — Sent after each failed payment. Use this to flag a user as overdue in your system.
• successful_payment — Sent after a successful payment. Use this to restore a previously overdue user to good standing.
• subscription_expired — Sent when Recurly expires a subscription due to non-payment or cancellation. Act on this immediately to terminate access in your system.

Transitioning from sandbox to production

Multiple dunning campaigns can be created and tested in sandbox or development mode, but are only accessible in production on Professional or Elite plans.

When transitioning a sandbox site to production under a Starter plan, all non-default dunning campaigns are deactivated. These campaigns are locked from editing and cannot be reactivated. Any plans assigned to a non-default campaign during testing revert to the default dunning campaign.

Transactions that won't retry

If your first dunning email for failed automatic invoices is scheduled after the first payment attempt, Recurly handles the following non-retryable transactions separately:

• Hard decline transactions
• Transactions failing due to incorrect billing details

Since these won't succeed without a billing info update, Recurly skips the retry schedule and waits for customer action.

Plan selection

After creating multiple dunning campaigns, you can assign specific campaigns to subscription plans in the plan details section. If an account has its own dunning campaign assigned, that takes priority over the plan's campaign.