WooCommerce Subscriptions Upgrade Instructions

This guide provides instructions to safely upgrade major versions of the WooCommerce Subscriptions plugin. While many of these steps are not necessary most of the time, it is always safest to follow these steps when upgrading to a major new version. By following these instructions carefully, you will prevent issues and interruptions to your store.

Step 1. Before Updating

↑ Back to top

To help prevent any issues when updating your live site, there are some important things to know and steps you can take before updating.

WooCommerce Dependency

↑ Back to top

Major new versions often increment the minimum WooCommerce version requirements. For example, Subscriptions v2.0 requires a minimum of WooCommerce 2.3 and Subscriptions v2.1 requires WooCommerce 2.4 or newer. You cannot use Subscriptions with a version of WooCommerce that does not meet the dependency. The first step before updating Subscriptions therefore is always to check your version of WooCommerce. If you are running a version of WooCommerce that is no longer supported by the new version of Subscriptions, please update WooCommerce before updating Subscriptions. However, be aware that this only applies if you have kept your extensions mostly up-to-date. If you are upgrading Subscriptions and/or WooCommerce a year or more late, then you will need to do version juggling to make sure you have compatible versions running. For more information on this, see the section on version upgrade paths below.

Update Other Plugins Too

↑ Back to top

On occasion, major new versions of Subscriptions, like version 2.0, introduce breaking changes with prior versions. This means extensions that integrated with Subscriptions may have had to update compatibility for the new version. To get access to this updated compatibility, you will need to be running the latest version of these extensions so please update all of your site’s other plugins, especially WooCommerce extensions, before updating Subscriptions.

Create a Backup

↑ Back to top

Before updating Subscriptions to any major new version, you should back up your site’s files and database. This is especially important for major versions like 2.0 or 3.0 where data storage is often updated. There are a couple of services out there that make backups easier for you:

• BackupBuddy is a very popular backup and migration tool amongst our customers.
• ManageWP does a lot more and is especially useful if you manage multiple websites.
• VaultPress is the full backup service by Automattic.

You can also perform backups manually, but making backups and ensuring your website continues to function are extremely important. Once you run the upgrade process to convert your database to newer versions of Subscriptions, there is no undo button. The only way you can restore the old data is by restoring your site from a backup. This is why it is important to make a backup before updating the extension.

Step 2. Create a Staging Site

↑ Back to top

Now that you have updated all the plugins on your live site and created a backup of your site, you should test the new version of Subscriptions on a staging site before upgrading on your live site. Many WordPress hosts offer a simple way to create staging sites, including:

• Site Ground
• Page.ly (SkyVerge published a great guide on how to create a staging site with Page.ly)
• WP Engine

If you are unsure of whether your host provides staging sites, contact your hosting company’s support team to ask. If your host does not offer a staging site feature, there are premium tools available to help. The WP Stage Coach plugin is a great way to create a staging site without having to copy databases and files manually. Alternatively, you can manually create a staging site by following one of the many tutorials online, like this tutorial from Maintainn or this one from WP Beginner. Subscriptions is designed to handle staging sites safely. No subscription related emails or recurring payments will be processed from your staging site once it has been set up (unless you enable them).

Step 3. Test Subscriptions on Staging

↑ Back to top

Now that we have a test environment with all the files and database from our live website, including its products, orders, and subscriptions, we can test the Subscriptions upgrade process on that site. Once it is upgraded, we can look at a few pages and run through a few common processes to make sure they are working correctly. Once we have tested the changes on the staging site, we can confidently repeat the same steps on the live site.

Step 3.1. Install the Latest Version of Subscriptions

↑ Back to top

To install the latest version of Subscriptions:

1. Go to your WooCommerce.com > My Account > Downloads page
2. Click Download next to WooCommerce Subscriptions
3. Go to the WordPress Administration dashboard on your staging site (e.g. www.example.com/wp-admin/)
4. Uninstall the active version of Subscriptions plugin by following the instructions for manually uninstalling a WordPress plugin
5. Install the plugin with the zip file you downloaded from WooCommerce.com by following the instructions for manually installing a WordPress plugin

Step 3.2. Run the Upgrade Process

↑ Back to top

Some new versions of Subscriptions, like version 2.0, require changing the way data is stored in your site’s database. In order to do this, Subscriptions will provide a database upgrade process. Once the new version of WooCommerce Subscriptions has been activated, if it needs to upgrade your database, you will be redirected to the upgrade process page. Subscriptions will redirect all administrative users to this page to ensure that the database is upgraded as soon as possible when database upgrades are required. Once you arrive at the upgrade process page, begin the upgrade by clicking Upgrade Database. The upgrader will process small batches of subscriptions until all subscriptions have been upgraded. Leave the upgrader webpage open until the upgrade completes. Subscriptions will provide you with estimated length of time until the process will be completed. If the upgrade process is estimated to take a long time, you can leave the computer or continue to work from other tabs or windows; however, do not close the webpage where the upgrade process is running. The webpage needs to remain open for the upgrade to continue. If you do happen to close the webpage, you can reload your website and resume the process without any issues. Similarly, if an error occurs during the upgrade process, refresh the page and resume the upgrade. Then contact support after the upgrade has completed successfully. The upgrade process is designed to handle many errors and it can often continue without corrupting your data if something goes wrong. If the upgrade process is unable to complete, create a support ticket so that we can help diagnose the issue as soon as possible. Be sure to include the log file mentioned below (upload it to a free service like CloudUp, CloudApp or Dropbox and include the link).

Upgrade Logs

Subscriptions keeps a log of everything it upgrades during the process. If you need to contact support about issues with the upgrade, please include this file with the support ticket. It can be found under the file path: /wp-content/uploads/wc-logs/ in the log file beginning with wcs-upgrade. This log file will automatically be deleted a few weeks after the upgrade has completed successfully.

Upgrade Process Design

The batch size for each upgrade will be between 35 and 50, depending on the number of subscriptions on your site (the more subscriptions the smaller the batch size). By upgrading the data in small batches, the upgrade process is slower than doing one large database query or processing larger batches, but it is also more reliable. Specifically, small batches prevent timeout or memory exhaustion errors on the many varieties of possible server configurations. Because upgrading small batches can be slow, the upgrade process is written is such a way that only administrative users are blocked from accessing the store while the upgrading is in progress. Customers, non-logged in visitors and other non-administrative users on your site can continue to browse and even purchase products (including subscription products) from your store while the upgrade is in progress.

Step 3.3. Test WooCommerce Subscriptions

↑ Back to top

Once the upgrade process completes, you will be redirected to a welcome page providing an overview of the new features in this version of Subscriptions. You can use links on this page to navigate to pages on your site to test out new and existing Subscriptions features. Because major new versions of Subscriptions often introduce a number of changes and new features, it’s important to test as many things as possible before you start using it on your live website. We test new versions for months on multiple live and test sites before releasing them publicly, but every install is different. Your site may have a particular plugin installed that is incompatible, or you may have some custom code running in your theme. That’s why it is still important to test the new version with your own store.

Administration Screens to Test

These are the most important administration screens you should visit in order to check that features are working:

• WooCommerce > Subscriptions: the main subscriptions page. Here you should see all of your existing subscriptions in the new table design.
• WooCommerce > Subscriptions > Add Subscription: on the administration screen above, click the Add Subscription button to load the new Add Subscription administration screen. Create a new subscription with products, taxes and shipping. Set the subscriber’s billing and shipping address and a billing schedule to test out the new feature and ensure it works with all of your existing plugins.
• WooCommerce > Subscriptions > Edit Subscription: on the subscriptions administration screen above, click the ID of a subscription under the Subscription column to load the new Edit Subscription administration screen. Here you may be able to modify an existing subscription, depending on whether the payment gateway used to purchase the subscription supports modifications.
• Now visit other administration screens, like the WooCommerce > Orders, WooCommerce > Orders > Edit Order and WooCommerce > Settings > Subscriptions screens to ensure that everything is working correctly.

Front End Pages to Test

After you have tested the administration side of your site, you should test the customer-facing side of the site too. The most important front end customer interactions to test are:

• Purchasing subscription and non-subscription products via your store.
• Viewing and managing a subscription via the My Account page for a customer. You should pay particular attention to the new View Subscription page. Go here to test suspending and reactivating a subscription and try to change the address or payment method on a subscription or upgrade/downgrade a subscription item.

Step 3.4. Report Issues and Get Support

↑ Back to top

If the site crashes after updating or installing WooCommerce Subscriptions, please review the most recent PHP Error logs to better determine the cause of the fatal error. Please report any issues with WooCommerce Subscriptions to WooCommerce via support. Although we do extensive testing with every major new version of Subscriptions, issues may arise. We want to resolve issues with WooCommerce Subscriptions as soon as possible and make sure the site is running smoothly with minimal interruption. To assist us in the support process, kindly ensure that you include all the information specified on the support ticket submission form, along with the PHP error logs. Providing us with as many details and information as possible can significantly expedite the resolution of issues.

Step 4. Update Subscriptions on Live Site

↑ Back to top

After you have successfully run the upgrade process on your staging site and tested compatibility with your store’s plugins and theme, you can now confidently update Subscriptions on your live site. It’s important to run the upgrade process on your live site instead of transferring your database from staging to live, because customers may have purchased new products or renewal orders may have been automatically created while you were testing the update on your staging site. Remember, the Subscriptions upgrade process is written in such a way that while the upgrade is in progress, customers, unauthenticated visitors, and other non-administrative users on your site can continue to browse and purchase products (including subscription products) from your store.

Upgrade Paths for Very Out-of-date Versions

↑ Back to top

To upgrade from really out-of-date versions of Subscriptions & WooCommerce is hard. WooCommerce often breaks backward compatibility, meaning you need to make sure you have a compatible version of Subscriptions prior to upgrading to that version of WooCommerce. Below is an upgrade path to go from Subscriptions version 1.4.2, released on 1st October 2013 to Subscriptions 2.2.n, released in April 2017.

1. Upgrade Subscriptions from 1.4.2 to 1.4.7 (which includes full compatibility with WC 2.1)
2. Upgrade WooCommerce from 2.0.x to 2.1.12
3. Upgrade Subscriptions from 1.4.7 to 1.5.10 (which includes full compatibility with WC 2.2)
4. Upgrade WooCommerce from 2.1.12 to 2.2.11
5. Upgrade Subscriptions from 1.5.15 to 1.5.19 (which includes full compatibility with WC 2.3)
6. Upgrade WooCommerce from 2.2.11 to 2.3.13
7. Upgrade Subscriptions from 1.5.19 to 1.5.29 (which includes full compatibility with WC 2.3)
8. Upgrade WooCommerce from 2.3.13 to 2.4.13
9. Upgrade Subscriptions from 1.5.29 to 2.0.9 (which includes full compatibility with WC 2.5)
10. Upgrade WooCommerce from 2.4.13 to 2.5.5
11. Upgrade Subscriptions from 2.0.9 to 2.0.15 (which includes full compatibility with WC 2.6)
12. Upgrade WooCommerce from 2.5.5 to 2.6.14
13. Upgrade Subscriptions from 2.0.15 to 2.2.8 (which includes full compatibility with WC 3.0)
14. Upgrade WooCommerce from 2.6.14 to 3.0.5
15. Upgrade Subscriptions to the latest version
16. Upgrade WooCommerce to the latest version

Downgrading Subscriptions

↑ Back to top

Some upgrades include data migration routines which change the way data is stored in the database.  This means that when the software is updated, the database is updated as well. If a good upgrade routine is maintained, both types of upgrades should happen smoothly and there should generally be no need for downgrades. There are times, though, when it may be desirable for a site manager to downgrade Subscriptions from the current version to a previous version.  Perhaps there is an error occurring in a newer version that was not present in the previous version.  However, downgrading is not without risk. When Subscriptions is upgraded, there may be a database upgrade that takes place as well.  This would occur with minor releases, meaning the second number in the version changes. For example, a minor release would be from version 2.2.n to 2.3.n.  This also applies to major releases, meaning the first number in the version changes. For example, a major release would be from 2.n.n to 3.n.n. After upgrading from one minor or major version to another, a database update may have taken place as well.  The process of downgrading can cause problems because the database version is now greater than the software. Downgrading the software version does not downgrade the database version. In order to bring attention to the possibility for issues brought by having differing database and software versions, Subscriptions will display a notice when the database version exceeds the software version.  If a downgrade occurs between minor releases, for example, from version 2.3.5 to version 2.2.19 and the database version is now greater than the software version, this notice will appear.

This does not mean that there are errors, but that this type of downgrade raises the possibility for errors.  The exact nature of the issues for each particular downgrade cannot be known without some investigation. For this reason, the notice appears as both a warning and a resource to get help if issues arise by opening a support ticket.