3.0 is a “major” release and is not backwards compatible with previous versions of WooCommerce Subscriptions. With this in mind, please employ best upgrade practices to ensure a smooth update process. Please refer to the Subscriptions Upgrade Guide for more details.

Key Points

1. Subscriptions 3.0 includes an update to the Action Scheduler library.
2. Action Scheduler 3.0 contains a data migration and as such isn’t compatible with previous versions. Once the data migration has started, rolling back will lead to data loss.
3. Action Scheduler is a library packaged with other extensions as well, including but not limited to WooCommerce core and WooCommerce Memberships. Because of the way this library loads, only 1 instance of it is loaded and that version is the latest one. This means by upgrading to WC Subscriptions 3.0 which contains Action Scheduler 3.0, all other plugins will also start using Action Scheduler 3.0 too.
4. By upgrading to Action Scheduler 3.0 you can expect to see performance improvements to the processing rate of scheduled payments and other events.
5. There are no other major features included in this version of Subscriptions.

Upgrade Process

Because this is a major version with data migration, we recommend: 

1. Taking a backup of your site before updating to Subscriptions 3.0.
2. Test the update on a staging copy of the live site.

Once you update to Subscriptions 3.0, if your site meets the migration requirements, the data migration will start automatically and will run in the background. While the data migration is happening, you can continue to use your site as normal.

Update Process for Sites Running the Action Scheduler Custom Tables Plugin

If your site has been using the Action Scheduler Custom Tables plugin to boost performance in advance of WooCommerce Subscriptions / Action Scheduler 3.0, you should disable this plugin immediately after updating to WooCommerce Subscriptions 3.0. 

The same code used in that plugin has now been merged with Action Scheduler 3.0, which is included in Subscriptions 3.0.

Migration via WP CLI

After upgrading to Subscriptions 3.0, the action scheduler migration will happen automatically in the background. However, it is possible, if you prefer, to run these upgrades via the CLI.

To migrate the action scheduler data via CLI, use the following command:

wp action-scheduler migrate

Once the migration starts, you will be given periodic updates about the process.

This command will continue running until all scheduled actions have been migrated. 

Once the migration is complete you will see the following output:

Success: Migration complete. x actions processed.

Depending on the number of actions which need to be migrated, this may take some time.

Enhancements

Increased Processing Rate for Scheduled Payments

WooCommerce Subscriptions 3.0 will process queues of scheduled payments significantly faster than previous versions. Scheduled payments are processed in a batch that can run for up to 20 seconds. In versions of Subscriptions prior to 3.0, after that time limit was reached, processing would cease until another WP Cron request.

With WooCommerce Subscriptions 3.0, whenever one request approaches the time limit for processing payments, a new request is initiated to start processing the next set of batches. This process repeats until there are no more payments to process, or no loopback requests can be made.

This significantly increases the throughput of payment processing.

For example, consider a site with 1,000 scheduled payments due where it takes 1 second to process each payment and WP Cron is run every minute on this site. With WooCommerce Subscriptions 3.0, these payments will be processed in approximately 17 minutes. With Subscriptions prior to 3.0, it would have taken approximately 50 minutes to process the same number of payments on the site.

Scheduled Payments Now Run on All Admin Requests, not just WP Cron

Prior to WooCommerce Subscriptions 3.0, scheduled recurring payments would be initiated by WP Cron. With WooCommerce Subscriptions 3.0, whenever a store manager visits the administration dashboard, WooCommerce Subscriptions will check if the site has pending scheduled payments and begin to process them.

This helps ensure payments are processed, even if there is a problem with the WP Cron system.

Scheduled Event Data Migrated to Custom Tables from Custom Post Type

WooCommerce Subscriptions 3.0 moves all scheduled job data to custom tables. Previously, this data was stored alongside product, order, subscription, post, and page data in your WordPress database.

Storing data in the same location as these other objects meant that both Action Scheduler database performance was slower, and performance across all other data was slower. With WooCommerce Subscriptions 3.0, the database performance is improved across all areas where post data is queried.

Other Changes

Admin Subscription and Order Status Visual Updates

Subscriptions 3.0 includes an update to the way subscription and order statuses are displayed on subscription-related admin screens. This is to bring them in line with the way WooCommerce displays these statuses.

FAQ

What are the requirements for using Action Scheduler 3.0?

In order to migrate the action scheduler data to custom tables your site must meet the following requirements:

1. Be running PHP 5.5 or higher. 
2. Have no scheduled actions with a combined arguments length greater than 191 characters.

If either of these conditions isn’t met, your site will remain using the WordPress posts data structures and tables to store Action Scheduler data. 

This means you can still upgrade to Subscriptions 3.0 and your site will continue to function as it has, however, the data migration won’t occur and so you won’t see the performance improvements that come with this release.

Should I update now or wait?

As with any major update, we suggest that you:

1. Take a backup of your site before upgrading.
2. Test the update on a staging site before updating the live site.
3. Once everything looks good on the staging site then update the live site. 

For more details about how we recommend updating Subscriptions, take a look at our Subscriptions Upgrade Guide.

Following these steps is the only way to be sure Subscriptions 3.0 is safe to run on your site.

Whether you should update now or wait is something only you as the store owner can answer. To help answer this question you should keep in mind a couple of things:

1. Have you tested the update on a staging copy of the live site?
2. How vigorously have you tested the normal functions of your site while it is running 3.0? You can do this on your staging site first.
3. What is the current or upcoming site traffic likely to be? Do you have an upcoming sale for example? Do you have thousands of renewals all scheduled to run in a couple of days? If so, it might be better to wait until after that period before upgrading.
4. How confident are you that if things did go wrong, you would be able to roll back the database and plugin to a previously saved version.

None of my renewals have processing on time. What’s happening?

The first thing to check is if you have upgraded to Subscriptions 3.0. To check which version of Subscriptions you have active:

1. Go to the Plugins from your WordPress admin dashboard.
2. Find WooCommerce Subscriptions
3. Under the plugin description is the version number.

If you do have WooCommerce Subscriptions 3.0 or above active, we’ll need to investigate why the scheduled actions are missing or aren’t running on time. To get in contact with us, please open a ticket.

All my scheduled actions haven’t migrated yet, will my site still run as normal?

Yes, while the data migration is in progress, Subscriptions will continue to process scheduled actions in both the post tables and custom tables. 

How long will the migration take?

How long it will take to migrate all your scheduled action data will depend on your store’s specific circumstances: 

1. How many actions need to be migrated.
2. How many actions your site can migrate at a time. This will depend on your server environment.

If you’re familiar with WP CLI you can run the data migration via a WP CLI command. This is the quickest way to complete the migration.

See our section on migrating the action scheduler data via WP CLI.

What performance improvements can I expect to see from this update?

The performance improvements you will see will be unique to your site and is dependent on the number of scheduled actions your site typically has to process in short periods of time. 

For example, if you have 10-20 renewals occur on one given day over the space of a number of hours, you will likely see some negligible performance improvements. These improvements will come in the form of quicker database queries for orders, subscriptions and other data stored in the posts tables.

If however you have all your subscriptions synced to run on 1 day (for example the 1st of each month) and you have 1000+ renewals. You will see much larger improvements in the time it takes to process those payments and the general improvements to post queries on your site.

Where almost all users will see an improvement is in data migration and generation in plugins that use scheduled actions to run these events in the background. For example, WooCommerce Subscriptions, in past plugin updates, has used scheduled actions to fix corrupted data or generate new data for existing customers orders and subscriptions. This process usually loops over every item (order, subscription, or customer) and processes it individually. Because these data repair or migration scripts use Action Scheduler to run a lot of events over a short period of time, the speed at which they complete for sites of all sizes will be improved by this update.

In some internal tests comparing Action Scheduler 3.0 with 2.5.5 we saw a:

• ~69% reduction in the amount of database storage required. 
• ~68% reduction to the time it takes to create and store scheduled actions. 
•  60-72% reduction in the time it took to receive 50 scheduled action results used populate the admin table sorted by field. 

These were the results on a site populating WooCommerce Admin data with: 

• 7500 customers
• 5000 products
• 50,000 orders

My site just updated to WC Subscriptions 3.0. Can I roll back to 2.x.x?

No. Because Subscriptions 3.0 includes data migration, rolling back to an earlier version will result in lost data.

Earlier versions of Subscriptions cannot interact with the migrated data, only 3.0 and above can.

If your site is not responding or not functional after upgrading to Subscriptions 3.0 you can attempt to roll back the database and plugins if it’s safe to do so, otherwise please contact support so we can investigate further.

I use WooCommerce Memberships which also uses Action Scheduler. Will Memberships still work after this upgrade?

Yes, WooCommerce Memberships will continue to work as normal after upgrading to Subscriptions 3.0. Memberships interacts with the Action Scheduler library in a way that won’t be affected by this upgrade. In fact, Membership related scheduled action events will also benefit from the performance improvements included in this release.

I use a plugin which uses Action Scheduler. Will this plugin still work after this upgrade?

Most likely yes, however it depends on how the plugin is interacting with Action Scheduler data. If the plugin is using Action Scheduler APIs they will continue to work as normal. If, however, the plugin is interacting with the database directly or using some of the schedule types which previously didn’t work as described, they may run into issues.

If you are unsure, please reach out to the developer of the plugin using Action Scheduler to ask whether their plugin is compatible with Action Scheduler 3.0.

The post What’s New in Subscriptions 3.0 first appeared on CODIBU.

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

New Features

Improved early renewal user experience

Customers who choose to renew their subscriptions early have in the past been required to go through the checkout flow. This meant the customer had to complete the checkout form, select a payment method, and process the payment.

For customers who have an automatic payment method already set on their subscription, this process can theoretically be skipped entirely. 

With Subscriptions 2.6, there is a new option in WooCommerce > Settings > Subscriptions which will allow customers to bypass the checkout and streamline this process. If enabled, customers who click the Renew now button will be displayed a modal. A modal is a window which appears over the top of the main page content. The early renewal modal includes information about the subscription line items, the amount they will be charged, the payment method which will be used, and what will be the new next payment date.

By using the modal, customers can renew early without leaving their view subscription page, with 2 clicks, and with no page loads.

Requirements

For customers to be displayed the early renewal modal the following requirements must be met: 

• The early renewal modal needs to be enabled via the admin settings. Upon upgrading to 2.6 this will be disabled by default. See steps below to enable this feature.
• The subscription must have an automatic payment method.
• The subscription must be eligible for early renewals.

To enable the early renewal via modal setting: 

1. Go to WooCommerce > Settings > Subscriptions
2. Scroll down to the Renewals section. 
3. Under Early Renewal enable: 
   1. Accept Early Renewal Payments, and 
   2. Accept Early Renewal Payments via a Modal

View which subscriptions and orders contribute to report figures

When viewing subscription reports with 2.6, you will be able to see which subscriptions and orders are contributing to a particular figure. 

By clicking one of the report data points with a you will be redirected to the admin order or subscription table with the list of subscriptions or orders which contribute to the reported figure listed. 

For example, to find the subscriptions which were cancelled in the last 7 days:

1. Go to WooCommerce > Reports > Subscriptions tab.
2. Select Last 7 Days from the date selection options.
3. On the left-hand side of the report, click the ‘subscription cancellations’ link.
4. You will be redirected to the list of subscriptions which have been cancelled in the last 7 days. 

The reports which support contribution views are: 

1. New Subscriptions – the number of subscriptions created during the selected report period. This includes subscriptions created manually, imported or created by a customer placing an order. This includes subscriptions with orders pending payment.
2. Subscription Signups – the number of subscriptions purchased in parent orders created during the selected report period. This represents the new subscriptions created by customers placing an order via checkout.
3. Subscription Resubscribes – The number of resubscribe orders processed during the report period.
4. Subscription Renewals – the number of renewal orders processed during the selected report period.
5. Subscription Switches – the number of subscriptions upgraded, downgraded, or cross-graded during the selected report period.
6. Subscription Cancellations – the number of subscriptions cancelled by the customer or store manager during the selected report period. 
7. Ended Subscriptions – the number of subscriptions in the selected report period which have either expired or reached the end of the prepaid term if it was previously cancelled.
8. Current Subscriptions – the number of subscriptions during the selected report period with an end date in the future and a status other than pending.

Enhancements

Improved switching calculations

WooCommerce Subscriptions 2.6 includes a complete rewrite of the code which calculates the amount a customer pays in upgrade fees and the number of days the subscription is extended by when downgrading between two products.

The code prior to this rewrite was complicated and led to bugs in the calculations being difficult to fix. 

As part of this rewrite, 12 known issues and possibly more unknown bugs have been fixed. 

To assist in understanding and troubleshooting a switch upgrade cost and outcome, information about every subscription switch will now be logged to the wcs-switch-cart-items log. Each log entry will include important switch values used in the proration calculations.

To view the switched cart item log:

1. Go to WooCommerce > Status > Logs (tab)
2. From the drop-down on the right-hand side select the wcs-switch-cart-items log file
3. Click View

Improved handling of unloadable orders in the related orders table

Sometimes errors can happen and orders cannot be loaded from the database. Prior to 2.6, this scenario would lead to errors on the admin edit subscription screen as we tried to generate the related orders table. 

Because a subscription keeps an internal record of its related orders, in 2.6, if the order fails to load from the database correctly, the order will be listed in the related orders table and include a link to documentation that will help store managers find and resolve the underlying cause.

Other Changes

Switching subscription setting changes 

To enable third-party developers to include their own product types in the list of switchable products, the setting which allows store managers to turn on switching between certain product types has been converted into multiple checkboxes rather than a drop-down.

All existing store settings will be kept unchanged and how the settings work in the plugin’s code will continue to work as they have in the past.

Updates to customer-facing templates

WooCommerce core uses sentence case (capitalizing only the first word and any proper nouns) in headings in customer-facing templates. Subscriptions 2.6 includes a review of all the my account, cart, and checkout templates and updates all headings to follow WooCommerce in order to be consistent across the board. 

For Developers and Store Builders

Rest API: removed subscription line items included in the response

Line items which have been removed from the subscription by the customer from their My Account > View Subscription page, will be included in the Subscription endpoint GET response. 

On top of the line item data, you will now receive the same data for the line items which have been removed. For example:

"line_items": [
 {
     "id": 2911,
     "name": "Small Woorld Subscription",
     "sku": "",
     "product_id": 24,
     "variation_id": 0,
     "quantity": 1,
     "tax_class": "",
     "price": "30.00",
     "subtotal": "30.00",
     "subtotal_tax": "0.00",
     "total": "30.00",
     "total_tax": "0.00",
     "taxes": [],
     "meta": []
 }]
"removed_line_items": [
 {
     "id": 2917,
     "name": "Small Woorld Membership",
     "sku": "",
     "product_id": 23,
     "variation_id": 0,
     "quantity": 1,
     "tax_class": "",
     "price": "100.00",
     "subtotal": "100.00",
     "subtotal_tax": "0",
     "total": "100.00",
     "total_tax": "0",
     "taxes": [],
     "meta": []
 }]

Switching refactor

As part of the switching refactor, there are 3 new classes which are used to calculate the prorated price and subscription date updates while switching. 

WCS_Switch_Totals_Calculator – The WCS_Switch_Totals_Calculator object takes a WC_Cart object as the only parameter in its constructor. It’s main function is calculate_prorated_totals() which will calculate all the prorated totals for all the switch items in the cart. It has other functions which are used to determine what switch settings are in place on the store and functions to set values in the cart item’s data.

WCS_Switch_Cart_Item – For every item in the cart which records a switch between one subscription line item and another, a WCS_Switch_Cart_Item object will be created. This class is responsible for calculating various things about the switch. Specifically how many days into the current term is the current subscription, what’s the price per day of the new and old products, whether the switch is occuring during a trial, etc.

WCS_Add_Cart_Item – The add cart item class extends WCS_Switch_Cart_Item. It is similar to a switch cart item, however, it doesn’t have an item on the current subscription which it is planned to replace. It only contains a couple of functions which override functions which aren’t necessary when an existing subscription line item isn’t being switched. Under normal use, this object isn’t used within Subscriptions core, it exists to enable third-parties to add items to existing subscriptions, and inherit all the built-in proration calculations that switching brings. 

Repair subscription line items with missing _has_trial meta

During Subscriptions 2.6 development we discovered that subscription products with a trial period purchased on sites running WC 3.0, haven’t been storing the _has_trial meta. The impact of this missing data is fairly small as it is only used by Subscriptions to calculate a subscription line item’s sign up fee and that’s used to apportion sign up fees while switching.

Subscriptions 2.6 includes an upgrade routine which will find and update all subscription line items with this missing data.

Apply BEM classes to Subscriptions templates 

In Subscriptions 2.6 all the My Account templates have been updated to use the BEM (Block, Element, Modifier) methodology. WooCommerce has in recent versions started to move towards using the BEM methodology. BEM provides a standard whereby theme developers and third-party developers can, on a more granular level, target HTML blocks, elements, and elements within specific blocks.  

You can read more about the BEM methodology and its key concepts here.

Template Changes

templates/admin/status.php templates/cart/cart-recurring-shipping.php templates/checkout/form-change-payment-method.php templates/checkout/recurring-totals.php templates/myaccount/my-subscriptions.php templates/myaccount/related-orders.php templates/myaccount/related-subscriptions.php templates/myaccount/subscription-details.php templates/myaccount/subscription-totals.php templates/myaccount/view-subscription.php templates/single-product/add-to-cart/subscription.php templates/single-product/add-to-cart/variable-subscription.php

Emails

All subscription email templates have been updated to include the additional content added in WooCommerce 3.7.0. 

templates/emails/admin-new-renewal-order.php templates/emails/admin-new-switch-order.php templates/emails/admin-payment-retry.php templates/emails/cancelled-subscription.php templates/emails/customer-completed-renewal-order.php templates/emails/customer-completed-switch-order.php templates/emails/customer-payment-retry.php templates/emails/customer-processing-renewal-order.php templates/emails/customer-renewal-invoice.php templates/emails/email-order-details.php templates/emails/expired-subscription.php templates/emails/on-hold-subscription.php templates/emails/subscription-info.php templates/emails/plain/admin-new-renewal-order.php templates/emails/plain/admin-new-switch-order.php templates/emails/plain/admin-payment-retry.php templates/emails/plain/cancelled-subscription.php templates/emails/plain/customer-completed-renewal-order.php templates/emails/plain/customer-completed-switch-order.php templates/emails/plain/customer-payment-retry.php templates/emails/plain/customer-processing-renewal-order.php templates/emails/plain/customer-renewal-invoice.php templates/emails/plain/expired-subscription.php templates/emails/plain/on-hold-subscription.php templates/emails/plain/subscription-info.php

New templates

templates/html-early-renewal-modal-content.php templates/html-modal.php templates/myaccount/subscription-totals-table.php

Deprecated Functions, Classes, Properties, Actions and Filters

Functions

• WC_Subscriptions_Cart::check_valid_add_to_cart() – this function has moved to WC_Subscriptions_Cart_Validator::check_valid_add_to_cart()
• WC_Subscription::get_completed_payment_count()– there is now a new function, WC_Subscription::get_payment_count(), which can be used for the same purpose and new concepts too like $subscription->get_payment_count( 'refunded' ) or $subscription->get_payment_count( 'net' )
• WC_Subscriptions_Manager::process_subscription_payments_on_order() – this function was not not being used by Subscriptions core and included pre-Subscriptions 2.0 concepts.
• WC_Subscriptions_Manager::process_subscription_payment_failure_on_order() – this function was not not being used by Subscriptions core and included pre-Subscriptions 2.0 concepts.

Filters

• woocommerce_subscription_payment_completed_count – this filter was not compatible with the new function WC_Subscription::get_payment_count(), as it filtered the combined parent and renewal completed order counts. You should use woocommerce_subscription_parent_payment_completed_count and woocommerce_subscription_renewal_payment_completed_count filters to provide the individual counts.

Properties

• WCS_Action_Scheduler::$action_hooks – this property is protected and should no longer be used by any third-party extending the WCS_Action_Scheduler class. WCS_Action_Scheduler itself will now use WCS_Action_Scheduler::get_date_types_to_schedule() to schedule and unschedule events on subscription status update.

The post What’s New in Subscriptions 2.6 first appeared on CODIBU.

Data Subscriptions Uses

Subscriptions accesses and records data similar to WooCommerce. The data used by Subscriptions includes:

• Subscription ID Number
• Date Created
• Recurring Total
• Subscription Items
• IP Address
• Browser User Agent
• Billing Address
• Shipping Address
• Phone Number
• Email Address
• Payment Gateway tokens

Data retention

Inactive user data retention

With WooCommerce, it is possible to erase customers’ data after a set amount of time. This setting is under WooCommerce > Settings > Accounts & Privacy > Personal data retention. With WooCommerce Subscriptions, customers who have at least one subscription are exempt from this cleanup. This is to prevent customers who have subscriptions from having their data removed while they still have a subscription.

Ended subscription data retention

It is possible to anonymize data associated with subscriptions after a set amount of time. This applies to subscriptions that are ended, meaning that they have a status of cancelled, expired, switched, or trash.

To find this setting:

1. Go to WooCommerce > Settings > Accounts & Privacy
2. Scroll to the section labeled Personal data retention
3. The setting is called Retain ended subscriptions

Export or Erase Customer Data

The ability to export or erase customer data is built into tools in WordPress. Subscriptions supports these tools by including subscription data as a part of the data that is exported or erased.

Data export

When data is exported, the user is given a file that contains their data. Subscriptions adds each subscription the user has, and data that is connected to each subscription, to this file. Similarly, when data is erased, Subscriptions erases this data.

Example of the Subscriptions portion of a data export:

Data erasure

Data erasure setting

To remove personal data from subscriptions during a data erasure request, a setting must be enabled. To enable this setting:

1. Go to WooCommerce > Settings > Accounts & Privacy
2. Go to the section labeled Account erasure requests
3. Check the box labeled Remove personal data from subscriptions

When personal data is erased and the data removed from the corresponding subscriptions, the subscriptions will be cancelled.

Bulk erase data from subscriptions

It is also possible to erase personal data on subscriptions in bulk. The corresponding subscriptions will then be cancelled and have the personal data removed. This only removes the data from the subscriptions chosen and not the related orders.

To erase personal data on subscriptions:

1. Go to the WooCommerce > Subscriptions administration screen
2. Select the subscriptions that you wish to remove personal data from using the checkboxes
3. In the Bulk Actions dropdown, select Cancel and remove personal data
4. Click Apply

Privacy Policy Guide

In order to ensure store managers have what they need to comply with the GDPR, WordPress includes a privacy policy guide. Subscriptions adds a section to this guide to help store managers understand what information Subscriptions uses and be better able to write their own privacy policies.

To see Subscriptions’ section in the privacy policy guide:

1. Go to the WordPress administrator dashboard
2. Go to Settings > Privacy and click the link to Check out our guide
3. Scroll to the section labeled Source: WooCommerce Subscriptions

OR

1. Go to https://example.com/wp-admin/tools.php?wp-privacy-policy-guide#wp-privacy-policy-guide-woocommerce-subscriptions, replacing example.com with your site’s URL.

The post Subscriptions and the GDPR first appeared on CODIBU.

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.

The post What’s New in Subscriptions 2.5 first appeared on CODIBU.

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

Required WooCommerce Version

This version of WooCommerce Subscriptions requires WooCommerce version 2.6 or newer.

If your site is not running WooCommerce 2.6 or newer, please update WooCommerce before updating Subscriptions.

New Features

Charge full price at time of sign up for synchronized products

On the WooCommerce > Settings > Subscriptions screen, under the Synchronization heading there is an option to “Prorate First Renewal”. There is a new option in this dropdown that allows store managers to set their store to charge the full amount of the product at sign-up, no matter the date.

Create limited subscription payment coupons

When creating a coupon for recurring products, a field labeled “Active for x payments” will be displayed. The default will be blank, meaning that the coupon will be active for the duration of the subscription.

Filling in this field with a number will ensure that the coupon is only active for that number of payments, including the initial payment. Once the coupon has reached its limited number of payments, it will be automatically removed from the subscription.

For more information on limited coupons, see the Limited Subscription Payment Coupon guide.

Allow customers to renew early

On the customer’s View Subscription page, there will be a button labeled “Renew Now”. After pressing this button, customers will be taken through the checkout process to pay for their renewal immediately. Upon successfully completing the early renewal, the subscription’s next payment date will be pushed forward the appropriate amount of time.

For example, if a subscription renews monthly on the 5th and the next payment date is August 5th. On the 26th of July, if the customer decides to renew early, the next payment date will account for this renewal and be changed to September 5th.

For the renew now button to be displayed:

• the early renewal feature will need to be enabled from the WooCommerce > Settings > Subscriptions screen.
• the subscription will need to have an active status.
• the subscription will need a recurring price (excludes subscriptions which are free).
• there must be a next payment date.
• the payment gateway used to purchase the subscription must support subscription date changes.
• the subscription will need to not contain any synchronized products.
• the subscription must not currently be in a trial period, if one exists.

Link a subscription to a parent order

On the Edit Subscription screen, below the subscription status, there is now a field that lists the parent order number or an empty dropdown field.

If the field is empty, you may click on the dropdown in order to search for and choose an order to become the parent order for the subscription. While searching, only orders which belong to the subscription customer will be listed. The orders are listed by number.

A pending parent order can also be created from a subscription. An invoice for this order could then be sent to a customer, which will activate the subscription when paid.

In the “Subscription actions” box on the right side of the Edit Subscription screen, there is an option in the dropdown to “Create pending parent order.”

Performance

Subscriptions strives to meet the needs of a broad range of businesses, including those who grow to large scales. These performance changes reduce the potential for growing pains and improves Subscriptions for everyone.

A persistent cache of subscription related order IDs

When retrieving a list of related orders for a subscription, there sometimes has to be a query to the database to get these related orders. This can be slow, especially on large sites. Subscriptions 2.3 adds a persistent cache of related orders that updates without having to query the raw data to avoid this performance bottleneck.

A persistent cache of customer subscriptions

Similar to the above, running a query to find a customer’s subscriptions can be slow, especially on large-scale sites. By creating a persistent cache of a customer’s subscriptions, performance is improved for retrieving a list of customer subscriptions.

Update Action Scheduler

Action Scheduler is a library used by Subscriptions to run actions at certain times. Many updates have been made to Action Scheduler, especially to enhance performance on a large scale. Action Scheduler 2.0 will be included as part of Subscriptions 2.3

Boost performance of admin subscription search

When searching subscriptions from the admin screen, the billing and shipping addresses are included in the fields searched. Prior to WooCommerce 3.0, these fields were many and separate.

The billing and shipping addresses have since had a field added that is a combination of the other fields to allow for better search performance. WooCommerce Subscriptions 2.3 takes advantage of those fields to improve admin subscription search performance.

But wait there’s more!

• Repair subscriptions that have been suspended in PayPal but not in WooCommerce. This problem persisted from Subscriptions version 2.1.4 until version 2.2.8, when this bug was fixed. While the root issue was fixed, the already affected subscriptions would still be out of sync with PayPal. This script will align the WooCommerce subscription statuses with the PayPal statuses.
• Remove one-time fees from renewals. This especially applies in cases when fees are added by third parties.
• Improve subscription report accuracy by excluding trashed subscriptions from report calculations.
• When a recurring coupon type is applied to a cart which only contains synced subscription products or products with a free trial, hide the coupon in the initial cart since it doesn’t apply any perceivable discount.
• Only allow switching between products which are visible to the customer.
• Improved the performance of getting a variable subscription product’s min and max price data. This should reduce the time it takes to load shop product archive pages.
• We’ve added new sections to the system status including an overview of the site’s subscriptions statuses, whether the store has been connected to a WooCommerce account, whether the site has custom retry rules, and a payment gateways section.

For Developers

• Ensure pre-WooCommerce 3.0 subscriptions have billing and shipping address indexes.
• Change created_via meta on renewal orders to remove possible conflict between hold stock setting and retry system order cancellation.
• Add $cart and $order arguments to woocommerce_checkout_create_subscription filter.
• Remove TLC transients library and cache manager in favor of using WordPress transients.
• Refactor code for date columns on subscriptions table.
• Requires PHP 5.6 or newer.
• Add a filter to allow third-parties to filter orders by custom order types.
• Add filter to control automatic single subscription redirect on customer account page.
• Deprecated the wcs_pre_get_users_subscriptions filter.

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

The post What’s New in Subscriptions 2.3 first appeared on CODIBU.

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:

1. Go to WooCommerce > Edit Order for an order with the failed status
2. Click Actions
3. Click the Retry Renewal Payment action
4. 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:

1. Go to the WooCommerce > Orders screen
2. Click the All order types select box
3. Change to the desired subscription or non-subscription order type
4. 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.

The post What’s New in Subscriptions 2.1 first appeared on CODIBU.

• PayPal Standard
• PayPal Reference Transactions via Express Checkout

By default Subscriptions uses the first of these – PayPal Standard. This is the easiest to configure. You can sell subscription products with PayPal Standard straight away with a PayPal business account. You do not need any further setup to start receiving recurring payments from your customers with PayPal Standard.

If you need to be use any of Subscriptions advanced features with PayPal, including upgrades/downgrades or need to workaround some of PayPal Standard’s limitations, then you will need to apply with PayPal for Reference Transactions. These are required both when using PayPal built-in to Subscriptions, and the PayPal Checkout extension with Subscriptions.

Reference Transactions is not a standard product and approval is subject to a fully underwritten application. This can include reviewing your business model and finances to determine your suitability.

This FAQ answers common questions about getting your PayPal account approved for Reference Transactions, and how PayPal Reference Transactions work with WooCommerce Subscriptions.

How do I get Reference Transactions Enabled with PayPal?

To request that PayPal turn on Reference Transactions, call your local PayPal Support Help Center. Find the phone number at Contact.

Tell PayPal that you are specifically calling so a PayPal Specialist can enable Reference Transactions on your account. They may try to help you set up recurring payments with a button — that is not want you want. They need to transfer you to a specialist who will ask you for your PayPal account information (email address), and then tell you that they filed a ticket, and you will hear back from PayPal via email on whether Reference Transactions have been enabled or not.

Email Application

You can also contact PayPal via email.

1. Log into your PayPal account.
2. Go to the Email Contact Form.
3. Choose topic: Business solutions.
4. Choose sub-topic: PayPal payment solutions.
5. Choose sub-topic: PayPal Express Checkout.
6. Copy and paste the message below, inserting your PayPal email address and name.
7. Wait for a reply.

Example Message to send to PayPal

Hello,

Could you please enable Reference Transactions on my PayPal account (email: paypal@example.com)?

I need this feature to sell recurring subscription products via WooCommerce.

Kind regards,

Your Name

Gotcha: Respond to the Autoresponder

In an effort to reduce support, PayPal may send you a response from an auto-response message with some links to documentation.

Hidden in this auto-response is the following:

If we haven’t answered your question, please reply to this email and our team will answer you as soon as possible.

You also need to respond to the auto-response before your support ticket is submitted to PayPal.

Will My Account Qualify for Reference Transactions?

PayPal does have a set a requirements that need to be met before they enable support for Reference Transactions on your account.

Unfortunately, PayPal does not publish these requirements and based on anecdotes from customers, the requirements can be different for different businesses.

Some things that store owners have mentioned PayPal require are:

• High personal credit (FICO) score for US based PayPal Business accounts
• Business plan
• Average transaction price
• Number of repeat customers
• Number of Reference Transactions per customer
• Revenue forecast and/or projected total revenue volume from Reference Transactions
• Demonstrate a clear business rationale behind the request
• Show the signup flow for customers in regards to Reference Transactions.
• Proof that you will show clear terms and conditions for customers in regards to Reference Transactions and how to cancel once they sign up.
• Written statement as to why you need Reference Transactions and how you will use it for your business.

In terms of revenue forecasts, we have had reports that UK based PayPal accounts may require minimum forecast of £6,000 month or more revenue.

How do I Enable Reference Transactions in Subscriptions?

WooCommerce Subscriptions takes advantage of Reference Transactions when possible.

If your PayPal account does not have Reference Transactions enabled, Subscriptions automatically checks with PayPal once a week when loading the WooCommerce > Settings > Payments screen to see if support has since been enabled.

If you wish to run the check manually:

1. Go to WooCommerce > Settings > Payments > PayPal.
2. Ensure PayPal is enabled and your credentials are set.
3. Select Check PayPal Account when the Reference Transaction notice appears.

Will Existing Subscriptions use Reference Transactions?

No. Any existing subscriptions continue to be PayPal Standard subscriptions.

PayPal Reference Transactions are only used for future subscriptions. This means that advanced subscription management features, such as recurring amount changes, are only possible on newly purchased subscriptions, not existing ones.

However, enabling Reference Transactions makes it possible to upgrade or downgrade existing subscriptions.

The only way to have existing PayPal Standard subscriptions changed to use PayPal Reference Transactions is to have customers sign-up again with PayPal by changing the payment method on their subscription(s).

Why are billing agreements not cancelled at PayPal when a subscription is cancelled in WooCommerce?

When a PayPal Standard Subscription is canceled or suspended in your WooCommerce store, status of the corresponding subscription at PayPal is also changed.

However, when a subscription created using PayPal Reference Transactions is canceled or suspended in your WooCommerce store, the corresponding Billing Agreement at PayPal does not have its status changed. It remains active.

This is normal behavior because Billing Agreements are fundamentally different to PayPal Standard subscriptions.

A PayPal Standard Subscription needs to be suspended or canceled because future payments would be processed on that subscription if it were to remain active. For a Billing Agreement, this is not the case. Once a subscription purchased using Reference Transactions has been canceled in your WooCommerce store, no future payments are processed against that billing agreement because Subscriptions no longer requests any payments.

The Billing Agreement is left active at PayPal because:

• Billing Agreements are per store not per subscription. Meaning if your customer has purchased multiple different subscriptions with your store, the same Billing Agreement ID is shared between all of those subscriptions. If it were to be canceled when one subscription is canceled, all other subscriptions would be unable to continue.
• Billing Agreements can be manually added to a manually created subscription or even used to undo cancellation of a canceled subscription (impossible to do with PayPal Standard Subscriptions), but only if the billing agreement remains active in PayPal.

For these reasons, it is recommended that you do not cancel Billing Agreements manually at PayPal. If your customer chooses to cancel their Billing Agreement at PayPal, Subscriptions handles that and cancels all subscriptions in your store using that Billing Agreement. But to give you maximum flexibility in working with customers, it is recommended you do not cancel the Billing Agreement.

Why has the initial payment changed in Subscriptions v2.0.10?

PayPal provide two options for charging an initial payment when creating a billing agreement with reference transactions:

• Charge the initial payment alongside the request to create the billing agreement.
• Charge the initial payment against the billing agreement after it has been created in a separate request.

There is little difference in terms of when the customer pays or the store receives the payment between these options. Both result in a payment almost immediately. However, there are many differences in terms of how PayPal presents and stores details of the payment.

Prior to WooCommerce Subscriptions version 2.0.10, the second of these methods was used. This meant, regardless of whether the initial order was for $0 or more, no initial payment was charged alongside transaction details the customer agrees to at PayPal. This method has the following downsides:

• No details about the initial payment are displayed to the customer when agreeing to the transaction at PayPal. Instead a billing agreement description would be displayed, and PayPal only allow one 127-character string to be used to describe the billing agreement (this description is also used on all future payments against that agreement, including for new subscription purchases and recurring payments, so it needs to be generic to avoid confusion).
• No line item details — individual product, tax and shipping costs — about initial payment are included in emails sent from PayPal to the customer and store owner, only total of payment.
• No line item details for recurring payments are included in the PayPal side of the transaction, so they are not displayed in the PayPal interface or emails sent to the customer or store owners.

A number of store owners complained about this behavior. As a result, Subscriptions version 2.0.10 switched to the alternative method of charging an initial payment in the same request that creates the billing agreement. This helps ensure that line items are displayed to the customer when agreeing to the transaction at PayPal and alongside the transaction at PayPal.

But this method also has a downside: PayPal appears to treat this initial payment as a separate transaction to the billing agreement, even though they are processed in the same transaction. So the amount charged for any initial payment is no longer included in the recurring total for a billing agreement in the PayPal dashboard.

PayPal does not provide a way to ensure that both the initial payment information is presented to the customer on checkout and that initial payment on subscriptions products is accounted for in the total amount charged for a billing agreement/recurring amount at PayPal. There is no way to get the best of both options.

Because better information is provided to the customer on PayPal Checkout with the new method, this was chosen as the best method to use in WooCommerce Subscriptions.

Screenshots of Differences

Screenshots help demonstrate the differences between the two methods.

Is Guest Checkout Possible with PayPal Reference Transactions?

No, PayPal provides no way for customers to check out without a PayPal account when using PayPal Reference Transactions.

If you wish to allow your customers to check out without a PayPal account, there are many other payment gateways that support automatic recurring payments. Stripe or Braintree are good options.

PayPal does provide a premium feature to U.S. based companies to offer Guest Checkout with PayPal Standard; but this is not available for transactions that use PayPal Reference Transactions.

PayPal Express Checkout, the PayPal product that Subscriptions uses to process Reference Transactions, also offers a guest checkout option that can be set in the API request or your PayPal account. However, this option is not supported for Reference Transactions. PayPal explained this via support request; it is not published publicly in the Express Checkout documentation.

Are Payment Authorizations Supported when using PayPal Reference Transactions with Subscriptions?

No. WooCommerce Subscriptions always captures payment immediately for subscription transactions. That includes both the initial and recurring payments. If you would like authorization then capture to be supported in a future version, please submit it as a feature request on the Ideas board.

Do Reference Transactions use PayPal Standard or Express Checkout?

Reference Transactions use the PayPal Express Checkout product. The full name for the product is PayPal Reference Transactions via Express Checkout.

To simplify setup of Reference Transactions with WooCommerce Subscriptions, once Reference Transactions are enabled by PayPal on your PayPal account, Subscriptions will use the PayPal account details already entered on the WooCommerce > Settings > Checkout > PayPal administration screen. This avoids having to duplicate the same PayPal account settings, like API credentials, on an additional administration screen.

As the details on that PayPal settings screen are used for PayPal Standard purchases in WooCommerce core, and PayPal Standard Subscriptions prior to Reference Transactions being enabled, this can lead to confusion about which PayPal product Reference Transactions uses. Because of this, it will be changed in a future version of Subscriptions.

The post PayPal Reference Transactions for Subscriptions FAQ first appeared on CODIBU.

On occasion, store managers may find that when a customer or store manager suspends or cancels a subscription in the store the status change is not reflected at PayPal. Similarly, if a customer changes the payment method or switches a subscription that was originally purchased at PayPal, the original subscription may not be cancelled at PayPal.

This guide covers potential issues that prevent Subscriptions from synchronising with PayPal.

Incorrect PayPal API Signature

To communicate with PayPal, WooCommerce Subscriptions needs your PayPal account’s API Signature. You can learn how to find and where to enter your credentials for this in the PayPal configuration guide.

You PayPal API credentials can be incorrect for a number of reasons:

1. Your API Signature may be for a PayPal Sandbox account but the PayPal Sandbox is disabled in your WooCommerce settings. Or you may be using a live PayPal account’s API Signature with PayPal Sandbox enabled.
2. Missing characters – sometimes PayPal API Signatures include special characters which may be missed when it is copied. Be sure to check that all the characters are entered in your WooCommerce settings page.
3. PayPal provides two forms of API credentials – API Certificate and API Signature. You must use an API Signature with Subscriptions. An API Certificate will not work.

PayPal API credentials notice

PayPal does not provide a way to verify you API Credentials when they are first entered into WooCommerce. Instead, if a request to suspend or cancel a subscription fails due to invalid credentials, it will keep a record of the profile ID that could not be changed and display this notice.

To hide the notice, you must update your PayPal API Credentials.

Old PayPal accounts

Subscriptions created with PayPal accounts that were registered before 2009 can not be synchronised with your store. PayPal doesn’t publish documentation on this issue, but we have anecdotally discovered this via customer’s facing this issue, and information provided by PayPal Merchant Technical Services.

If you have an old PayPal account, check the PayPal Subscription ID value for your subscriptions. Normal IDs will start with an uppercase “I” followed by numbers and letters, e.g. I-nnnnnnnnnnnnnn. Subscriptions created with old PayPal accounts start with an uppercase “S” instead, e.g. S-nnnnnnnnnnnnnn.

To check the PayPal Subscription ID value for your subscriptions:

1. Go to the WooCommerce > Edit Subscription for a subscription using PayPal Standard as the payment method
2. Check the PayPal Subscription ID value displayed under the Subscription Data > Billing Details section

If your store’s PayPal Subscriber IDs start with an S, neither you nor your customers will be able to cancel or suspend the subscription in WooCommerce.

To address this issue, you will need to contact PayPal Merchant Technical Services and notify them that your account is still using out of date subscription IDs and request they update your account.

Out-of-date subscription ID notice

If PayPal returns a subscription ID with an uppercase “S”, e.g. S-nnnnnnnnnnnnnn, then Subscriptions will display the out-of-date account notice at the top of the admin area.

Once you have followed the advice above and contacted PayPal Merchant Technical services, you can safely dismiss the notice and it will never be displayed again.

The post Why aren’t Subscriptions Cancelled or Suspended at PayPal? first appeared on CODIBU.

Please also note, you can not change to the email address in WooCommerce to use the email address of a different PayPal account. You must update the email address used on the PayPal account instead of using a new account. Changing the PayPal account email in WooCommerce will break the connection between PayPal and WooCommerce Subscriptions for all subscriptions created with the old PayPal account.

To change the email address used at PayPal, please follow PayPal’s article on changing your email address. Be sure to set the new email address as the primary email.

To make the change in WooCommerce:

1. Go to: WooCommerce > Settings > Checkout > PayPal.
2. Enter the new email in both the PayPal Email and Receiver Email fields.
3. Save the changes.

The post Change PayPal email address with existing subscriptions first appeared on CODIBU.

The first part of this guide is written for store owners and outlines the administration interface available for this purpose. The second part of the guide is written for developers and provides information on how to programmatically change a subscription’s payment method to manual.

Store Manager Guide to Change a Subscription to Manual Payments

To change a customer’s subscription via the administration interface:

1. Go to the WooCommerce > Subscriptions administration screen.
2. Click the ID of the subscription you want to change to open the Edit Subscriptions screen.
3. Click the pencil icon next to the Billing Details section.
4. Click the Payment Method select box at the bottom of Billing Details.
5. Choose Manual.
6. Click Save Subscription.

Developer Guide to Change a Subscription to Manual Payments

If you need to switch a large number of subscriptions to use manual renewals, and you are proficient with PHP and/or MySQL, you can also programmatically change a subscription’s payment method to be manual.

Change a Subscription to Manual Payments via Database

To change a customer’s subscription via the database:

1. Find the ID of the subscription – this will be displayed on the Manage Subscription table next to the subscription.
2. Open MySQL editor (like PhpMyAdmin).
3. Search the wp_postmeta table for a row where the post_ID is the ID found in step 1 and the meta_key is '_requires_manual_renewal'.
4. If a row is found, change the meta_value for that row to true.
5. If a row was not found in step 3, insert a row into the wp_postmeta table where the post_ID is the ID found in step 1, the meta_key is '_requires_manual_renewal' and the meta_value is true.

You can also bulk insert or update this meta data via a custom MySQL query for a batch of subscription IDs.

Change a Subscription to Manual Payments via PHP

To change a customer’s subscription using PHP:

1. Find the ID of the subscription – this will be displayed on the Manage Subscription table next to the subscription.
2. In you PHP code, instantiate an instance of that subscription using wcs_get_subscription( $subscription_id )
3. Call update_manual() on the subscription instance with a value of true to set the subscription to require manual renewals.

The post Change Subscription from Automatic to Manual Payments first appeared on CODIBU.