WooCommerce Subscriptions is a premium plugin, and version 2.1 introduced a new system to automatically retry a recurring payment that has previously failed.
This system can help recover revenue otherwise lost due to payment methods being temporarily declined. For example, if a credit card balance was at its limit when attempting the first recurring payment and the charge was declined, it can be successfully processed a few days later when the card owner has paid off the balance.
This guide provides an overview of the Failed Payment Retry system and is intended to provide non-technical details for store managers. For a technical overview, refer to the Developer Guide to the Failed Payment Retry System.
Enabling the Retry System
The retry system is disabled by default. To enable it:
- Go to: WooCommerce > Settings > Subscriptions settings administration screen.
- Scroll to the Miscellaneous settings section.
- Tick the Enable Automatic Retry checkbox.
Subscriptions will now automatically retry payments that fail when certain requirements are met.
Retry System Requirements
Subscriptions does not retry all failed recurring payments. It only retries a payment for a subscription that uses:
- Automatic recurring payments; and
- A payment gateway that does not control the billing schedule for the subscription
Failed payments for subscriptions using PayPal Standard cannot be retried automatically, as the payment gateway does not allow it.
Failed Recurring Payment Retry Process
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 finally declaring the payment as failed and no longer attempting to process the payment.
The general retry process proceeds like this:
- Automatic recurring payment fails.
- Subscriptions checks if a retry rule exists for this specific payment failure.
- If a rule exists, it is applied and Subscriptions 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 the email defined by the rule
- email store managers the email defined by the rule
- 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
- If the payment fails on this retry attempt, steps 2 through 4 are repeated until there are no more retry rules.
If no rule exists, either because the all retry rules have been exhausted or the retry system cannot be applied to the renewal order, 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.
Retry Statuses
A record of the retry is stored in the database when a retry rule is applied after failed payment. This retry will be stored with the status of Pending.
When the scheduled retry time arrives and Subscriptions starts the retry process, it sets the stored retry status to:
- Processing 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.
- Canceled 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 was successfully processed for the order; or
- Failed if the renewal order still needs payment
Retry Rules
Subscriptions uses a set of Retry Rules to control the schedule and behavior of each retry attempt.
Each retry rule defines 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.
Default Retry Rules
Subscriptions applies five (5) default retry rules to retry failed payments over 7 days by default.
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.
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.
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.
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.
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 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
To help you track automatic failed payment retries, Subscriptions displays retry information in a different places throughout the WooCommerce administration area.
Retry Date on Edit Subscription Screen
If a subscription is currently within the retry process, it should have a Pending retry date set. This date is displayed at WooCommerce > Edit Subscription.
To view this date:
- Go to WooCommerce > Edit Subscription for a subscription with a failed payment pending retry.
- Find the Renewal Payment Retry date in the Billing Schedule meta box.
Automatic Failed Payment Retries Meta box
The retry history for a given failed payment is displayed in the Automatic Failed Payment Retries meta box. This metabox 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:
- Go to WooCommerce > Edit Order for an order with a failed payment.
- Find the Automatic Failed Payment Retries meta box toward the bottom of the screen.
Subscription Relationship Column of the Orders Table
If an order has failed payment retries, an additional clock icon is displayed in the Subscription Relationship column of WooCommerce > Orders. A tooltip on this icon displays number of retries of each status associated with the order.
To view the retries for an order:
- Go to WooCommerce > Orders
- Find an order with the clock icon in the Subscription Relationship column.
- Hover the mouse cursor over the clock icon to reveal the tooltip.
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 (Dunning)
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.
Manually Retry a Failed Recurring Payment
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:
- Go to the WooCommerce > Edit Order screen.
- Click Actions.
- Click Retry Renewal Payment.
- 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
FAQ
Why isn’t the customer emailed when the first payment fails?
The first retry 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.
How is the next renewal payment date calculated after a successful retry?
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.
Can a customer log in and change credit card details for a renewal that is currently pending retry?
Yes. A customer can pay for a failed renewal order egithub.com/…/woocommerce-subscriptions-preserve-billing-scheduleven 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.