A dunning campaign is how Recurly Commerce keeps subscribers in the loop when a payment fails. You define the emails, the timing, and what happens at the end of the cycle, so your team doesn't have to step in manually and your subscribers always know where things stand.

Available on all Recurly plans

1Definition 2Key benefits 3Key details 4FAQs

Prerequisites

Dunning campaigns are configured under Recovery > Dunning Management
Payment retry settings are configured under Recovery > Dunning Management
Billing error snippets are managed under Recovery > Billing Error Snippets

Limitations

Merchants can configure only one dunning campaign at a time
The dunning campaign enforces a maximum of one email per day per subscriber
Dunning emails are sent via Commerce transactional email templates. Customization is available in Notifications and Billing Error Snippets

Definition

A dunning campaign is a sequence of automated emails sent to subscribers after a payment failure. You define which emails to send, when to send them (immediately on failure or after a set number of days), and what happens at the end of the cycle if payment still hasn't been recovered. Dunning campaigns work alongside Payment Retries, giving subscribers every opportunity to resolve a failed payment before losing access to their subscription.

Key benefits

Proactive subscriber communication Keep subscribers informed at every stage of the payment recovery process with timely, relevant emails.

Flexible scheduling Send the first email immediately on failure or delay it, up to one email per day, on your schedule.

Configurable end-of-cycle outcomes Choose to pause, cancel, or leave the subscription active when the dunning cycle ends, based on your business policy.

Automatic resolution If payment succeeds at any point, the campaign ends immediately and no further emails are sent.

Full audit trail Every dunning email sent is recorded in the notification log for visibility and troubleshooting.

Key details

How dunning works with Payment Retries

Dunning campaigns handle subscriber communication, and Payment Retries handle charge recovery. Both activate on payment failure and run independently based on your configuration. Neither tool waits for the other.

Payment Retries re-attempt the charge on the schedule you've set, working silently in the background
Dunning campaign emails fire on the day offsets you define, keeping the subscriber informed and prompting them to act
A subscriber might receive a dunning email on day one while a retry attempt fires on day two, or both at the same time. The combination gives the payment every chance of succeeding while the subscriber stays informed throughout.

If payment succeeds at any point, whether from a retry or a subscriber updating their payment method, the dunning campaign ends automatically, the subscription returns to active, and no further emails are sent.

Configure a dunning campaign

In Commerce, go to Recovery > Dunning Management and select Edit Dunning Campaign. The Campaign Summary panel on the right updates in real time as you configure notifications, giving you a live preview of the full dunning sequence before you save.

The campaign configuration has two sections: Payment Failed Notifications and At the End of the Dunning Cycle.

Payment Failed Notifications

Define the emails sent to subscribers during the dunning cycle.

Choose immediate actions

Select which transactions trigger a notification as soon as the first payment fails: send for all transactions, send for non-retriable transactions only, or do nothing.

Set the timing for each follow-up notification

For each notification after the first, enter the number of days later than the previous notification. The helper text shows the number of days after the initial payment failure. For example, a 2nd notification set to 1 day later is sent 1 day after the first payment attempt fails.

Add or remove notifications

Click + Add Notification to add another email to the sequence. Click the X next to any notification to remove it.

Customize the email template (optional)

Click Edit Email Template in the top right of the section to customize the email content in Notifications.

NoteCommerce enforces a maximum of one dunning email per day per subscriber, regardless of how your campaign is configured.

At the End of the Dunning Cycle

Define what happens when the dunning cycle completes without a successful payment.

Subscription behavior determines what happens to the subscription:

Cancel subscription: the subscription is cancelled and the subscriber receives a cancellation notification
Pause subscription: the subscription is paused and the subscriber retains access until manually reactivated
Leave the subscription active: the subscription remains active and the subscriber receives one final failed payment notification
Send cancellation (or pause) notification sets when to send the end-of-cycle email. The helper text shows the total number of days after the initial failure. The Email Template field shows which template will be used. Click Edit to customize it in Notifications.

Once configured, click Save Campaign to activate.

Default campaignClick Reset to Default to restore the out-of-the-box 27-day campaign: an immediate hard decline notification, follow-ups on Days 1, 8, and 24, and a final cancellation email before terminating the subscription on Day 27.

Billing error snippets

Billing error snippets control the specific explanation a subscriber sees in a failed payment method email. Commerce receives billing error codes from Shopify when a charge fails. Each code has an email display name and an email description, which you can edit in Recovery > Billing Error Snippets.

The dunning campaign sends the same email each time, but the billing error snippet inserts targeted copy that tells the subscriber what went wrong and what action to take to bring their account back to good standing and renew their subscription.

To edit a snippet, search for the code or expand a category, then update the Email Display Name and Email Description fields. Click Save Changes to apply your edits.

The page groups the 42 billing error codes into eight categories. The tables below list each code with its default email display name and default email description.

Card-Related Issues

Billing error code	Default email display name	Subscriber call to action
`EXPIRED_CARD`	Card Expired	Update the card with a current expiration date, or use a different card.
`CARD_DECLINED`	Card Declined	Contact your bank to confirm the charge is allowed, or use a different card.
`CARD_NUMBER_INCORRECT`	Card Number Incorrect	Check the card number for typos and re-enter it.
`INCORRECT_NUMBER`	Incorrect Card Number	Re-enter the card number and confirm it matches the card in your wallet.
`INVALID_EXPIRY_DATE`	Invalid Expiry Date	Check the expiration date printed on the card and update it.
`INVALID_NUMBER`	Invalid Card Number	Re-enter the card number, expiration date, and security code.
`INCORRECT_ADDRESS`	Incorrect Address	Confirm the billing address matches what your bank has on file, then update it.
`INCORRECT_ZIP`	Incorrect ZIP Code	Confirm the billing ZIP code matches your bank records, then update it.
`EXPIRED_PAYMENT_METHOD`	Expired Payment Method	Renew the payment method or add a new one.
`PAYMENT_METHOD_DECLINED`	Payment Declined	Contact your bank, or add a different payment method.

Authentication & Verification

Billing error code	Default email display name	Subscriber call to action
`AUTHENTICATION_ERROR`	Authentication Error	Update your payment method and try again. If it fails again, contact your bank.
`AUTHENTICATION_FAILED`	Authentication Failed	Complete the verification prompt from your bank, or use a different payment method.
`AUTHENTICATION_REQUIRED`	Authentication Required	Complete the identity verification step from your bank.
`FRAUD_SUSPECTED`	Suspected Fraud	Contact your bank to confirm the charge, or use a different payment method.
`CONFIRMATION_REJECTED`	Confirmation Rejected	Confirm the payment when prompted, or update your payment method.

Billing & Payment Method

Billing error code	Default email display name	Subscriber call to action
`INVALID_PAYMENT_METHOD`	Invalid Payment Method	Update your payment method or add a new one.
`PAYMENT_METHOD_NOT_SPECIFIED`	No Payment Method	Add a payment method to your subscription.
`INVALID_BILLING_ADDRESS`	Invalid Address	Update your billing address.
`INVALID_CUSTOMER_BILLING_AGREEMENT`	Billing Agreement Invalid	Re-authorize your payment method.
`PAYMENT_METHOD_NOT_FOUND`	Method Not Found	Add a new payment method to your subscription.
`BUYER_CANCELED_PAYMENT_METHOD`	Buyer Canceled Payment Method	Restart the payment and complete it with your payment method.

System & Provider Issues

Billing error code	Default email display name	Subscriber call to action
`PAYMENT_PROVIDER_ERROR`	Provider Error	Wait a few minutes and try again. If the problem continues, contact the merchant.
`INFRASTRUCTURE_ERROR`	System Error	No action needed. The payment will be retried automatically.
`TRANSIENT_ERROR`	Temporary Error	No action needed. The payment will be retried automatically.
`PROCESSING_ERROR`	Processing Error	Try again later. If the problem continues, contact the merchant.
`UNEXPECTED_ERROR`	Unexpected Error	Try again later. If the problem continues, contact the merchant.
`GENERIC_ERROR`	Payment Error	Update your payment method and try again.

Payment Type Issues

Billing error code	Default email display name	Subscriber call to action
`AMOUNT_TOO_LARGE`	Amount Too Large	Contact your bank to check your card limit, or use a different payment method.
`TRANSACTION_LIMIT_EXCEEDED`	Limit Exceeded	Contact your bank to check your card limit, or use a different payment method.
`PURCHASE_TYPE_NOT_SUPPORTED`	Purchase Type Not Supported	Use a payment method that supports subscription purchases.
`INVALID_PURCHASE_TYPE`	Invalid Purchase Type	Use a payment method that supports subscription purchases.
`AMOUNT_TOO_SMALL`	Amount Too Small	Contact the merchant to review the charge amount, or use a different payment method.

Account Issues

Billing error code	Default email display name	Subscriber call to action
`INSUFFICIENT_FUNDS`	Insufficient Funds	Add funds to your account or use a different payment method. The payment will be retried.
`CALL_ISSUER`	Call Your Bank	Call your bank to approve the charge.
`DO_NOT_HONOR`	Do Not Honor	Contact your bank to resolve the declined charge, or use a different payment method.
`INVALID_SHIPPING_ADDRESS`	Invalid Shipping Address	Update your shipping address.

Third-Party (PayPal)

Billing error code	Default email display name	Subscriber call to action
`PAYPAL_ERROR_GENERAL`	PayPal Error	Try again, or use a different payment method.
`EXPIRED_BUYER_ACTION`	Action Expired	Update your payment method to restart the payment.

Retry & Recovery

Billing error code	Default email display name	Subscriber call to action
`RETRY_DECLINED`	Retry Declined	Update your payment method, then try again.
`OFF_SESSION_REJECTED`	Payment Rejected	Update your payment method, and confirm the payment with your bank if prompted.
`PAYMENT_METHOD_UNSUPPORTED`	Method Not Supported	Use a supported payment method.
`CANCELLED_PAYMENT`	Payment Cancelled	Update your payment method to retry the payment.

Notification log

Every dunning email sent is recorded in the Notification Log. Use it to confirm which emails a subscriber received and when, and to troubleshoot any gaps in communication.

Automatic campaign resolution

If a subscriber updates their payment method and the charge processes successfully at any point during the dunning cycle, the campaign ends automatically:

No further dunning emails are sent, even if one was scheduled for that day
The subscription status returns to active
The normal renewal schedule resumes without alteration

FAQs

What happens when retries are exhausted before the campaign ends?

If retries reach their maximum count before the final dunning notification fires, retries stop, but the dunning campaign continues on its notification schedule. No terminal action (cancel, pause, or keep live) is applied until the campaign completes through its final notification. A subscriber can exhaust all retry attempts and remain in their current status until the final scheduled email fires and the campaign ends.

Does the dunning campaign stop if a retry succeeds?

Yes. If a retry recovers the payment at any point during the dunning cycle, the campaign ends immediately. No further emails are sent and the subscription returns to active.

Can I configure different dunning campaigns for different subscription plans?

Not yet. Commerce currently supports one dunning campaign per merchant. Support for multiple campaigns assigned to specific plans is planned for a future release.

Will a subscriber receive more than one dunning email per day?

No. Commerce enforces a maximum of one dunning email per day per subscriber. regardless of how your campaign is configured.