WooCommerce Subscriptions version 2.1 has been in development for more than a year. This major new version introduced two big features as well as many smaller features and improvements. This guide covers everything that is new and improved in WooCommerce Subscriptions version 2.1.
If you are a store manager looking for instructions to help ensure you have a smooth upgrade to version 2.1, please refer to the Subscriptions Upgrade Guide.
Required WooCommerce Version
The first major change being introduced with Subscriptions 2.1 is the WooCommerce dependency. Subscriptions 2.1 requires WooCommerce 2.4 or newer.
If your site is not running WooCommerce 2.4 or newer, please update WooCommerce before updating Subscriptions.
Subscription Reports
How many customers stay subscribed to your store for more than 6 months? What is the average lifetime value of your subscribers? How much renewal revenue will your store earn next year?
These are important questions for any subscription commerce business. Prior to Subscriptions 2.1, they were not easy to answer. Subscriptions 2.1 introduces new reports to answer these questions, and many more. The reports cover:
- Subscription events and revenue, like sign-ups, cancellations and upgrades and downgrades.
- Upcoming recurring revenue, to help forecast the revenue you can expect from existing subscriptions.
- Retention rate, to find any churn hotspots and increase the length of time customers remain subscribed with your store.
- Subscription product popularity and lifetime value, to help you find your best performing products.
- Subscription data by customer, including subscription count, subscription orders and lifetime value.
Learn more in the Guide to Subscription Reports.
Failed Recurring Payment Retry System
Failed recurring payments can now be retried automatically. This helps recover revenue that would otherwise be lost due to payments that are declined only temporarily.
By default, Subscriptions will retry a failed payment 5 times over 7 days. It will also periodically email the customer to let them know their payment has failed, that payment will be automatically retried, and that they can login to complete payment.
But the rules that control the retry process can also be customized to change:
- the total number of retry attempts
- how long to wait between retry attempts
- emails sent to the customer and store manager
- the status applied to the renewal order and subscription
The retry system is disabled by default. To enable it, visit the Subscriptions settings administration screen.
Learn more in the Store Manager Guide to Failed Recurring Payment Retry System and Developer Guide to Failed Recurring Payment Retry System.
Manual Payment Retry
In addition to the automatic retry system, Subscriptions 2.1 introduces a new action to manually retry a failed payment from the Edit Order screen.
To use this action:
- Go to WooCommerce > Edit Order for an order with the failed status
- Click Actions
- Click the Retry Renewal Payment action
- Click Save Order
This will attempt to process the order’s payment again with the payment gateway.
New Subscription Emails
Subscriptions 2.1 also introduces a number of new emails to notify store owners when:
- a customer suspends a subscription
- an automatic payment fails and will be automatically retried
- a subscription expires
These emails can be enabled, disabled and customized under the WooCommerce > Settings > Emails administration screen.
Learn more in the Subscription Emails section of the Subscriptions Store Manager Guide.
New Cancellation Date
In prior versions of Subscriptions, the end date of a subscription was recorded on the subscription. But if the subscription was cancelled, either by the customer or store owner, this date would be different to the end date, and was not recorded.
Subscriptions 2.1 now keeps a record of the cancellation date. This date is used for Subscription reports, especially the Retention Rate and Events by Date report. It is also displayed on the WooCommerce > Edit Subscription screen.
For existing subscriptions, the cancellation date will also be set when you upgrade your store to Subscriptions 2.1. For subscriptions with the cancelled or pending cancellation status, it will be set to the date the subscription was last modified.
Small Enhancements
Additional Order Type Filters
The order type filter on the WooCommerce > Orders screen is a handy way to show specific order types. Unfortunately it didn’t include switch, parent or resubscribe order types as options. The Original order concept it did offer was also lacking as it mixed in parent, resubscribe and non-subscription order types.
Subscriptions 2.1 addresses this by introducing the following new filter options:
- Parent: to show only orders in which subscription products were purchased, creating new subscriptions.
- Resubscribe: to show only orders to renew an expired or cancelled subscription.
- Switch: to show only orders placed to upgrade or downgrade subscriptions.
- Non-subscription: to show only orders that are not related to a subscription at all. This is orders for non-subscription products and includes orders that are not subscription parent, renewal, resubscribe or switch orders.
To use the new order types filter:
- Go to the WooCommerce > Orders screen
- Click the All order types select box
- Change to the desired subscription or non-subscription order type
- Click Filter
Resubscribe to Subscriptions Pending Cancellation
In Subscriptions 2.0, it was not possible to resubscribe to a subscription with the pending cancellation status. Instead, the customer needed to wait until the end of the prepaid term before being able to resubscribe.
Subscriptions 2.1 makes it possible for your customers to resubscribe to subscriptions pending cancellation. The existing subscription will immediately be transitioned to the cancelled status. The first payment date for the new subscription will be set to the end of the prepaid term date on the old subscription to account for the prepaid time.
Edit Product Interface Improvements
The responsiveness and grid layout of the subscription pricing fields on the WooCommerce > Edit Product screen have been updated to match other WooCommerce fields.
The subscription length field has also been moved to its own line to reduce confusion between the product length and billing interval.
Renewal Orders Always Used for Renewal Data
One of the big changes introduced with Subscriptions 2.0 was the creation of renewal orders before renewal payment. However, when this change was introduced, not all renewal features were updated to take advantage of the renewal order being available, and instead, they continued to use the data from the subscription.
Subscriptions 2.1 now uses renewal order data as the source for:
- the order items, totals and other data used when manually renewing a subscription via the cart; and
- the amount passed to payment gateways as the amount to charge for automatic renewal payments.
This change makes it easier for 3rd party code to add one time fees or discounts to specific renewal payments. It also paves the way for such a feature to be added to Subscriptions itself.
Process Upgrades and Downgrades on Order Status Change
In previous versions of Subscriptions, when a customer switched a subscription, the switch would be processed when they completed checkout. This could cause issues with PayPal and other payment gateways where payment happens after checkout, and may not be completed.
Subscriptions 2.1 addresses this by processing switches when the status of the switch order is transitioned to processing or completed (or a custom payment complete order status).
Use Renewal Order or Subscription Address on Checkout
In prior versions of Subscriptions, when the customer paid for a manual renewal order, subscription upgrade/downgrade or resubscribe, the customer’s default billing and shipping address would be loaded into the checkout address fields. This could cause issues if the customer had multiple addresses on their account for different subscriptions.
For example, a customer may gift a subscription that ships to a family member and also have one that ships to their own home. The default address on their account is their home address. When they manually pay for the renewal of the gifting subscription, if they did not change the shipping address, after checkout, the renewal order’s address would be changed to their home address instead of the gift recipient’s address.
Subscriptions 2.1 changes this and loads the renewal order or subscription addresses as the default addresses on checkout when paying for a subscription renewal, resubscribe or switch.
Performance Improvements
Subscriptions 2.0 made a large amount of code obsolete. To avoid breaking compatibility with 3rd party code, it continued to call some of that obsolete code.
Now that it has been more than a year since Subscriptions 2.0 was released, this code is no longer being called by default. This will help your store run faster.
Subscriptions is also now caching some expensive queries and other redundant operations to help speed up the Subscriptions administration page and subscription product pages for limited products.
Notes for Developers
WP REST API Endpoints
WooCommerce 2.6 added support for REST API endpoints built on the REST API infrastructure in WordPress core.
Subscriptions 2.1 adds support for subscription data to this infrastructure.
Your applications can now create, read, update or delete subscriptions via RESTful API endpoints with the same design as the latest version of WooCommerce’s REST API endpoints.
Want to list all the subscriptions on a site?
Get /wp-json/wc/v1/subscriptions.
Want the details of a specific subscription?
Get /wp-json/wc/v1/subscriptions/<id>/.
Learn more in the Subscriptions REST API documentation.
Deprecated Hooks are No Longer Called
Subscriptions 2.0 deprecated a large number of hooks for 3rd party code. It continued to call these hooks to avoid breaking compatibility. Now that it has been more than a year since these hooks were deprecated, they are no longer being called by default.
For more information, including a list of all hooks that were deprecated in version 2.0, see the guide on deprecated hooks.
If you need to continue to call deprecated hooks, install the WooCommerce Subscriptions Load Deprecation Handlers plugin.
Deprecated Functions Removed
All functions which were deprecated prior to Subscriptions 2.0 have now been removed completely from the codebase as the functions have been deprecated for over 2 years.
Add-to-cart Validation Applied to Renewal & Resubscribe Process
WooCommerce’s 'woocommerce_add_to_cart_validation' filter is now applied when a customer renews or resubscribes to a subscription via the cart. This helps improve compatibility with 3rd party code that has special validation on products that should not be renewed.
'pay_for_order' Capability Usage
In previous versions of subscriptions, to determine whether the logged in user could pay for a renewal or resubscribe, the user’s ID was checked against the customer ID on the subscription or order directly. Subscriptions 2.1 changes this to use the 'pay_for_order' in the background, which falls back to the same checked but makes it possible for 3rd party code to customise whether a user should be able to pay for a specific order.