WooCommerce HPOS: moving to the new order storage

What HPOS is and what is happening with it

HPOS stands for High-Performance Order Storage, formerly called Custom Order Tables: separate tables for orders instead of keeping them in the WordPress post tables. The main tables are _wc_orders, _wc_order_addresses, _wc_order_operational_data and _wc_orders_meta, all with your database prefix. Existing stores do not switch to the new storage on their own.

The table data comes from the release notes on the WooCommerce developer site. If your store is older than version 8.2, your orders sit in the previous storage, which the settings call “WordPress posts storage (legacy)”. For the general picture of how the store works, see the article on WordPress and WooCommerce.

Do you need to switch right now

There is no urgency: an official announcement that the previous storage is deprecated, and a date for switching it off, appear in no WooCommerce document. The developer documentation does not call it deprecated. Any deadlines from third-party blogs are not confirmed by a primary source, so do not plan around them.

Decide based on your own situation: switching makes sense if you plan new extensions built for HPOS or are preparing for a growing number of orders. If the store is stable and your extensions have not declared compatibility, you can wait. Store speed in general is covered in the article on WooCommerce optimization.

A backup before the switch

Before switching, make a full copy of the database and files and check that it can be restored. The switch changes where orders live, and the cleanup command later deletes orders from the old tables. Without a copy there is nothing to bring that data back with.

The minimum is a database export with WP-CLI or mysqldump and a copy of the site directory. Setting up regular backups is covered in the article on WordPress backups.

wp db export /root/backup/before-hpos.sql
mysqldump --single-transaction -u dbuser -p dbname > /root/backup/before-hpos-dump.sql
ls -lh /root/backup/

Better still, rehearse the whole switch on a copy of the site first: you will see which extensions get in the way without risking live orders.

Checking extensions

Every active plugin must declare compatibility with HPOS; a single incompatible one blocks choosing the new storage in the settings. According to WooCommerce, extensions from WooCommerce.com are compatible, but at your publication date this is worth rechecking. Check third-party and custom plugins yourself.

A plugin declares compatibility on the before_woocommerce_init hook. In addition, the code must not read and write orders directly through wp_posts and wp_postmeta: use wc_get_order() and the order object methods. Otherwise, as the documentation warns, you may read an outdated order or write an order that nobody will read.

use Automattic\WooCommerce\Utilities\FeaturesUtil;

add_action( 'before_woocommerce_init', function () {
    if ( class_exists( FeaturesUtil::class ) ) {
        FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
    }
} );

The switch step by step in the admin

The switch is done in two steps: first compatibility mode is enabled and orders are copied into the new tables, and only then is the new storage chosen as the main one. The admin path is WooCommerce → Settings → Advanced → Features. Item names follow the English interface.

1. Make and verify a backup.
2. Tick “Enable compatibility mode (synchronizes orders to the posts table)” and save the settings.
3. Wait for the background transfer. Orders are moved in batches of 25 per action; progress is visible in WooCommerce → Status → Scheduled Actions.
4. When the transfer is finished, choose High-Performance Order Storage in the “Order data storage” block.
5. For a few days, keep testing the store: checkout, emails, reports, integrations.

The same through WP-CLI

On large stores it is more convenient to run the transfer from the command line: you see progress and errors. HPOS has the wp wc hpos command namespace; the old wp wc cot is marked as deprecated, although it still appears on some documentation pages.

wp wc hpos status
wp wc hpos sync
wp wc hpos verify_data
wp wc hpos --help

The commands status, sync, verify_data, cleanup, backfill and enable are listed in the documentation. We did not verify the flags of each command, so run wp wc hpos --help on your own server. The cleanup command deletes order data from the previous tables, so run it only after a backup and a long verification period.

Compatibility mode: benefit and cost

Compatibility mode keeps orders in sync in both schemas, which is why rolling back to the post tables is instant. The documentation advises not to switch it off right away but to keep it on for some time. The cost is that data is written twice.

Two things follow that the documentation does not state outright: write load grows and the database gets bigger. Watch table sizes and checkout speed; database cleanup techniques are described in the article on WordPress database optimization.

When you are sure everything works, compatibility mode is switched off. After that, rolling back to the old tables is no longer a single toggle.

Frequently asked questions

Will HPOS turn on by itself when WooCommerce updates?

No. For new installations from version 8.2 it is on by default, while existing stores stay on the previous storage until you switch yourself.

Can I go back?

Yes, while compatibility mode is on: the documentation calls the return to the post tables instant. After the old tables are cleaned up, rely only on a backup.

When will the old storage be switched off?

There is no official date, and no statement that it is deprecated. If you come across a specific deadline somewhere, look for it in the WooCommerce documentation, not in retellings.

What should ZevsHost customers do?

On shared hosting the panel provides backups and database access: make a copy through it and carry out the switch in the WooCommerce admin. On a VPS or dedicated server you handle backups, WP-CLI and extension checks yourself.