The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Dunning Management

When a customer's payment fails, Recurly utilizes Dunning emails to notify the customer that their payment has failed to entice the user to enter valid payment information or remit manual payment.


The verb dun stems from a 17th century word meaning "to demand payment for a debt." This process begins when an invoice has failed its initial payment attempt for automatic invoices (credit card or ACH) or for manual invoices (check, wire, etc) when net terms pass.

Recurly provides best-in-class Dunning Management tools. For best practices, industry research, and a conceptual overview, please visit our blog.

Dunning Process Configuration

Dunning Management can be accessed from your account's Configuration menu.

On this page, users with Configuration user access can change the failed payment notification intervals, number of notification attempts, which types of notifications to send, and the desired end-result when payment is unsuccessfully collected.

There are two types of emails in the Dunning process: Automatic Payments (Payment Declined) and Manual Payments (Invoice Past Due).

Automatic Payments

For failed credit card payments, Recurly will send an email by default called Payment Declined to inform the customer that their payment failed, and prompt them to update their billing information.

Subsequent emails are sent to the merchant on the schedule that you configure under the Dunning Management section in Recurly. In order to add or remove steps to the dunning process, click the Configure Settings button.

Here you have the option to add, remove, or edit steps in the dunning process. You can also associate the dunning step with a specific email template, which you can configure in the Email Templates section of the Configuration panel or by clicking the Email Templates link from Dunning Management.

Manual Payments

The manual payment dunning cycle is configured in the same way as the automatic payments, but it uses the Invoice Past Due email templates.

End of Dunning Cycle

For both automatic and manual payment dunning cycles, you have the option to configure the behavior of the failed invoice and the subscription if the customer does not update their payment information.

By default, dunning settings will automatically fail an invoice at the end of the dunning cycle if the invoice has not been paid. A failed invoice is Recurly's way of writing it off as bad debt, removing the owed balance from the customer's account.

You can change your dunning settings to never auto-fail the invoice and leave the invoice past due. When you change the invoice dunning setting, all invoices currently in dunning (in a past due state), will still either fail or stay past due based on the previous setting, but new invoices entering dunning will start to follow the new setting. This is due to the fact that dunning settings are versioned to make sure an invoice currently in a dunning step does not change its schedule for sending email.

Users with permissions to edit the Customer section of Recurly have the option to reopen failed manual invoices. If a failed manual invoice is reopened, dunning will not restart (no dunning emails will be sent) and the associated subscription will not be effected. When a manual invoice is reopened, it will remain in an Open state indefinitely until it's closed and marked paid/failed.

If you leave your invoices past due after the dunning cycle is complete there are two ways to attempt collection again on the invoice. Both of the below actions will send all past due invoices on the account into collections.

  • Have the customer update their billing information
  • Add a new subscription to the account (resubscribe the customer)

Email Template Configuration

When you navigate to the Email Templates page, you'll see that Dunning Management Templates has its own section at the bottom of the page. You will need the Configuration user role to access this page.

For more information on editing email templates, visit the documentation for that section.

Creating a new email template

In order to create a new email template, navigate to either the Payment Declined Templates (for automatic invoices) or the Invoice Past Due Templates (for manual invoices to be paid by check, wire, etc) and click New Email Template.

You will be given the option to pick a template to create this template from so that you do not need to write the email from scratch. You will need to give the template a name, which will be referenced when linking the email with Dunning steps in the Dunning Management page.

Each Dunning email will have the same look and feel as our other email templates, but you have a deeper control over the Dunning process as there is now not just one email for each step in the Dunning process.

After you have created new emails, you can associate them with steps in your Dunning process by navigating to the Dunning Management page. After you associate an email with a Dunning step, this step will be noted on the Email Templates page under each Dunning email.

Deleting a Dunning Email Template

If you'd like to delete a Dunning email template, you first need to ensure it is not associated with any Dunning step. You can do this by navigating to the Dunning Management page, configuring your Dunning settings, and removing the template from any Dunning step to which it is associated.

Then, navigate to the Email Templates page and find the email. If there is a note that it is "Not being sent by the current Dunning settings" then you will be allowed to delete the email. Note that you cannot delete the base Payment Declined or Invoice Past Due emails.

Dunning History & Effectiveness

Each invoice will follow the dunning configuration that was active at the time when an invoice entered dunning. You can track the past dunning versions by clicking the Settings History button.

Here you are able to see each version of your Dunning settings over time so that you can always have a reference. This allows you to perform testing of different dunning schedules and assess performance over time.

For quick reference to the Analytics behind each dunning version, click the View Analytics button on the right side of each line item on the Settings History page. You need the Analytics role to access these pages. At the moment, analytics are only available for automatic payment invoices.

For more information on measuring Dunning effectiveness using Recurly's reporting, see our analytics documentation here and for best practices please visit our blog.


Webhooks can be used to keep your service synchronized with payment issues inside of Recurly.

Dunning Event

Sent when invoices enter and remain in dunning and will follow the same dunning schedule as configured under Dunning Management in Recurly. These push notifications are delivered regardless of whether or not merchants use Recurly to send customer communication. Recurly merchants use this push notification to customize customer emails for each dunning step or to reach customers using different communication channels (email, SMS, Slack channel, etc)

Failed Payment

Sent after each failed payment. Recurly merchants use this push notification to flag a user as past-due inside their application and encourage them to update payment information.

Successful Payment

Sent after a successful payment. Recurly merchants use this push notification to recognize when a previously past-due user is now back in good standing.

Subscription Expired

Sent if Recurly terminates a subscription due to non-payment or if the subscription is canceled and no longer valid. When this notification is received, the subscription should be immediately terminated in your system. This is the primary notification you should catch if you are receiving push notifications.

Learn more about Recurly's webhooks, or see our webhooks documentation for developers.

Updating Billing Info

When your customers receive a failed payment email, they need to know how to update their billing information. The default payment declined email template offers your customers a direct link to their hosted account management page, where the customer can provide updated billing information.

You can include a direct link to a customer's account management page from your website using the hosted_login_token parameter available on the Accounts API. API users can also update the email template to point to a billing update form on their own website.

Whenever billing information is updated successfully, Recurly will retry collection on any past due invoices on the account.

Stop Dunning

The Dunning process can be manually halted on an account by opening the past due invoice, clicking on the Stop Collection tab, and selecting either the Stop Collecting option, which will mark the invoice as failed, or the Mark Paid option, which will indicate that the invoice was successfully paid for (this option is typically used when funds are received outside of Recurly).

Either option will move the invoice to a Closed state and will stop all future collection attempts on the invoice.

Please note: Stopping collection on an invoice will not automatically cancel the related subscription. The subscription needs to be canceled separately in order to stop the subscription from renewing again.

A subscription will only be canceled automatically if an invoice fails dunning (assuming your dunning settings are configured to expire a subscription at the end of the dunning process).

Test Dunning Behavior

Merchants wanting to speed up the dunning behavior to test webhooks, delivery of email, and other variables may follow the below instructions to put an account through dunning in sandbox mode.

  1. Subscribe an account using the "Success" test card number: 4111-1111-1111-1111
  2. Update the account's billing information to use the "Fail, but save" test card number: 4000-0000-0000-0341 (note: it will appears this action returns an error, but this is expected. The card number will still save on the account).
  3. Speed up the renewal process by clicking "More info" on the subscription, then "Change Renewal Date" on the Subscription Details page
  4. Set the subscription's next renewal date to 1 hour in the future
  5. The subscription will renew within the hour, kicking off your dunning process.

Updated 5 days ago

Dunning Management

When a customer's payment fails, Recurly utilizes Dunning emails to notify the customer that their payment has failed to entice the user to enter valid payment information or remit manual payment.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.