Preparing for a Major WooCommerce Upgrade

Step Process: WooCommerce Major Upgrade Preparation

1. Clone the live site to staging and restore wp-content plus the database with WP-CLI.
2. Compare all theme template overrides with the new WooCommerce default templates.
3. Rehearse the irreversible database migration and record before/after row counts.
4. Build and verify a plugin compatibility list for WooCommerce 9.x and PHP 8.3.
5. Run real test orders through every payment gateway and refund flow.
6. Deploy to production during a low-traffic window with a rollback file ready.

Comparing Template Overrides

Why this matters: WooCommerce loads templates from /wp-content/plugins/woocommerce/templates/, but your child theme may hold copies in /wp-content/themes/your-child/woocommerce/. A major release in 2026 such as WooCommerce 9.4 can rename hooks, change wc_get_template() arguments, or replace a file entirely. If your override is stale, the shop page may render without add-to-cart buttons or throw a PHP notice.

How to do it: first list every override on staging with a shell command, then diff against the new plugin version.

# find all overridden WooCommerce templates in the active child theme
find /var/www/staging/wp-content/themes/your-child/woocommerce -type f -name '*.php' | sort

# after installing WooCommerce 9.4.0 on staging, diff each file
for f in $(find /var/www/staging/wp-content/themes/your-child/woocommerce -type f -name '*.php'); do
  base=${f#/var/www/staging/wp-content/themes/your-child/woocommerce/}
  new="/var/www/staging/wp-content/plugins/woocommerce/templates/$base"
  if [ -f "$new" ]; then
    diff -u "$new" "$f" | head -40
  else
    echo "MISSING IN NEW VERSION: $base"
  fi
done

How to verify: open WooCommerce > Status > Templates. Every row must say “No changes needed” or list a file you intentionally keep. If a file is marked outdated, copy the new default into your override path and re-apply only your custom add_action changes. Also check wp-content/debug.log for WC_Template_Loader warnings.

Pitfall: developers often delete the whole woocommerce folder in the theme to “reset” it, which silently removes custom checkout fields. Instead, move the folder to woocommerce-backup-2026 so you can restore single files. Rollback: if the diff shows your override is incompatible and the new default breaks layout, restore the backed-up file and keep the old WooCommerce version until you patch it. For a deeper safe-upgrade routine see A Safe WordPress Upgrade Process: Before, During and After.

Irreversible Database Updates

Why this matters: major WooCommerce releases ship migration routines in includes/class-wc-install.php that alter wp_woocommerce_order_items, add HPOS tables such as wp_wc_orders, or convert meta keys. Once wc_update_940_... functions run, the option woocommerce_db_version is bumped and some column types cannot be reverted without a backup.

How to do it: on staging, trigger the update with WP-CLI rather than the browser so you can log everything.

# check current db version before the upgrade
wp option get woocommerce_db_version

# put site in maintenance mode
wp maintenance-mode activate

# run the pending WooCommerce database routines
wp wc update

# confirm the new version took effect
wp option get woocommerce_db_version

# compare row counts of core tables
wp db query "SELECT COUNT(*) FROM wp_posts WHERE post_type='shop_order';"
wp db query "SELECT COUNT(*) FROM wp_wc_orders;"

How to verify: the woocommerce_db_version must equal the target release number (for example 9.4.0), and SHOW TABLES LIKE 'wp_wc_%' should list every HPOS table with a row count matching your legacy orders. Check WooCommerce > Status > Database for “Update required: No”.

Pitfall: running wp wc update on production directly can lock tables for minutes on large catalogs. Always rehearse on staging first. Rollback: if counts mismatch or you see Duplicate column errors, restore the staging database dump taken before the update with wp db import backup-pre-wc940.sql and investigate the failing migration function. If you manage your own stack, our notes on WordPress Server Migration Without Downtime cover how to snapshot safely.

Plugin Compatibility List

Why this matters: payment gateways, shipping methods and subscription add-ons hook into WooCommerce CRUD classes. A plugin written for WooCommerce 8.x may call WC_Order::get_meta() in a way that is deprecated in 9.x, producing fatal errors at checkout.

How to do it: export the active plugin list with versions, then test each against the target release.

# export active plugins and versions
wp plugin list --status=active --fields=name,version,update

# deactivate all WooCommerce extensions except WooCommerce itself
wp plugin deactivate $(wp plugin list --status=active --field=name | grep -v '^woocommerce$')

# reactivate one by one and check for fatals
wp plugin activate woocommerce-gateway-stripe
wp eval 'echo class_exists("WC_Stripe_API") ? "Stripe OK" : "Stripe FAILED";'

How to verify: build a table of results in staging.

Plugin	Version	WC 9.4 Result	Action
WooCommerce Stripe Gateway	8.2.0	OK	Keep
WooCommerce Subscriptions	5.9.0	Deprecated notice	Update to 6.1
Custom Shipping	1.4.3	Fatal error	Patch calculate_shipping()

Pitfall: some vendors declare “compatible” without testing HPOS. Confirm the plugin header contains WC requires at least: 9.4 and HPOS compatible: yes. Rollback: if an extension cannot be patched in time, keep it deactivated and use a core alternative, or stay on the previous WooCommerce minor release. For complex stores, our E-commerce & WooCommerce Development team audits every extension before release.

Testing Orders and Payments

Why this matters: the database migration and template changes mean nothing if a customer cannot pay. Gateways use webhooks and WC_Order::payment_complete(); a broken signature check silently drops orders.

How to do it: enable sandbox mode for each gateway, then place orders covering every path.

# enable WooCommerce sandbox / test mode for core gateways
wp option update woocommerce_stripe_settings --format=json '{"testmode":"yes"}'

# create a test product if none exists
wp wc product create --name="Upgrade Test Item" --regular_price=10 --user=1

# simulate order completion via WP-CLI hook (smoke test)
wp eval '$o = wc_get_order( 123 ); $o->payment_complete(); echo $o->get_status();'

How to verify: place one guest order, one logged-in order, one with a 100% coupon, one refund, and one failed payment. Then query:

wp db query "SELECT ID, post_status FROM wp_posts WHERE post_type='shop_order' ORDER BY ID DESC LIMIT 5;"
wp db query "SELECT order_id, status FROM wp_wc_order_stats ORDER BY order_id DESC LIMIT 5;"

Statuses must be completed for paid and refunded for refunds, and Stripe/PayPal dashboards must show matching test charges. Check WooCommerce > Status > Logs for wc-* gateway errors.

Pitfall: leaving test mode on after QA. Always run wp option update woocommerce_stripe_settings --format=json '{"testmode":"no"}' before going live. Rollback: if a gateway fails after deployment, switch to the backup plugin version folder (wp-content/plugins/woocommerce-gateway-stripe-old) and re-run wp wc update only if needed. Official gateway docs are listed on developer.woocommerce.com for reference during QA.

Action Checklist

• Clone to staging and diff every template override against the new release.
• Rehearse wp wc update and confirm woocommerce_db_version plus row counts.
• Export and test each plugin for WooCommerce 9.4 and HPOS support.
• Place real test orders, refunds and failures through every gateway.
• Turn off test mode and deploy with a rollback directory prepared.

Need expert help executing this plan? Our engineers handle staging, database rehearsals and gateway QA end to end. See our WooCommerce upgrade services and ship your 2026 release with confidence.

Frequently asked questions

How early should WooCommerce major upgrade preparation start?

Start two weeks before the release window. That gives time to patch custom overrides, wait for vendor updates and rehearse the database migration on staging without rushing.

Can I skip staging and update directly on production?

No. Irreversible database updates and template changes can break checkout instantly. Always rehearse on a clone so you have a verified rollback path.

What if a payment plugin is not compatible on launch day?

Keep the previous WooCommerce version or deactivate that gateway temporarily. Use a secondary method such as bank transfer until the vendor ships a tested release.

References & further reading

• WordPress Developer Documentation
• WordPress Theme Handbook
• WordPress Plugin Handbook