Getting Started

Building Blocks

Custom Fields

Subscription Features




Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages


Reports and Analytics


Open Source Resources

Other Features

API Integration

Third Party Integrations


Retrying attempts to capture payments on invoices that are due is called dunning. Chargebee automates this process and retries the card for a maximum of three times after the initial attempt to charge the card fails. After the third retry fails, the subscription may be canceled or left active and marked as unpaid. It is completely up to you to decide what to do when a payment attempt fails and when to stop payment retries.


Dunning Management 


  1. Automated retry of payments
  2. Configurable payment retry settings
  3. Automated email notifications
  4. Customizable email templates

The settings for dunning is in the web interface under SettingsDunning Settings.

Here's how the retry settings look:

At any stage in the dunning process (between the failed initial attempt to charge the card and the three retries), you can choose to cancel the subscription, or mark the invoice as Not Paid. You can also configure Chargebee to cancel the subscription, as well as mark the invoice as Not Paid or Voided. You can also customize the time period between each retry attempt.

You can also choose to Disable dunning for trial and future subscriptions, in which case the Subscriptions in Trial and Future states will get cancelled upon the first instance of payment failure.

  • Maximum time period for each retry attempt is 45 days.
  • If an invoice has been partially paid, it cannot be marked as Voided or Not Paid (if configured under Dunning Settings), but the subscription will be canceled.

Email Communication 

You can enable email notifications to notify customers prompting them to update their card details.


If Email Notifications V2 is enabled in your Chargebee, refer this page to know about setting up email notifications for Dunning.

To enable email notifications, go to SettingsEmail NotificationsEnable Email NotificationsPayment FailedON.

Emails can be sent out after a payment has failed. If email notification for "Payment Failed" is enabled, emails are sent out based on the intervals defined in the retry settings section described above.

You can modify the email template being sent to customers. To do this, go to SettingsEnable Email NotificationsPayment FailedCustomize Template.

In the email, you can provide customers with a link to use for updating their card details or instructions on how to do it. The merge var for this is "{{customer.card_update_url}}" and is available in the "Customer" group.

How do I send different messages based on the retry attempt? 

Each time a charge is retried for a failed payment based on your retry settings a different email message can be configured in your template.

To do this, you can use our mail merge fields.

Fields specific to the retry attempt emails are available in the "Invoice" group.

{{invoice.next_retry}} - Shows the date when the next payment attempt date will be made.

{{invoice.recurring}} - Displays the charge type. Can be used to indicate if the payment failed for a recurring charge or a one time charge. The variables shown are "true" and "false".

{{invoice.dunning_status}} - Shows the stage of the dunning process. This works only for failed charge attempts on recurring charges and not for one time charges.

The possible values are:

in_progress - the dunning will still continue after the current attempt.

exhausted - after all retry attempts are over.

stopped - retry attempt stopped by canceling or marking a subscription as paid manually.

success - when the payment succeeds.

{{invoice.attempt_count}} - Indicates the current retry attempt count. You can use this as a condition variable to send different responses to the customers.

Here's a sample template for the "Payment Failed" notification:

Dear {{customer.first_name}},

{{#invoice.attempt_count = 1}}

We regret to inform you that the most recent charge attempt on your card failed.

Our next charge attempt will be on: {{invoice.next_retry}}

{{/invoice.attempt_count = 1}}

{{#invoice.attempt_count = 2}}

Our attempts to charge your card has failed again.

We will try again on: {{invoice.next_retry}}

{{/invoice.attempt_count = 2}}

{{#invoice.attempt_count = 3}}

This is to inform you that our last 3 attempts to charge your card has failed.

Our final attempt to charge your card will be on: {{invoice.next_retry}}

If this fails, your subscription will be canceled.

{{/invoice.attempt_count = 3}}

{{#invoice.attempt_count = 4}}

We regret to inform you that our last attempt to charge your card has failed and your subscription has been canceled. To reactivate your subscription, please update your payment details and contact us.

{{/invoice.attempt_count = 4}}

{{#invoice.recurring = false}}

Our attempt to charge your card for the services provided has failed.

{{/invoice.recurring = false}}

Here's the details:

Charge Attempted On: {{}}

Amount: {{transaction.amount}}

Card No: {{transaction.masked_card_number}}

Please update your billing information using the link below to ensure uninterrupted services:


If you have any questions, please contact us.



We have also included a similar template in the application you could use to get started easily.

Can I perform a manual retry? 

Yes you can. You can open the invoice that is due payment and use the Collect Now option to attempt a manual retry. This retry will not be considered as an attempt under Dunning Settings and any automated attempts left will still continue.

Can I stop dunning for an invoice? 

Yes. Say, a customer is unable to pay for a particular term and you wouldn't want to further retry the payment for that particular invoice, you can choose to stop dunning.

The invoices for which dunning has been stopped will move to a Not Paid status. You can then handle the unpaid invoices according to your choice.

You can stop dunning for an invoice using one of the following methods:

i) Via the API

Using the Stop Dunning for an Invoice API,  you will be able to stop dunning.

ii) Via web interface

In Chargebee's web interface, open a Payment Due invoice. In the right hand panel, you can find the option to Stop Dunning for that invoice, as shown:

The Stop Dunning feature will only stop the dunning process and cancel all the scheduled retries for the invoice. However, the subscription will continue to remain Active and the invoice will be marked as Not Paid, irrespective of your dunning settings.

What happens when an invoice is marked as ‘Not Paid'? 

If you've configured Chargebee to mark an invoice as Not Paid on any of the 4 attempts and NOT to cancel the subscription, no further attempts will be made to charge that invoice. Chargebee will however still continue to renew the subscription and attempt to charge the customer on the next renewal.

What happens if I set ‘Cancel subscription and mark invoice as Not Paid' as the final action? 

When the final collection attempt fails during Dunning and you have configured this option, then

  • Subscription will be canceled
  • Invoice will be marked as Not Paid
  • Other invoices, if created, during Change Subscription will also be marked as Not Paid

If the subscription is reactivated, the billing term will remain the same if it's an in-term reactivation (done within the current billing term), otherwise it will be reset to the reactivation date.

  • Subscription starts on 1st Jan
  • Dunning attempt fails on 14th Jan
  • Subscription is marked as Canceled on 14th Jan
  • User reactivates on 20th Jan
  • The subscription term will stay as 1st of every month

What happens if I set ‘Cancel subscription and mark invoice as Voided' as the final action? 

When collection attempt fails during Dunning and you have configured this option, then

  • Subscription will be canceled
  • Invoice will be marked as Voided
  • Other invoices created during Change Subscription operation will also be voided

If the subscription is reactivated, then the same billing term will be updated based on the day on reactivation.

  • Subscription starts on 1st Jan
  • Dunning attempt fails on 14th Jan
  • Subscription is marked as Canceled on 14th Jan
  • User reactivates on 20th Jan
  • The subscription term will be updated as 20th of every month

What if a customer updates their card after any one of the failed retry attempts? 

Chargebee can immediately try to charge the card and collect the invoice for the latest Payment Due invoice. To do this, you need to enable the Collect Invoice on Card Update option under SettingsSite SettingsSite Info.

Will the next renewal date change if an attempt succeeds on the last try? 

No, the subscription's renewal date will remain the same.


Renewal Date is on 20th Jan. First 3 attempts fail and on the last attempt, the payment succeeds on 5th Feb. Next renewal will still be 20th Feb and will not change even though the last charge was on 5th Feb because the renewal date will not be affected by retry attempts on a failed charge.

For what sort of payment failures does dunning management apply? 

  1. When a trial subscription ends and automatically switches to a paid subscription.
  2. When a paid subscription automatically renews.

When do Dunning Settings not apply? 

  • When you apply a one time charge or an addon to a subscription.

  • When you attempt to manually collect a Not Paid invoice (using the Collect Now option) and that payment attempt fails.

  • Dunning Settings is unavailable for direct debit payments, such as payments made through GoCardless, ACH with Stripe and ACH with Authorize.Net

See also