WooCommerce

Migrating WooCommerce to High-Performance Order Storage (HPOS) Safely

Migrating WooCommerce to High-Performance Order Storage (HPOS) Safely

For most of WooCommerce’s history, orders were stored as a custom post type. Every order was a row in wp_posts, and all its details, like billing address, totals and payment method, were rows in wp_postmeta. That design made sense early on because it reused WordPress’s existing structures. But as stores grew, it became a bottleneck. The postmeta table on a busy store could grow to tens of millions of rows, and order queries became slow. Moving to WooCommerce HPOS fixes that bottleneck.

High-Performance Order Storage, usually called HPOS, fixes this by moving orders into dedicated tables designed specifically for order data. It became the default for new WooCommerce installations in version 8.2, released in late 2023. But existing stores still running on the old posts storage need to migrate deliberately.

If your store was created before then and you haven’t switched, this guide covers how to do it carefully.

What HPOS changes

With HPOS enabled, WooCommerce stores orders in a set of new tables:

  • wp_wc_orders for core order data
  • wp_wc_order_addresses for billing and shipping addresses
  • wp_wc_order_operational_data for internal order details
  • wp_wc_orders_meta for additional metadata from plugins

These tables have proper columns and indexes for the data orders actually need. Searching orders by customer email, filtering by status and date and generating reports become much faster. Orders no longer compete with posts, pages and products in the same tables.

The benefits are most noticeable on stores with thousands of orders or more, but even small stores benefit from cleaner data and better reliability.

How to check your current setting

Go to WooCommerce, Settings, Advanced, Features. Under “Order data storage”, you’ll see either “WordPress posts storage (legacy)” or “High-performance order storage (recommended)”. If it’s on legacy, this guide is for you.

You can also check with WP-CLI:

A value of “yes” means HPOS is active.

The main risk: plugin compatibility

The biggest risk in moving to HPOS isn’t WooCommerce itself, it’s plugins. Any plugin that reads or writes order data by querying wp_posts and wp_postmeta directly, instead of using WooCommerce’s order functions, will break when orders move to the new tables.

Most well-maintained plugins have been updated. WooCommerce tracks compatibility: plugins declare whether they support HPOS, and the Features settings screen lists any active plugins that are incompatible or haven’t declared compatibility.

Before migrating:

  1. Update all plugins to their latest versions.
  2. Check the Features screen for incompatible plugins.
  3. For each one, check whether an updated version or an alternative exists.
  4. Review any custom code in your theme or custom plugins that touches orders.

Custom code is often the hidden problem. Look for code using get_post_meta on order IDs, WP_Query with post_type set to shop_order, or direct SQL on the posts table for orders. These need to be rewritten to use WooCommerce’s CRUD methods, like wc_get_order, $order->get_meta and wc_get_orders.

Step 1: Back up everything

Take a full database and file backup immediately before starting, and confirm you can restore it. The migration touches every order in your store. If anything goes wrong, a working backup is your safety net.

Step 2: Test on staging first

Copy production to a staging site and do the entire migration there first. Use staging to:

  • Check plugin compatibility warnings
  • Run the migration and time how long it takes
  • Test every order-related workflow: placing orders, refunds, status changes, emails, invoices, shipping labels, reports, exports and integrations
  • Find any custom code that breaks

Disable outgoing emails and payment processing on staging, so testing doesn’t affect real customers.

Step 3: Enable compatibility mode

WooCommerce provides a sync feature, sometimes called compatibility mode, that keeps both storage systems up to date at the same time. With sync enabled, orders are written to both the old posts tables and the new HPOS tables.

In WooCommerce, Settings, Advanced, Features, tick “Enable compatibility mode (synchronizes orders to the posts table)”. Keep the legacy storage selected as authoritative for now.

WooCommerce then starts copying existing orders to the new tables in the background, using scheduled actions. On a large store, this can take hours or days.

You can speed it up and monitor it with WP-CLI:

The sync command processes orders in batches and shows progress. Run it during a quiet period, because it adds database load.

Step 4: Verify the data

Once sync finishes, check that the data matches. WooCommerce includes a verification command:

It compares orders in both storage systems and reports differences. Investigate any it finds before moving on. Often these come from plugins that wrote data in unusual ways.

Step 5: Switch to HPOS as authoritative

When sync is complete and verified, change the setting to “High-performance order storage” while keeping compatibility mode enabled. Now HPOS is the main storage, and changes are still copied back to the posts tables.

This is the safest arrangement. If something breaks, you can switch back to legacy storage, and the posts tables are still current.

Watch the store closely for a week or two. Test new orders, refunds, subscription renewals and anything involving integrations. Check error logs daily.

Step 6: Disable compatibility mode

Once you’re confident everything works, disable compatibility mode. Orders are then written only to the HPOS tables, which gives you the full performance benefit.

Keep the old order data in the posts tables for a while as a fallback. WooCommerce provides a command to clean it up later:

Only run this when you’re certain you won’t need to roll back, and after taking another backup.

What to test after switching

A checklist I use for HPOS migrations:

  • Place a test order with each payment method
  • Process a full refund and a partial refund
  • Change order status manually and confirm emails send
  • Generate an invoice or packing slip
  • Print a shipping label, if you use a shipping integration
  • Run a subscription renewal, if you sell subscriptions
  • Search orders by email, name and order number
  • Filter orders by status and date
  • Export orders to CSV
  • Check that accounting, CRM and fulfilment integrations still receive orders
  • View the customer’s My Account orders page

When to wait

Some stores should delay migration:

  • If a business-critical plugin isn’t compatible and has no alternative yet
  • If you’re about to enter a peak sales period, like the weeks before Diwali or Black Friday
  • If you have significant custom order code and no time to test properly

HPOS is clearly the future of WooCommerce, and older storage will eventually lose support. But a careful migration at a quiet time beats a rushed one before your busiest season.

Custom reports and direct SQL queries

Many stores have custom reports, dashboards or exports built over the years by different developers. These often query the database directly, joining wp_posts and wp_postmeta to calculate sales by product, region or period. After HPOS, those queries return nothing for new orders, or worse, return incomplete data that looks plausible.

Make a list of every report, export and integration that reads order data, and check each one on staging after migration. Compare figures for the same period before and after: if the old report shows a hundred orders in March and the new data shows sixty, something is reading the wrong tables.

Rewrite direct queries against the new tables, or better, use wc_get_orders with the right arguments, which works with either storage system:

Performance during the sync

The background sync adds database writes for every order. On large stores, run the WP-CLI sync during the quietest hours and watch database load. If the server struggles, sync in smaller batches with the –batch-size option rather than letting scheduled actions process everything at once. Once the initial sync is done, ongoing synchronisation of new orders adds very little overhead.

Communicate with your team

Staff who work in the orders screen will notice small differences after HPOS, such as a different URL format for order edit pages. Tell them in advance, update any bookmarks or internal documentation and ask them to report anything that looks wrong during the first weeks. They’re often the first to spot a problem with an integration.

Keep a rollback plan written down

Before switching, write a short rollback note: which setting to change, who is allowed to change it and how to confirm orders are flowing again. In a stressful moment, a three-line note beats searching documentation. Done carefully, the move to WooCommerce HPOS is uneventful, which is exactly what you want from a database migration.

Frequently asked questions

Will HPOS make my store faster for customers?

Mostly it speeds up admin order screens, reports and order-related queries. Checkout can benefit too, especially on stores with large order histories.

Can I go back to legacy storage?

Yes, as long as compatibility mode was enabled and the posts tables are still in sync. Once you disable sync and clean up the old data, going back becomes much harder.

Do new stores need to do anything?

No. New installations since WooCommerce 8.2 use HPOS by default.

What if a plugin says it’s incompatible but seems to work?

It may only be working by luck, or failing quietly. Contact the developer and test carefully. Don’t migrate production while relying on an incompatible plugin for anything order-related.