Dunning for Credit Cards

Dunning is the process of how you handle past due accounts. It involves communicating with your customers in response to failed transactions, and what action you take when the subscription can’t be renewed. Advanced Billing gives you the ability to customize these communications every step of the way.

Dunning settings have moved to Config > Retries & Dunning along with the other payment method types.

Credit card dunning.

For more information on how to configure dunning for ACH and other strategies, please our specific sections that deal with dunning for ACH or dunning for Direct Debit.

Selecting a Dunning Strategy

To get you started, Advanced Billing has put together some preconfigured dunning strategies. Choose one, and you’ll be on your way.


All of the pre-set strategies include sending an email each time we retry the payment. After selecting a strategy, you will have the option to make changes such as editing the email templates, adding or removing steps, or disabling the email message on one or more steps.

Please note that if you elect to not have a dunning strategy then subscriptions will be canceled immediately if the renewal payment fails. Once dunning is enabled, it cannot be turned off.


Select Dunning Strategy Options

This section will go over the 3 options that can be selected when first setting up a dunning strategy.

Configure your dunning options here.

Trigger dunning if mid-period component allocation payment fails

When payment for a mid-period component allocation fails, you have the option to initiate the dunning process on that subscription. Thus, the ability to initiate dunning is available if you choose to charge the allocation cost immediately, either at prorated or full cost, and the cost is not zero. If you choose to accrue instead of charging now, the dunning configuration will be ignored.

Similarly, it’s only available for components with a “charge-now” functionality. This means quantity-based components (recurring and one-time), on/off components, and prepaid allocations. Metered, prepaid, and EBB usage cannot trigger dunning as they cannot be charged immediately.

Dunning will follow the same schedule as a renewal payment failure. If the subscription renews while past due from an overdue component charges, the dunning schedule will continue as normal and not reset if the renewal fails. The default component dunning behavior can be configured per credit card dunning strategy.

If the primary fails an allocation payment, the entire group will enter dunning. If a single group member fails an allocation payment, only that member will enter dunning. Please note that this is different than remittance dunning behavior.

Additionally, you can set the dunning behavior per component allocation. More information on this can be found here.

Note that remittance dunning handles component dunning by default and that this behavior can't be disabled.
If this option is enabled a subscription that is set with a future start date and in an awaiting signup state will enter dunning if the signup fails. If this option is disabled the subscription will immediately be canceled.

End dunning after first payment failure

If this option is selected the strategy will have only one step on day 1 which will immediately cancel or mark the subscription as unpaid. This option can be used to create a one-step dunning process for your customers.

Configuring your Dunning

Dunning is configured from the “Retries and Dunning” section in your settings.

Configure your dunning settings for credit cardholders

Configuration is managed in separate sections:

  1. Email Settings
  2. Retry and Dunning Schedule
  3. Final Step

Email Settings

Change the email address that your dunning emails are sent from, by clicking on the From Address field. If you would like to add a BCC email address to your dunning emails, add that information here:


Retry and Dunning Schedule

If the dunning strategy schedule is changed, Advanced Billing will recalculate what the current dunning step is for "today". Advanced Billing doesn't store data related to what step in the dunning process the subscription resides. Dunning is defined by the current strategy and how long the subscription has been in the dunning process.


When a subscription’s period ends, the normal renewal process attempts to charge the card on file. If that attempt results in a failure (i.e. a processor “decline”), the subscription becomes “past due”. Advanced Billing will automatically retry the failed charge according to the schedule you configure in this section. After all the steps in this schedule have been completed, you can take a “final action” on the subscription and optionally send an email.

The subscription will still try to renew at the end of its regular billing cycle if there isn’t a dunning step defined for that day.

Note: The “From Address” configured in this section will also be used as the “From Address” on your final action email. It defaults to your merchant email address.

To send an email without retrying the payment, disable the “Retry Payment” slider. This will turn off the payment retry for that dunning step.

To add an email to a retry step, move the “Send Email” slider to on to launch the email editor. Within the email editor, you can customize the subject and body of the email. You can also create a custom layout to personalize the look and feel of the email.

After adding or editing a new dunning email via the email editor, you will be able to choose whether or not to be BCC’d on this email. This email has access to custom parameters as defined in the section on Customizing Dunning Emails.

Edit the step, configure the day of the dunning email

Edit the contents of the dunning email.

Editing the dunning email template

Switch off the 'Retry Payment' setting to disable an automated retry on this dunning step

Advanced Billing imposes a limit of dunning schedule limit of 365 days and/or 30 dunning steps.


Final Step

Select the day you would like Advanced Billing to perform before you take a “Final Step”. Entering “1” in this box will cause the final action to be taken upon the very first failed attempt to renew, i.e. every step in the Retry and Dunning Schedule will be ignored.

Next, select the Final Action to take. You can either cancel the subscription or mark the subscription unpaid.

  • When you cancel the subscription, the subscription will transition to the ‘canceled’ state and it will cease to accrue any new charges. No more attempts will be made to collect the balance due. A canceled subscription can be later Reactivated.
  • When you mark the subscription unpaid, the subscription will transition to the ‘unpaid’ state, but it will continue to accrue new charges. No more attempts will be made to collect the balance due. An unpaid subscription can be moved back to active by either applying for a payment, retrying the renewal (and receiving a successful payment), or zeroing out the balance and retrying the renewal.

Finally, you may optionally specify an email to be sent upon the execution of the final action.

When you select a final action, it’s important to familiarize yourself with the differences between the unpaid and the canceled states. For more information on subscription states, please view our subscription state documentation.

Edit the contents of the dunning email.

Editing the dunning email template

Switch off the 'Retry Payment' setting to disable an automated retry on this dunning step

Advanced Billing imposes a limit of dunning schedule limit of 365 days and/or 30 dunning steps.

Testing Dunning

Throughout any part of the testing process in Advanced Billing, we absolutely recommend giving your team enough time to thoroughly test the subscription lifecycle over many weeks. In addition to testing subscriber actions, testing the dunning process is also an important part of integrating with Advanced Billing.

Here are a few tips that we recommend when testing dunning and Advanced Billing:

Using bogus payment information

  • Use the Advanced Billing test gateway to simulate successfully and failed payments
  • To use bogus payment information, enter a bogus card number or bank account number
  • After the new payment method is entered, switch the default card number to the newly entered bogus payment method.

Forcing subscriptions to past due

  • It’s important to note that you can’t force a subscription into the past due state.
  • The subscription will have to transition thereby following a sequence of events.
  • Over the course of several testing days, you may also delete the payment profile on file.
  • This creates a situation where the next payment will fail

Forcing subscriptions to enter the final step

  • Set a dunning strategy that is as short as possible
  • Follow the steps above to supply bogus payment information
  • Allow the dunning process to fully execute and allow the subscription to transition to unpaid or canceled.

Customizing your Dunning Emails

When editing your Final Action Email and Dunning Emails, you can use keywords that Advanced Billing will replace dynamically before sending the email. Custom parameters (also known as dynamic variables or liquid variables) are surrounded in double curly braces like this: {{custom_parameter}}

Parameter Description
failure_subject The reason the transaction failed. e.g. ‘Failed Credit Card Transaction’, or ‘No Credit Card On File’ depending on whether or not the client has a Credit Card on file.
from_address The “from address” defined for your dunning emails
name The name of your customer. e.g. Bill Williams
product_price The recurring price of the subscription’s current product
product_name The name of the product. e.g. Basic Plan
balance_in_cents The amount, if any, they still owe. e.g. 0 (for $0.00) or 23100 (for $231.00) Useful for conditionally adding a reminder.
balance The amount, if any, they still owe in dollars. e.g. $0.00 or $2.31
merchant_name Your merchant name. e.g. Acme Corp.
update_url The URL that the customer can use to update their Credit Card information.
masked_card_number The customer’s Credit Card, obscured to only show the last 4 digits.,e.g. XXXX-XXXX-XXXX-1
reason_for_decline The reason that a transaction was declined at the gateway.
payment_profile_exists This returns true or false depending on whether or not the client, has a Credit Card on file. It can be used to conditionally display text, based on its value.

Note: Regarding payment_profile_exists, you may use an if statement combined with payment_profile_exists in order to check to see if the payment profile is attached to the subscription.

{% if payment_profile_exists %}
  Lorem Ipsum
{% endif %}

For more information on how Dunning works, see our Dunning Introduction. For additional information on using dynamic/liquid variables, see Email Templates.

Was this article helpful?
0 out of 0 found this helpful