WooCommerce HPOS: what High-Performance Order Storage is and how to migrate

High-Performance Order Storage (HPOS) is the way WooCommerce stores orders in dedicated database tables instead of in WordPress's general-purpose posts and postmeta tables. It has been the default for new WooCommerce installations since WooCommerce 8.2, released in October 2023.

If your store was created before then, it may still be using the older "WordPress posts storage". WooCommerce does not switch existing stores automatically: you enable HPOS yourself, ideally after checking that your extensions are compatible and letting a sync mode copy your orders across first.

This guide explains what HPOS changes, why it matters for performance, how to check compatibility, how compatibility (sync) mode works, and a safe step-by-step migration for an existing store, including the WP-CLI commands larger stores rely on.

What HPOS is

For most of its history WooCommerce saved each order as a WordPress "post" of a special type, with order details (addresses, totals, payment data) stored as rows of metadata in the wp_postmeta table. That table also holds metadata for every page, post and product on the site, so on a busy store it becomes very large and heavily used.

HPOS moves orders into their own tables. According to WooCommerce's HPOS documentation, it uses four custom tables (shown here with the default wp_ prefix):

HPOS uses WooCommerce's CRUD (create, read, update, delete) layer, which is why extensions that read orders through WooCommerce's own functions keep working, and extensions that query the posts tables directly do not.

Why it matters for your store

WooCommerce describes the benefit as "fewer read/write operations and fewer busy tables", allowing stores to scale. In plain terms:

• Order queries run against tables designed for orders, not a shared table full of unrelated content.
• Order activity competes less with page and product queries for the same table.
• Order data has a clearer structure, which makes reporting and integrations simpler to build correctly.

The gain is largest on stores with many orders. A small store will notice less, but it still benefits from being on the default storage that new WooCommerce features and extensions are built and tested against. For other speed work, see our guide on speeding up a WooCommerce store.

How to tell which storage your store uses

Go to WooCommerce > Settings > Advanced > Features. Under order data storage you will see two options:

• High-Performance Order Storage
• WordPress posts storage (legacy)

The same screen has the compatibility mode checkbox. If the HPOS option is grayed out, WooCommerce has detected an active plugin that is incompatible.

Checking extension compatibility

Extensions tell WooCommerce whether they support HPOS by declaring compatibility in their main plugin file. Developers do this with FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true ) on the before_woocommerce_init hook. WooCommerce then shows the result to you:

• The Plugins screen warns about plugins that are incompatible or have not declared compatibility.
• The HPOS option cannot be enabled while an incompatible plugin is active.
• WooCommerce.com product pages show a Compatibility section that lists HPOS support.

Before migrating, list every WooCommerce-related plugin, check its changelog or product page for HPOS support, and update it. If a plugin you depend on is not compatible, contact the developer or plan a replacement. Custom code that queries wp_posts for orders, or uses get_post_meta() on orders, needs rewriting to use WooCommerce's order functions; our article on plugin database design explains why direct table queries are fragile.

Compatibility mode (sync)

Compatibility mode keeps both storage systems in sync. When it is on, WooCommerce writes each order to the active storage and copies it to the other one. According to WooCommerce, sync happens in three ways:

• Immediate: new and changed orders are synced as they happen.
• Scheduled: existing orders are backfilled in batches through Action Scheduler (WooCommerce documents batches of 25 orders).
• Manual: you run a sync with WP-CLI.

Sync has a cost: every order write happens twice. That is why it is a transition tool rather than a permanent setting for most stores. WooCommerce advises keeping it on "for some time to ensure a seamless transition", because "reverting to the post table can be done instantly" while both are in sync.

Step-by-step: migrating an existing store to HPOS

1. Back up the full database and files, and confirm you can restore. Our guide to automating website backups covers this.
2. Update WordPress, WooCommerce and all extensions on a staging copy of the store.
3. Check compatibility on the Plugins screen and resolve or replace incompatible plugins.
4. Turn on compatibility mode in WooCommerce > Settings > Advanced > Features ("Enable compatibility mode (synchronizes orders to the posts table)").
5. Let the sync finish. Watch progress in WooCommerce > Status > Scheduled Actions, or use WP-CLI on larger stores (below).
6. Switch to High-Performance Order Storage once all orders are synced, keeping compatibility mode on.
7. Test real workflows: place orders with each payment method, issue a refund, run reports, check fulfillment, accounting and shipping integrations.
8. Repeat on production during a quiet period, then monitor for a few weeks.
9. Turn off compatibility mode once you are confident, to stop double writes.

WooCommerce publishes a separate guide for large stores with additional planning advice.

WP-CLI commands for HPOS

Background sync can be slow on stores with many orders. WooCommerce's HPOS CLI tools let you run each step directly:

Treat cleanup as a one-way, destructive step. Run it only after you have turned off compatibility mode, kept recent backups and run on HPOS without problems for a long period.

Should you migrate now?

For most stores still on posts storage, yes, with preparation. HPOS has been the default for new stores since October 2023, so most actively maintained extensions have had years to add support, and new WooCommerce features are built with HPOS stores in mind. Staying on legacy storage indefinitely means your store drifts further from how WooCommerce is developed and tested.

Reasons to wait a little longer:

• A business-critical plugin is still flagged as incompatible and has no update or replacement yet.
• You have custom code or reporting that reads orders directly from the database and has not been rewritten.
• You are about to run a major sale or seasonal peak. Migrate in a quiet period instead.

If none of those apply, schedule the migration like any other maintenance task, with a backup, a staging test and someone available to monitor orders afterward. Our article on handling CMS and plugin upgrades covers the general process.

Rolling back if something goes wrong

If you kept compatibility mode on, rolling back is a setting change: select WordPress posts storage (legacy) in the Features screen and save. WooCommerce supports switching between the two storages. If you turned sync off before rolling back, run a sync first so orders created on HPOS exist in the posts tables too. This is the main reason to leave compatibility mode on until you are confident.

Common problems

• The HPOS option is disabled: an active plugin is incompatible. Update or deactivate it.
• Sync is stuck: check Scheduled Actions for failed jobs, confirm WP-Cron is running, or use wp wc hpos sync.
• A report or integration shows missing orders: it is probably reading the posts tables directly. Ask the vendor for an HPOS-compatible version.
• Data mismatches: run wp wc hpos verify_data, then diff on specific orders.

Conclusion

HPOS is the standard order storage for WooCommerce, and new stores already use it. For an older store, the migration is straightforward if you do it in order: back up, confirm compatibility, sync with compatibility mode on, switch, test, then turn sync off. Keep the rollback path open until you are sure. Find more store guides in our WordPress hub, including what WooCommerce is. If you would like help with a migration or with custom code that is not yet compatible, eSEOspace offers WordPress plugin development.

Frequently asked questions