WooCommerce Subscriptions is a premium WooCommerce extensionThis 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.
If you are a developer who needs to update custom code to work with Subscriptions v2.0, please refer to the Developer Overview of Subscriptions v2.0 Architectural Changes and Payment Gateway Upgrade Guide for a technical overview of the changes.To help prevent any issues when updating your live site, there are some important things to know and steps you can take before updating. 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. 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. 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.
- Site Ground
- Page.ly (SkyVerge published a great guide on how to create a staging site with Page.ly)
- WP Engine
- Go to your Woo.com > My Account > Downloads page
- Click Download next to WooCommerce Subscriptions
- Go to the WordPress Administration dashboard on your staging site (e.g. www.example.com/wp-admin/)
- Uninstall the active version of Subscriptions plugin by following the instructions for manually uninstalling a WordPress plugin
- Install the plugin with the zip file you downloaded from Woo.com by following the instructions for manually installing a WordPress plugin
Make sure the new folder has the name /woocommerce-subscriptions/, or else some other extensions might not work.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).
The database upgrade process is not necessary with all new versions of Subscriptions. For example, while version 2.0 required a database upgrade, version 2.1 did not.
Upgrade LogsSubscriptions 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
This log file will automatically be deleted a few weeks after the upgrade has completed successfully.
Upgrade Process DesignThe 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. 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 TestThese 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 TestAfter 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.
- Upgrade Subscriptions from 1.4.2 to 1.4.7 (which includes full compatibility with WC 2.1)
- Upgrade WooCommerce from 2.0.x to 2.1.12
- Upgrade Subscriptions from 1.4.7 to 1.5.10 (which includes full compatibility with WC 2.2)
- Upgrade WooCommerce from 2.1.12 to 2.2.11
- Upgrade Subscriptions from 1.5.15 to 1.5.19 (which includes full compatibility with WC 2.3)
- Upgrade WooCommerce from 2.2.11 to 2.3.13
- Upgrade Subscriptions from 1.5.19 to 1.5.29 (which includes full compatibility with WC 2.3)
- Upgrade WooCommerce from 2.3.13 to 2.4.13
- Upgrade Subscriptions from 1.5.29 to 2.0.9 (which includes full compatibility with WC 2.5)
- Upgrade WooCommerce from 2.4.13 to 2.5.5
- Upgrade Subscriptions from 2.0.9 to 2.0.15 (which includes full compatibility with WC 2.6)
- Upgrade WooCommerce from 2.5.5 to 2.6.14
- Upgrade Subscriptions from 2.0.15 to 2.2.8 (which includes full compatibility with WC 3.0)
- Upgrade WooCommerce from 2.6.14 to 3.0.5
- Upgrade Subscriptions to the latest version
- Upgrade WooCommerce to the latest version
This section applies to downgrades between major and minor versions only.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.