New version check in WooCommerce 3.2

WooCommerce 3.2 will be released with a new version check feature. If you have active plugins that have not declared compatibility with the latest version of WooCommerce a variety of helpful warnings display when you try and upgrade WooCommerce. These messages will advise you about how you can safely upgrade in a way that prevents plugin errors that lead to broken features and store downtime. WooCommerce will also prevent itself auto-updating if there are incompatible plugins.

You have to already be on WooCommerce 3.2 to get this feature, so the first time you may see these sorts of messages will be when upgrading to WooCommerce 3.3.

Adding version check support to your plugins

The feature works by checking the active plugins’ headers to determine compatibility with WooCommerce. This requires the cooperation of the plugin development community. If you are a plugin developer it is simple and straightforward to add support for the version check to your plugins. There are just two new headers you need to add:

 * Plugin Name: WooCommerce Barter Gateway
 * Plugin URI:
 * Description: Take payments by bartering crops and livestock.
 * Author: WooCommerce
 * Author URI:
 * Version: 3.0.7
 * Text Domain: woocommerce-gateway-barter
 * Domain Path: /languages
 * WC requires at least: 3.0.0
 * WC tested up to: 3.2.0

There are some great benefits to adding the headers and keeping them current:

  • You will have to field less complaints from users that the new WooCommerce version broke your plugin. They will have clear warnings about the dangers of upgrading when the plugin is incompatible. This should reduce your support load when new versions of WooCommerce are released.
  • You will not have to rush updates to your plugin. If a user upgrades WooCommerce and your plugin breaks you are under a lot of pressure to release an update fast. If the user waits until a compatible version of the plugin is released before updating WooCommerce you do not have this problem.
  • Users will trust your plugin more. By adding the header you are letting the user know that the plugin has been tested, works with their version of WooCommerce, and is actively maintained to be compatible with WooCommerce.

The headers should be updated after each major (4.0.0) and minor (3.2.0) WooCommerce release. They do not have to be updated after patch releases (3.2.1). You should ideally have these headers in your plugins by WooCommerce version 3.3.0 to get the benefits.

20 responses to “New version check in WooCommerce 3.2”

  1. Just to confirm Claudiu… are you saying the warnings will NOT display if your plugin declares it’s compatible with the current MINOR level?

    So if we declare…

    * WC tested up to: 3.2.0

    …and the WooCommerce team releases 3.2.1, the warning will NOT show to users when the 3.2.1 update comes through for WooCommerce?

    And can you confirm what the behaviour will be if the plugin does NOT declare either of these lines? Will it report a warning at all?

    Thanks in advance ๐Ÿ™‚

    1. The warning will not display if the plugin is compatible with the current minor level. Patch releases happen often and just fix bugs, so if the plugin is compatible with the minor level everything should be good. It would be a big hassle for devs if they had to keep the headers updated to the latest patch release.

      If the plugin does not declare the lines and it says something about “WooCommerce” in the name or description you will see an “unknown” last-tested version like in the featured image above. All other plugins without the lines will be ignored silently by the version check.

  2. Gabriel Reguly Avatar
    Gabriel Reguly


    I have asked Otto to add this kind of headers like 3 years ago, nice to see they coming at last.

  3. bildmanufakturwackernah Avatar

    Wow, a long awaited feature. Thanks.

  4. InfiWebs Avatar

    Can this be useful for themes as well?

    1. It doesn’t check themes currently. Themes generally don’t hook deeply into WooCommerce and so won’t break as often during updates.

      1. Mike Nine Avatar
        Mike Nine

        Would definitely like to let my users know if the theme has been updated for the WC version or not. In fact, I’d like to *confirm* that it is tested, show it in green text, to ease peoples minds when they’re updating.

  5. @mike or @claudiu — to confirm, this should be in the *plugin headers*, not the readme?

  6. Will still force automatic updates if enabled?

    1. We’ve filtered it to attempt to disable auto-updates but ultimately this might be out of wc control.

  7. Wow, this is an excellent feature!

    But I’m so close to begging you on the theme’s topic. As developers, we really need this in themes as much as in plugins.

    I’m maintaining 10 WordPress themes with Woo support(a few custom templates) and is turning into a tough task. Our clients always update WooCommerce without checking if we provided an update for that version and this means only hundreds of support tickets with broken shops.

    It could be added as argument in “add_theme_support( ‘woocommerce’, array() );” or in the theme style.css comment.

    1. Why don’t you bundle into the themes a function to prevent updating WooCommers?

      Seems like it could be a good hack for avoiding support tickets ๐Ÿ˜‰

      1. Well, we are not looking for a hack, we are looking for a clear statement that a certain version of a theme is compatible with a certain version of WooCommerce. The end user deserves this info.

        1. You surely can add this clear statement that a certain version of a theme is compatible with a certain version of WooCommerce with your theme description ๐Ÿ™‚

          And the hack to avoid support tickets is not difficult at all

        2. backupsnl Avatar

          Yes i totally agree to this. We also make huge changes in the wordpress templates and functions and we would like this ability also applied for themes. Its a huge benefit. I dont want to disable updating of all plugins when the theme is not compatible, but only for the plugin itself.

          We all saw what happened when 3.0 was released. All themes that changed the single product image template got huge problems.

  8. We’ll have to look into it. I didn’t realize it was a big problem with themes, too. The big limitation is that the Themes screen does not have a good way of showing notifications like the Plugins screen does.

    EDIT: Clicked on the wrong button when posting this. andreilupu this should be a reply to your comment.

    1. Thank you! It is really a pain, especially when big versions pop up.
      Lately, I’ve played a little with the themes list, I’ll try to help with a PR on GitHub if I can.
      But I still believe that the most important part is on the plugins page where the update notification informs the users if the theme or some active plugins are not yet ready for a WooCommerce update.

  9. backupsnl Avatar

    You got my vote to add this ability for themes aswell and i know for sure most theme authors will second that!

  10. Does not seem to work when I add the entries as shown to my plugins. Just keeps showing:
    Not tested with the active version of WooCommerce

Leave a Reply

Your email address will not be published. Required fields are marked *