Failed Recurring Payment Retry System

WooCommerce Subscription’s includes a Failed Recurring Payment Retry System which can help recover revenue otherwise lost due to a customer’s payment method being temporarily declined. For example, if the credit card balance reached its limit when the system attempted the first recurring payment and the bank declined the charge, Subscriptions can successfully process it a few days later when the card owner pays off the balance.

This guide provides a general overview of the system for non-technical users.

For a developer level overview, refer to the Developer Guide to the Failed Payment Retry System.

Enabling the Retry System

↑ Back to top

The retry system is off by default. Follow these instructions to turn it on:

1. Go to: WooCommerce > Settings > Subscriptions settings.
2. Scroll to the Miscellaneous settings section.
3. Tick the Enable Automatic Retry checkbox.

Subscriptions will now automatically retry payments that fail and meet the following requirements:

• Subscription uses Automatic recurring payments; and
• A payment gateway that does not control the billing schedule for the subscription is in use (ex. PayPal Standard (sunset) does not allow automatic retries).

Note: The Failed Payment Retry system doesn’t trigger for SEPA payments.

Failed Recurring Payment Retry Process

↑ Back to top

The retry system works by applying a set of retry rules whenever a renewal payment fails. The full set of retry rules defines the specific behavior of the retry process between the first failure and declaring the payment as failed and no longer attempting to process the payment after a set number of retries.

The general retry process proceeds like this:

1. Automatic recurring payment fails.
2. Subscriptions checks if a retry rule exists for this specific payment failure.
3. If a rule exists, Subscriptions applies it and will:
   • schedule a pending retry event to occur after a set period of time
   • set the status on the subscription to match the status defined by the rule
   • set the status on the order to match the status defined by the rule
   • email the customer as defined by the rule
   • email store managers as defined by the rule
4. When the scheduled time for the retry event arrives, Subscriptions will retry the payment if:
   • the retry still has a status of pending
   • the order still requires payment
   • status on the subscription matches the status defined by the rule previously applied
   • status on the order matches the status defined by the rule previously applied
5. If the payment fails on this retry attempt, steps 2 through 4 repeat until there are no more retry rules.

If no rule exists, either because the system has exhausted all retry rules or cannot apply the retry system to the renewal order, Subscriptions marks the renewal order as failed and sends the Customer Renewal Invoice email to the customer (if enabled), following the normal failed renewal payment process.

Retry Statuses

↑ Back to top

When Subscriptions applies a retry rule after a failed payment, it stores a record of the retry in the database with the status of Pending. When the scheduled retry time arrives and Subscriptions starts the retry process, it sets the stored retry status to:

• Pending if the order still needs payment and the order and subscription have the status defined by the retry rule. This status signifies that Subscriptions has begun to process the retry attempt.
• Cancelled if the order no longer requires payment, or the order or subscription has a status other than a status defined by the retry rule. This signifies that the payment no longer needs to be retried.

If the payment is attempted again, after the payment gateway has finished processing the attempt, the stored retry’s status will be updated to:

• Complete if payment successfully processes for the order; or
• Failed if the renewal order still needs payment

Automatic Failed Payment Retries Information

↑ Back to top

The retry history for a given failed payment is displayed in the Automatic Failed Payment Retries box. This (meta)box is added to Edit Order for renewal orders with retries. It is only displayed on orders with failed payments. To view the retry history for a renewal order:

1. Go to WooCommerce > Edit Order for an order with a failed payment.
2. Find the Automatic Failed Payment Retries meta box toward the bottom of the screen.

Components of Retry Rules

↑ Back to top

Subscriptions uses a set of Retry Rules to control the schedule and behavior of each retry attempt. Each retry rule defines/includes the:

• Interval: Amount of wait time between the time of failed payment and retry attempt.
• Customer Email: Email to send the customer about failed payment (optional – to avoid emailing customer about all failed payments). This email is sent when the payment attempt fails, not when it is retried.
• Store Owner Email: Email to send the store owners at defined email addresses about failed payment (optional).
• Order Status: Status applied to the renewal order for the period between the time of failed payment and retry attempt.
• Subscription Status: Status applied to the subscription for the period between the time of failed payment and retry attempt.

Subscriptions provides a default set of rules, but these rules can also be customized with code discussed in the Developer Guide to the Failed Payment Retry System.

Subscriptions Default Retry Rules

↑ Back to top

The Automatic Failed Payment Retry system in Subscriptions applies five (5) default retry rules to retry failed payments over 7 days by default. Let’s take a look at each one:

1. Retry Rule 0:

• Interval: Subscriptions waits 12 hours between failed payment and first retry attempt.
• Customer Email: No email is sent to the customer.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

2. Retry Rule 1:

• Interval: Subscriptions waits another 12 hours between failed payment and retry attempt.
• Customer Email: Customer Payment Retry is sent to the customer (if enabled) to notify of failed payment and scheduled retry attempt.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

3. Retry Rule 2

• Interval: Subscriptions waits another 24 hours between failed payment and retry attempt.
• Customer Email: No email is sent to the customer.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

4. Retry Rule 3:

• Interval: Subscriptions waits 48 hours between failed payment and retry attempt.
• Customer Email: Customer Payment Retry is sent to the customer (if enabled) to notify of failed payment and scheduled retry attempt.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

5. Retry Rule 4:

• Interval: Subscriptions waits 72 hours between failed payment and retry attempt.
• Customer Email: Customer Payment Retry is sent to the customer (if enabled) to notify of failed payment and scheduled retry attempt.
• Store Owner Email: Payment Retry is sent to store owners (if enabled) to notify of failed payment and scheduled retry attempt.
• Order Status: Renewal order’s status is set to Pending.
• Subscription Status: Subscription’s status is set to On-hold.

After the fifth retry (retry rule 4) is processed, the renewal order is marked Failed and the customer is sent the Customer Renewal Invoice email (if enabled), per the normal failed renewal payment process.

Monitoring Failed Payment Retries

↑ Back to top

To help you track automatic failed payment retries, Subscriptions displays retry information in a different places throughout the WooCommerce administration area. Let’s take a look at each one:

Retry Date on Edit Subscription Screen

If a subscription is currently within the retry process, it should have a Pending retry date/time set. This date is displayed at WooCommerce > Edit Subscription. To view this date:

1. Go to WooCommerce > Edit Subscription for a subscription with a failed payment pending retry.
2. View the Renewal Payment Retry date in the Schedule box.

Failed Payment Retry Report

An overview of your entire store’s failed payment retries is also available in the Failed Payment Retry Report. This report allows you to view revenue recovered by the failed payment retry system and the average number of retry attempts before successfully processing payments in a given time period.

Retry Emails

↑ Back to top

The retry system can email the customer and/or store owner to notify them of the failed payment and scheduled retry. This makes it possible to implement a dunning process for failed payments. When defined in the retry rules, emails will be sent when a payment attempt fails, not when the payment is retried. This makes it possible to:

• notify the customer that the payment attempt failed immediately;
• inform them when it will be retried (if at all); and
• provide a link to manually complete the the payment before it is automatically retried, in case the customer knows it will continue to fail due to an expired credit card number or similar.

Subscriptions provides two default email templates — one for emailing customers; and the other for store owners. Both email templates use the WooCommerce Email system, which means they can be enabled or disabled and customized the same way as other WooCommerce emails.

Why customers don’t receive an email after the first payment failure:

The first retry (retry rule 0) is designed to address any temporary technical issues that don’t need or require the customer’s involvement to fix. Because of of this, the first retry attempt happens 12 hours after the first payment. This short timeframe doesn’t give the customer much time to log in and fix any issues, such as paying off a credit card balance. The retry system is also unsure after first failure that the issue can be addressed by the customer, as it may be other factors. Because of this, the customer is not yet contacted. For example, if a payment fails at 6:00 pm on Wednesday night. At 6:00 am Thursday morning, the payment will be retried. If that retry fails, then the customer is emailed. If the customer was emailed at 6:00 pm Wednesday night, it’s unlikely they’d seen the email until after payment was retried at 6:00 am Thursday morning. They’d check their inbox at 9:00 am Thursday morning and find two emails.

Manually Retry a Failed Recurring Payment

↑ Back to top

In addition to the automatic retry system, Subscriptions provides a method for store managers to retry a failed recurring payment. To manually retry a failed payment:

1. Go to the WooCommerce > Edit Order screen.
2. Click Actions.
3. Click Retry Renewal Payment.
4. Click Save Order.

Retry Renewal Payment Action Requirements

For this action to be displayed, these requirements must be met:

• Order must be a renewal (action is not displayed on initial orders or non-subscription orders)
• Order total must be greater than zero
• Order must have a Payment Method set
• Payment method must support payment date modifications
• Subscription must require automatic payments, not manual renewals
• Order status must be Failed or the status set by the last retry rule

Manual Customer Payment during Automatic Retry Process

↑ Back to top

Subscriptions also allows for a customer to pay for a failed renewal order even when its payment is pending automatic retry. Paying for the renewal order manually will also update the payment method used on the subscription. By default, the email sent to the customer to notify them of the failed payment and pending retry also includes a call to action and link to login and manually pay for the order to encourage them to do so.

Next Payment Date Calculation after Successful Retry

↑ Back to top

The automatic retry system does not change default behavior for calculating next renewal payment date. For most subscriptions, the next payment date is calculated based on the date the payment is successfully processed by the retry system. For example, consider a monthly subscription product purchased on 1st of February. If the automatic renewal payment fails on 1st of March but is not successfully processed by the automatic retry system until 3rd of March, the next payment date is calculated as 3rd of April, not the 1st of April. The exception to this is when the subscription contains a synchronized subscription product. If the subscription is synchronized, the next renewal pay date is calculated from the original renewal date, not the date the payment is processed. This ensures synchronized dates are preserved even when payment is late. If you want the next payment date to always be calculated from the last scheduled payment date, install WooCommerce Subscriptions – Preserve Billing Schedule.

How to Stop Subscription Renewal Payment Retry

↑ Back to top

In rare situations, when payment method on file doesn’t work, and payment retry is enabled, the renewal retry will loop and get stuck. To stop and reset the payment retry schedule, at the moment it’s only possible by changing the value for _schedule_payment_retry meta_key in the database.

Here is an example of next payment retry we want to reset:

To reset the “Renewal Payment Retry: in 12 hours”, which will bring back the Next Payment date field, go to phpMyAdmin.

Search for _schedule_payment_retry meta_key, within wp_postmeta table.

Look for the Subscription ID of the subscription we want to reset, in this example is 3392, and then click edit to change the meta_value from 2021-06-24 15:30:09 to 0.

When the meta_value of the meta_key _schedule_payment_retry is set to 0, the Renewal Payment Retry field is removed and the Next Payment date field is brought back.