Troubleshooting WooCommerce Subscription Renewals
Estimated reading time: 7 minutes, 46 seconds.
Note, this article does not cover issues where the payments fail, but the scheduled actions are running correctly. For more about this, there’s a very indepth article about the Failed Recurring Payment Retry System in the official documentation.
Having a digital membership subscription website can be great business model. Once the system is set up, you can attract larger amounts of new customers with only slightly more amount of work that you have to do to support them. However, it takes several pieces of software to accomplish this. Every additional step and plugin added creates another potential failure in the automated system. One of the most concerning is when the automatic renewal orders don’t get created or fail to get automatically paid. On our client’s membership sites and with internal projects, we leverage the awesomeness that is WooCommerce Subscriptions, processing payment through PayPal or Stripe. There’s lots of other payment gateways available to use with WooCommerce Subscriptions, but PayPal & Stripe are the two ones that we have the most experience with and so will be covering in this article.
There are 2 main problems that can occur when renewals fail:
- The renewal order is created correctly, but then payment isn’t able to go through. In this case, most frequently a customers access would get cut off, as their accompanying membership would probably be put on hold.
- The system fails in the renewal order creation point, resulting in the system giving users access but not charging them for it.
It’s important to note how the WooCommerce Subscription system does this. Upon creation of a subscription, the software will create an action that is scheduled in the future. The action we’re most concerned with is creation & processing of a renewal order.
When there is an error in collecting payment, the system creates a notification that a subscription renewal has failed. This notification shows up on the backend of the website.
This warning is dismissible, but I recommend leaving it on your dashboard until you have remedied each of the subscriptions. You can click the link on each of the subscriptions, which will take you to the individual subscription page. Unfortunately, there isn’t information on this page about why this failed. There will also be a link that says “to see further details about these errors view the “field – schedule-actions log file from the WooCommerce logs screen”. That’s the place you want to go to figure out WHAT is causing this to happen. In our experience, these aren’t just temporary glitches, but will show up in increased frequency.
For PHP fatal errors that interrupt the creation of renewal orders, I have found that the WooCommerce Subscription system does not give dashboard notifications. We’ve got an outstanding customer service ticket to make them aware of this. In the meantime, I highly recommend you install the free plugin Fatal Error Notify which will send you an email notification whenever a fatal error (or other error level you’ve configured) is detected on your site.
Consequences of failed renewals
When your renewal payments fail to charge (different than when payments fail), your customers are going to experience a disruption to your subscription service. connected to commerce memberships, then their membership status may be put on hold until the renewal order is paid for. In the event of renewal orders failing to generate, your customers will continue to have access to your digital membership product, but they won’t have paid for it. Depending on which problem occurs, you could either end up with a lot of unhappy customers had a lot of support ticket so you need to respond to, or potentially months of lost revenue.
Identifying the likely cause of errors
You could always turn on the WP_DEBUG constant and pour through the debug.log on the server, but WooCommerce thankfully gives us a better tool for researching and managing. You’re going to want to navigate to the page WooCommerce > Status. Then click the “Scheduled Actions” tab at the top. or use the link https://YOURWEBSITE.com/wp-admin/admin.php?page=wc-status&tab=action-scheduler. There are 5 filters for the scheduled action based on where they are in the process. If you are just looking in general, check out the Failed filter. Otherwise enter your faulty subscription id number into the search bar.
If an action was scheduled in the past but failed to process, you’re going to see a date listed in the “scheduled date” column. When perusing new clients logs during audits, sometimes I find actions that were scheduled for five years ago and failed. It’s important to note that these logs do not clear on their own.
The “log” column is where we’re doing our forensic work. From the screenshot example above we can see the following message:
2022-02-09 04:06:04 +0000 unexpected shutdown: PHP Fatal error Uncaught Error: Call to a member function needs_payment() on null in /home/customer/www/website.com/public_html/wp-content/plugins/woocommerce-gateway-paypal-express-checkout/includes/class-wc-gateway-ppec-checkout-handler.php:578 Stack trace: #0 /home/customer/www/website.com/public_html/wp-includes/class-wp-hook.php(307): WC_Gateway_PPEC_Checkout_Handler->maybe_disable_other_gateways(Array) #1 /home/customer/www/website.com/public_html/wp-includes/plugin.php(189): WP_Hook->apply_filters(Array, Array) #2 /home/customer/www/website.com/public_html/wp-content/plugins/woocommerce/includes/class-wc-payment-gateways.php(163): apply_filters('woocommerce_ava...', Array) #3 /home/customer/www/website.com/public_html/wp-content/plugins/woocommerce-point-of-sale/includes/wc-pos-core-functions.php(312): WC_Payment_Gateways->get_available_payment_gateways() #4 /home/customer/www/website.com/public_html/wp-content/plugins/woocommerce-point-of-sale/includes/class in /home/customer/www/website.com/public_html/wp-content/plugins/woocommerce-gateway-paypal-express-checkout/includes/class-wc-gateway-ppec-checkout-handler.php on line 578
While PHP debugging is outside of the scope of this article, in this case there’s some strong suspicions based on the logs. We can see that there are reference to two other plugins, WooCommerce Gateway PayPal Express Checkout (woocommerce-gateway-paypal-express-checkout) and WooCommerce Point of Sale. The PayPal Express Checkout plugin was far behind on its updates. Looking at the homepage for the plugin and the documentation it’s clear this is likely the culprit as it said essentially that the plugin was being deprecated in favor of a newer system for PayPal. Updates to the plugin stopped as of 1 Sept 2021. So before doing anything else, we deactivated those suspicious plugins. To test this, we manually creating a new renewal order, then manually triggered it. This went through smoothly.
This reminds us one of the inherent trade-offs about WordPress plug-ins. It’s easy to add new functionality to your website through third-parties, but this also creates more points of potential failure. Keeping your tech stack svelt can lower your maintenance overhead. At Fountain City we have lots of automated and manual checks to make sure our clients don’t unnecessarily suffer this type of problem.
So now that we know why the past schedule actions failed to execute, is there anyway to try to manually capture payments for those missed renewal orders? YES!
How to make up for those failed orders
If it’s not too far past when your customers expect to have their payments go through, we can create “catch up renewal orders”.
- Go to the edit subscription page for the specific subscription. In the screenshot below, you can see that though this is supposed to be a monthly subscription, there wasn’t a renewal created for Feb 8th as we’d expect.
- Clicking on the “next payment” brings up a date picker. I like to change this to be a specific timestamp like 12:34 or 00:07 that gives future shop managers and developers a hint that this was manually manipulated.
- Click the update button after modifying the next payment date, and it should create a scheduled action to create the next renewal order
- Go back to the Scheduled Actions page
- Search for any actions that are related to the specific subscription by entering in the subscription ID number in the search bar. At this point you’ll probably see some of the past successful actions, with one renewal still “Pending.”
- When you hover over the name of it, such as “woocommerce_scheduled_subscription_payment” there should be a link for “run”. Click that, and let the system do its processing. Then go back to the edit subscription page to confirm that an order was created, and then payment was immediately taken.
- I like to have the Stripe dashboard open at the same time as separate window or screen in order to double check the actions and confirm that the payment went through as expected.
- If you navigate back to the Scheduled Actions pending filter, and search for the subscription #, the upcoming renewal (with manually created time stamp) should still exist. Note: depending on the hook, manually running an action doesn’t automatically change it’s status to “complete” from “pending”.
If the payment fails for some reason with the automatic payment type attached, like a Stripe token, there’s still another way to get this paid. If the customer has their credit card information saved into their account, you can impersonate the user via the “user switching” plug-in, and then when logged in as them, open up the pending payment order, click on “pay now”, and then complete the process.
Due to the hyper flexible nature of the open-source WordPress ecosystem, encountering errors because of conflicting or outdated code is something must site owners run into some point. It doesn’t mean you need to reach out immediately to your customers about these errors. Customers expect their service providers to work out details on their own. With a little manual effort, we can get these subscriptions back on track.
For more background, we recommend reading the official Subscriptions Store Manager Guide. These instruction manuals are more useful than for a lot of software as Skyverge (the developers) have been supporting this software for a long time, and update the documentation frequently to respond to frequent concerns and questions that come in over customer support. Additionally, learning about the nuances of the Subscription Renewal Process can also be helpful.