Before you start
- ✓A staging copy of the store
- ✓A clean copy of the exact theme version you're running, to compare against
- ✓A backup of the theme and its companion plugin
- ✓The theme's changelog for the version you're moving to
- ✓The WooCommerce Status page (Templates section) open in another tab
1. Find every change that's been made
Compare the live theme, file by file, with a clean copy of the exact version it's running. Check the theme's companion plugin too: premium WooCommerce themes usually ship one for widgets and page-builder elements, and customisations often end up there. On the store behind this guide, the same product-image code had been changed in the theme and in a companion-plugin widget.
2. Move changes out of the main theme
Where each change belongs depends on what it does:
- How shop pages look: a child theme, a small theme layered on the main one that survives its updates and that WooCommerce checks first.
- How things behave: the child theme or a small custom plugin, using WordPress's official extension points rather than edits to the main theme.
- Companion-plugin changes: a child theme can't reach these, so replace the widget with your own or adjust it from a custom plugin.
3. If you can't move them yet, flag them
Sometimes the only fix is an edit to the theme's own files. If so, make it visible. We added a clearly marked note to the project's history naming the two theme files that must be re-fixed after every update, so the next one couldn't silently undo the work, and saved the fix so re-applying it is mechanical, not archaeology.
4. Check WooCommerce's template list
WooCommerce › Status in the WordPress dashboard has a Templates section listing every shop template your theme replaces with its own copy, flagging any written for an older WooCommerce version. On this store:
| Theme / WooCommerce | Outdated templates |
|---|---|
| Old theme, WooCommerce 9.0 | 3 of 19 |
| Old theme, WooCommerce 9.7 (WooCommerce updated alone) | 10 of 19 |
| New theme, WooCommerce 9.7 | 0 of 21 |
5. Update the theme and WooCommerce together, on staging
The theme release that fixed our templates changed 38 files, including almost 400 lines of the code connecting the theme to WooCommerce: far too much to review on a live store.
6. Re-apply your changes and test the pages that sell
Re-apply anything still in the main theme, then check product pages, category grids, the mini-cart, cart, checkout, account pages and product images at every size before going live.
What usually goes wrong
From our own projects, not the manual.
A routine theme update quietly undid a fix
We'd fixed the theme's product-image code because its on-the-fly image resizing didn't work with WP Engine's offloaded media storage. The fix lived in the main theme, so the next update restored the original code. We re-applied it, this time using WooCommerce's standard single-product image size instead of resizing on the fly.
The same fix was needed in two places
The image code was used by the theme and by a widget in its companion plugin, and updates overwrite both. Find every place the code is used before you fix just one.
Updating WooCommerce alone would have left 10 outdated templates
The theme's copies of WooCommerce templates were written for older WooCommerce versions. With WooCommerce 9.7 and the old theme, 10 of 19 would have been out of date, including checkout, mini-cart and quantity input. Updating the theme at the same time brought it to 0 of 21.
On-the-fly image resizing doesn't suit offloaded media
Theme features that create image sizes when a page is requested need to save files next to the originals, which doesn't work reliably when images live in cloud storage. Use the image sizes WordPress or WooCommerce create at upload time.
Do it yourself, or get help?
If your changes are already in a child theme and the store has a staging copy, updating is routine: update, then test the checkout. If you know or suspect that someone edited the main theme or its plugin directly, or there's no staging site, get help. That's exactly how fixes get lost, and a broken checkout costs more than the update.
Get a developer on it