What’s New in Subscriptions 2.5

This new version includes two main features, various enhancements, and other fixes and updates. Version 2.5 is a “minor” release and should be backwards compatible with sites running WooCommerce Subscriptions 2.0 and above.

In order to ensure a smooth update process, please refer to the Subscriptions Upgrade Guide.

New features

Sign up for free trial and synced products without payment details

When customers have signed up to subscription products in the past, they have been required to select a payment method and enter their credit card details, even if no initial payment is required. This was to ensure that future payments could be processed automatically. One of our most highly requested features on the ideas board has been to allow customers to bypass this step and in 2.5, this is now possible.

Store managers can enable this feature by changing a new setting. Enabling this feature will allow customers to check out without the need to enter their payment details when signing up to subscriptions that don’t need an initial payment.

Conditions for a $0 initial checkout include:

• Products with a free trial
• Non-prorated synced products
• Orders where the first payment has been discounted by 100%

To enable this feature:

1. Go to the WooCommerce > Settings > Subscriptions screen.
2. Scroll down to the Miscellaneous section.
3. Check the option to Allow $0 initial checkout without a payment method.
4. Save.

Add payment method

For customers who have signed up for subscriptions without entering their payment details, or for customers who have had a subscription created for them manually, adding an automatic payment method to their subscription is an important step.

With 2.5, customers will be able to add a payment method in a similar way to how they have changed their subscription payment methods in the past.

For the Add Payment button to appear the following criteria must be met:

1. The subscription must be manual renewal. Manual renewal subscriptions include those which:
   • don’t have a payment method
   • were purchased with a manual payment gateway like Cheque, or
   • have been set to require manual renewal in the case where the store has turned off automatic payments
2. The subscription must have a recurring amount and therefore require payment.
3. The subscription must be active and have a next payment date.
4. The store must have at least one payment method that can support payment method changes.

As part of this new feature, store managers can now also generate a link directly from the WooCommerce > Subscriptions > Edit Subscription screen that can be used by customers to add or change a subscription’s payment method. To get this link:

1. Go to WooCommerce > Subscriptions.
2. Click on the subscription you want to get the link for.
3. The link will be displayed at the bottom of the billing details section.

Auto-renew toggle

For stores that accept both manual and automatic payments, the payment method the customer uses to sign up for their subscription determines if a subscription is renewed manually or automatically. In 2.5 there is a new option that will allow your customers to switch between automatic and manual renewals whenever they choose.

This feature will be off by default. To enable it:

1. Go to the WooCommerce > Settings > Subscriptions screen.
2. Scroll down to the Renewals section.
3. Check the option to Display the auto renewal toggle.
4. Save.

Enabling this feature will display an auto-renew toggle on the customer’s View Subscription page. Clicking this will switch their subscription between manual and automatic renewals.

If the customer chooses to turn on automatic payments and the subscription doesn’t have an automatic payment method set, the customer will be asked to add one by following the Add Payment method flow. This process is similar to the existing change payment method process.

Enhancements

Update all subscription payment methods

In 2.5, when a customer adds or changes a subscription’s payment method, they will be given the option to update all their subscriptions to use this new payment method. This will be useful for customers who have multiple subscriptions with your store.

For this checkbox to appear the customer will need to:

• Have more than one subscription.
• Select a payment method which supports this feature. Payment gateways that support admin payment method changes and update the payment method immediately on the change payment page will work out of the box. Payment gateways can also declare direct support for this feature. More on this in the developer section below.

Improved payment method display

It’s important for your customers to know what payment method will be used to process upcoming renewal orders for their subscriptions. In 2.5, we’ve moved the subscription’s payment method details out of the subscription totals table and up into the subscription details table.

We’ve also tried to make sure that customers have as much information as possible. Depending on the payment gateway, the customer will see more details about which card will be charged.

Reactivate pending-cancellation subscriptions

Sometimes store managers and customers can accidentally cancel a subscription. In 2.5 customers and store managers will be able to reactivate subscriptions that have the Pending-Cancellation status.

A cancelled subscription can only be reactivated if it:

• has a pending-cancellation status,
• is manual renewal, or
• has a payment gateway that:
  • isn’t gateway scheduled (for example, PayPal Standard is gateway scheduled),
  • supports payment date changes, and
  • supports subscription reactivation

Store managers can reactivate pending-cancelled subscriptions by:

1. Going to the WooCommerce > Subscriptions administration page.
2. Find the subscription with a Pending-Cancellation status you would like to reactivate.
3. Hover over the subscription status.
4. Click Uncancel.

Customers can reactivate pending-cancelled subscriptions by:

1. Going to their My Account > Subscriptions page.
2. Find the subscription with a Pending-Cancellation status they would like to reactivate.
3. Click View
4. Click Reactivate

Filter subscriptions by manual renewal

On top of filtering subscriptions in the WooCommerce > Subscriptions administration table by specific payment gateways or no payment gateway, you can now filter subscriptions which are manual renewal.

To filter by manual subscriptions:

1. Go to WooCommerce > Subscriptions.
2. From the payment method filter drop-down, select Manual Renewal.
3. Click Filter.

Payment gateway feature support tooltip

To make it easier to see what features your payment gateways support we’ve added a tooltip in the WooCommerce > Settings > Payments table. By hovering over this tooltip — marked with a ? — you will see a list of features each payment gateway supports.

New information added to the dashboard status widget

In 2.5 we’ve added some new Subscriptions-related stats to the WooCommerce Status widget to help you get a quick overview of how your store is running. The new stats we’ve added include the total number of signups, renewals and cancellations for the current month. As well as the signup and renewal revenue for the current month.

To view the status widget:

1. Go to the Dashboard tab on your WordPress dashboard.
2. Scroll down to the WooCommerce status widget.

Other changes

PayPal Standard for subscriptions

In 2.5 you will now be able to disallow PayPal Standard for subscription purchases. If you have subscriptions already using PayPal Standard, it is safe to disable this setting. Processing renewals and other events for existing PayPal Standard subscriptions will continue as normal.

When this setting is disabled, PayPal Standard won’t appear as an option on the checkout when:

• Adding or changing a subscription’s payment method
• Signing up to a new subscription
• Paying for manual or failed renewal or initial payment orders
• Resubscribing

To ensure continued support without any interruption, this setting will be automatically enabled for stores that had PayPal Standard enabled prior to 2.5.

If you’re setting up a new store or if you had disabled PayPal Standard prior to upgrading to 2.5, PayPal Standard for Subscriptions will automatically be disabled.

PayPal Standard has many limitations and due to its nature, can lead to complications with keeping your store in sync with PayPal. Because of this, it is not recommended as a payment method for Subscriptions unless it is the only available option for your country.

If you’re looking for a payment method to replace PayPal Standard, please see WooCommerce’s guide on Which Payment Option is Right for Me?

To disable PayPal for Subscriptions:

1. Go to WooCommerce > Settings > Payments.
2. Click PayPal.
3. Under the Enable/Disable heading, uncheck the Enable PayPal Standard for Subscriptions option.
4. Save.

PayPal Standard and $0.01 transactions

In 2.5, Subscriptions will now ignore all PayPal IPNs which are for $0.01. Prior to 2.5, Subscriptions would ignore $0.01 IPNs if the subscription had exactly one completed payment. You can read more about $0.01 IPNs here.

Changes to the customer’s view subscription page (downloads)

On the customer’s View Subscription page, we’ve improved the way downloads are displayed so they appear all in one table.

For developers and store builders

Subscription order key changes

In WooCommerce 3.5.4, WooCommerce changed the way order keys are generated in order to make them more unique. In 2.5, Subscriptions will follow and use the same method WooCommerce uses to generate subscription order keys.

WC_Subscription::get_change_payment_method_url()

This new function can be used to generate an add or change subscription payment method URL. This will be useful if you’re creating an onboarding flow and want to include this link in an email sent to customers.

Payment gateway support for the new Update all Subscription Payment Methods feature

While working on the Update all Subscription Payment Methods feature, we recognized there are two types of payment gateways that will need to support this new feature. These two types of gateways include:

• Payment gateways that process the change payment request directly on the change payment page.
• Payment gateways that update the payment method sometime after the customer has clicked the Change Payment Method button.

A payment gateway can be identified as either one of these using the existing woocommerce_subscriptions_update_payment_via_pay_shortcode filter. Payment gateways that return true to this filter (the default), update the payment method directly on the change payment method page, immediately. Whereas, payment gateways that return false to this filter update the payment method sometime after the change payment request has been completed. PayPal Reference Transactions is an example of the latter type of payment gateway as it will send customers to PayPal and then needs PayPal to respond with a new Billing Agreement before it can update the subscription’s payment method.

This section will explain how the Update all Subscription Payment Methods feature, will work for both types of payment gateways.

Out of the box support using existing payment gateway features

Your payment gateway will automatically support the Update all Subscription Payment Methods feature if it:

• Supports the subscription_payment_method_change_admin feature and
• Returns true to the woocommerce_subscriptions_update_payment_via_pay_shortcode filter. Note: the default value for this filter is true.

These two features give Subscriptions access to how the payment gateway stores payment meta, and tells Subscriptions that the payment gateway updates the payment method immediately on the change payment page.

When processing the Update all Subscriptions request for these payment gateways Subscriptions will:

1. Update the subscription’s payment method, as has been done in the past.
2. After the subscription’s payment method is updated, Subscriptions will get a copy of payment meta on the subscription using the subscription_payment_method_change_admin filter.
3. Subscriptions then applies this updated payment meta to all the customer’s other subscriptions.

Support via a new subscription_payment_method_delayed_change payment gateway feature

If your payment gateway returns false to the woocommerce_subscriptions_update_payment_via_pay_shortcode filter, and therefore updates the payment method sometime after the customer has clicked the Change Payment Method button, your payment gateway won’t support this feature out of the box. To support this feature your payment gateway will need to declare that it supports subscription_payment_method_delayed_change.

You can register support for this new feature using the WC_Payment_Gateway::supports() API. This can be done by setting the supports property of your gateway to an array containing subscription_payment_method_delayed_change. For more information about this, see our Subscriptions Payment Gateway Integration Guide.

For payment gateways that declare support for this new feature, your plugin will be required to handle the request to update all the customer’s subscriptions once it has updated the subscription’s payment meta.

When processing the Update all Subscriptions request for payment gateways that return false to woocommerce_subscriptions_update_payment_via_pay_shortcode but do support the subscription_payment_method_delayed_change feature, Subscriptions will:

1. Set _delayed_update_payment_method_all meta on the subscription which is being changed by the customer.
2. Once the payment gateway which supports delayed changes has handled the request and updated this subscription’s payment method, the payment gateway should update all the other customer’s subscriptions to use this new method.

To achieve this there are a few new helper functions.

WC_Subscriptions_Change_Payment_Gateway::will_subscription_update_all_payment_methods()
This function accepts one parameter, a WC_Subscription object, and will return true if _delayed_update_payment_method_all meta is set on the subscription and therefore has been flagged as requiring an update to all the other customer’s subscriptions.

Once your plugin has changed a subscription’s payment method, you can use this function to check if further action is needed.

WC_Subscriptions_Change_Payment_Gateway::update_all_payment_methods_from_subscription()
This function accepts 2 parameters, a WC_Subscription object and the payment method ID.

If your payment gateway supports the subscription_payment_method_change_admin filter you can use this function to copy payment meta from one subscription to all the customer’s other subscriptions. If your payment gateway doesn’t support the subscription_payment_method_change_admin filter, you will need to update the payment meta on all the customer’s subscriptions manually.

To see an example of how to use this new subscription_payment_method_delayed_change feature, please take a look at how we have implemented it for PayPal Reference Transactions.

Template changes

templates/admin/html-failed-scheduled-action-notice.php
templates/checkout/form-change-payment-method.php
templates/myaccount/my-subscriptions.php
templates/myaccount/related-orders.php
templates/myaccount/subscription-details.php
templates/myaccount/subscription-totals.php

Deprecated functions, classes, actions and filters

Functions

WCS_My_Account_Payment_Methods::get_subscriptions_by_token()
WCS_My_Account_Payment_Methods::get_customer_tokens()
WCS_My_Account_Payment_Methods::get_customers_alternative_token()
WCS_My_Account_Payment_Methods::customer_has_alternative_token()
WC_Subscriptions_Upgrader::maybe_update_subscription_post_author()
wcs_display_item_downloads()
WC_Subscriptions_Cart::pre_get_refreshed_fragments()

Classes

WCS_Upgrade_Subscription_Post_Author

Actions and filters

Woocommerce_subscriptions_by_payment_token

For a complete list of the changes coming in 2.5, see the changelog.