Building

How to Migrate WooCommerce to High-Performance Order Storage (HPOS) Safely

How to migrate WooCommerce to HPOS safely: sync mode, current wp wc hpos commands, hook replacements, rollback and common mistakes, checked on 14 November 2026.

·15 min read
Diagram of WooCommerce orders moving from wp_posts and postmeta through sync into the wc_orders tables, titled Migrate to HPOS safely

High-Performance Order Storage (HPOS) keeps WooCommerce orders in dedicated database tables instead of in wp_posts and wp_postmeta. New stores have used it by default since WooCommerce 8.2, and existing stores are never moved over automatically. You migrate by turning on compatibility mode under WooCommerce > Settings > Advanced > Features, letting the two storage layers sync, and only then making the new tables the source of truth. The safe version of that takes an afternoon of preparation and a week of watching, not a single click.

This guide is the version our team follows when we move client stores. It covers the order of operations, the WP-CLI commands that exist today (several older ones are deprecated), what breaks in custom code, how to roll back, and when you should simply leave a store on posts storage for now. Where we give a number or a command, it comes from the official WooCommerce documentation or the WooCommerce source code, and we say which.

Sources checked on 14 November 2026: the WooCommerce developer documentation for HPOS, its CLI tools page, the merchant documentation, and the WooCommerce code on GitHub (trunk, readme stable tag 11.3.0 on the day we read it).

What is High-Performance Order Storage in WooCommerce?

HPOS is a storage change, not a new feature you see. Before it, every order was a post of type shop_order, and every order detail (billing email, totals, payment method) lived as a row in wp_postmeta. With HPOS, WooCommerce writes orders to four tables built for the job. We read the table definitions in the WooCommerce source to confirm what each one holds:

  • wp_wc_orders holds the order row: id, status, currency, type, tax and total amounts, customer id, billing email, created and updated dates in GMT, parent order id, payment method, transaction id, IP address, user agent and customer note.
  • wp_wc_order_addresses holds billing and shipping addresses, one row per address type per order.
  • wp_wc_order_operational_data holds bookkeeping: the order key, cart hash, created-via value, paid and completed dates, discount and shipping totals, and flags such as stock reduced.
  • wp_wc_orders_meta holds the custom meta that plugins and your own code attach to an order.

Your table prefix may not be wp_, so read these as {prefix}wc_orders and so on. The wp_wc_orders table indexes status, creation date, customer id, billing email, transaction id and parent order id, and it has a composite index on type, status and date. That is the reason the Orders screen can filter and sort without joining wp_postmeta over and over.

The old name was Custom Order Tables, which is why older code, hooks and CLI commands still say cot.

Is HPOS enabled by default, and should I turn it on for an existing store?

On a fresh installation of WooCommerce 8.2 or later, HPOS is on by default. WooCommerce states that existing stores “will not be migrated over to HPOS automatically”, so a store that predates 8.2 stays on posts storage until someone chooses otherwise.

Should you? For a store with a few hundred orders, the practical gain is small and the migration still carries risk, so we treat it as a scheduled maintenance task rather than an urgent one. For a store with tens of thousands of orders, a busy admin, or heavy reporting, we recommend moving, because every other query against wp_postmeta also stops competing with order data. WooCommerce does not publish benchmark numbers for HPOS. The merchant documentation says only that it means fewer read and write operations and fewer busy tables. We will not give you a made-up speed-up figure either. Measure your own Orders screen and checkout before and after, as described further down. If your slow admin is the real problem, our WooCommerce database optimization guide covers the other causes that HPOS does not touch.

Should you stay on posts storage, run in sync mode, or go full HPOS?

There are three states a store can sit in, and the middle one is where most migrations spend their time. Pick on purpose.

State

Where orders are read from

Where orders are written

Pick it when

Posts storage, no sync

Posts and postmeta

Posts and postmeta only

An active plugin is incompatible and you cannot replace it yet, or the store is small and stable.

HPOS with compatibility mode (sync on)

The order tables (once you make them authoritative)

Both layers

You are migrating, or you still run reports or plugins that read legacy post data.

HPOS without sync

The order tables

The order tables only. Posts get a placeholder record (shop_order_placehold), no postmeta.

Every plugin and custom script reads orders through WooCommerce functions, and you have run the store for a full business cycle on sync mode.

Two costs of the middle state are worth planning for. Each order write now touches both layers, so write-heavy moments such as a flash sale do more database work than they did before. And while sync is on, legacy post data remains available for tools that still want it. WooCommerce Subscriptions is the documented example: legacy Subscriptions reports were disabled on HPOS stores that run without data sync, according to the March 2023 Subscriptions announcement. If your finance team lives in those reports, check the current Subscriptions changelog before you switch sync off.

How do you check whether your plugins are compatible with HPOS?

Start in the admin. Go to WooCommerce > Settings > Advanced > Features and click “View and manage” under the order storage option. WooCommerce lists the active plugins it considers incompatible. If one of your non-Marketplace extensions is flagged, the switch is disabled until you deal with it. The same list is available from the Plugins screen with the plugin_status=incompatible_with_feature&feature_id=custom_order_tables query arguments.

On the command line, WooCommerce 9.1 added a report that splits plugins into compatible, incompatible and “uncertain” (no declaration at all). We confirmed the command and its flags in the CLI source:

# Checked on 14 November 2026 against WooCommerce trunk (stable tag 11.3.0)
wp wc hpos compatibility-info
wp wc hpos compatibility-info --include-inactive --display-filenames

Inactive plugins always show up as uncertain unless you pass --include-inactive, because they never get the chance to declare anything. An “uncertain” plugin is not proof of a problem. It means the author never told WooCommerce either way. Read the plugin’s changelog or ask the vendor, then test it on staging.

How does a plugin declare HPOS compatibility in code?

A plugin declares support on before_woocommerce_init through the FeaturesUtil class. This is the pattern in the official recipe book, and it goes in the plugin’s main file:

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

Pass false as the third argument if you know your code does not support HPOS. That is an honest declaration and it gives merchants a clear warning instead of a surprise. A declaration is a promise, not a test. Do not treat a green tick as the end of your testing, because a plugin can declare support and still read order meta the old way. If your store also runs the block-based checkout, the separate cart_checkout_blocks feature has its own declaration, covered in our checkout blocks migration guide.

How do you migrate WooCommerce to HPOS step by step?

Here is the sequence we use. Steps 1 to 3 happen on a staging copy first, and the whole sequence is repeated on production in a quiet trading window.

  1. Back up the database and test the restore. A backup you have never restored is a hope. Take a full database export and a host-level snapshot, and store them outside the web root.
  2. Update WooCommerce and the order-related extensions. Vendors ship HPOS fixes in ordinary releases, so run current versions of WooCommerce, Subscriptions, Bookings, your payment gateways and any shipping or invoice plugins before you start. Keep Subscriptions and Bookings active during the migration. WooCommerce warns that deactivating extensions that use custom post types first can cause data discrepancies.
  3. Review incompatible plugins using the Features screen or wp wc hpos compatibility-info. Resolve each one: update it, replace it, or accept staying on posts storage for now.
  4. Turn on compatibility mode. Under WooCommerce > Settings > Advanced > Features, tick the option that synchronizes orders to the posts table. WooCommerce then copies orders to the new tables in the background, 25 orders at a time, through Action Scheduler.
  5. Wait for the sync to finish. You can watch the pending actions under WooCommerce > Status > Scheduled Actions, or use the commands in the next section.
  6. Verify the data with wp wc hpos verify_data (no re-migrate flag yet).
  7. Make the order tables authoritative. Back on the Features screen, select the high-performance order storage option and save. WooCommerce will not let you switch while orders are pending sync.
  8. Keep compatibility mode on and watch the store. WooCommerce advises leaving it on for a while after the switch. This is your rollback window.
  9. Retire sync only after a full business cycle of clean operation, and only once you have confirmed that nothing reads legacy post data.

The duration of step 5 depends on order volume and on whether WP-Cron or a real system cron is firing reliably. If Scheduled Actions shows the data sync pending for hours, jump ahead to the troubleshooting list below before touching anything else.

Which WP-CLI commands does WooCommerce provide for HPOS?

The commands now live under wp wc hpos. The older wp wc cot namespace prints a deprecation warning “since 8.9.0” in the WooCommerce source, and wp wc cot migrate no longer works at all. A lot of tutorials, including earlier versions of this one, still show the old names. We checked each command below against the CLI runner file in the WooCommerce repository and the official CLI tools page.

# Checked on 14 November 2026 against WooCommerce trunk (stable tag 11.3.0).
# Always run `wp wc hpos <command> --help` on your own version first.

# Where do we stand? Shows whether HPOS and compatibility mode are on,
# and how many orders are unsynced or eligible for cleanup.
wp wc hpos status

# How many orders still need to be copied between the two layers
wp wc hpos count_unmigrated

# Copy orders from the active datastore to the other one (default batch: 500)
wp wc hpos sync --batch-size=500

# Compare the two layers. Reports differences, fixes nothing.
wp wc hpos verify_data --batch-size=500

# Show the differences for one order
wp wc hpos diff 123 --format=json

# Copy one order, or selected fields, from one layer to the other
wp wc hpos backfill 123 --from=posts --to=hpos

# Make the order tables authoritative (runs the compatibility checks first)
wp wc hpos enable --with-sync

# Go back to posts storage. Refused while orders are pending sync.
wp wc hpos disable

# Turn compatibility mode on or off on its own
wp wc hpos compatibility-mode enable
wp wc hpos compatibility-mode disable

# Remove legacy order data from postmeta once HPOS is authoritative
# and compatibility mode is off. Destructive. Read the help first.
wp wc hpos cleanup all --batch-size=200

Three of these deserve a closer look.

verify_data --re-migrate is not a routine fix. The source comment says to use it only when you have never run the site with HPOS as the authoritative source, or when you have manually checked the reported errors. Otherwise stale data can overwrite newer data. An earlier version of this guide told you to add --re-migrate after a busy sync. We are correcting that: run verify_data plain, read the report, use diff on a few failing orders, and decide per case.

enable refuses to proceed unless the layers are in sync (or the shop is new) and every installed WooCommerce plugin is compatible. There is an --ignore-plugin-compatibility flag, and we have never needed it on a client store. If you reach for it, you are overriding the safety check that exists to protect your order data.

cleanup deletes data. The official page says it only works when HPOS is enabled and compatibility mode is disabled, and that it stops on orders whose legacy data looks newer. Do not run it during your rollback window. It is a housekeeping job for stores that have already decided never to go back, and a good reason to take another backup first.

What breaks in custom code after you switch to HPOS?

Anything that treats an order as a WordPress post. That includes get_post(), WP_Query with post_type=shop_order, get_post_meta() and update_post_meta() on order ids, and raw SQL against wp_postmeta. The fix is the same everywhere: go through the order object. The recipe book gives the pattern.

$order = wc_get_order( $order_id );

$value = $order->get_meta( &#x27;_my_key&#x27; );

$order->update_meta_data( &#x27;_my_key&#x27;, $new_value );
$order->save(); // save() is relatively expensive, call it once per request

For collections, use wc_get_orders(), which accepts WooCommerce’s order query arguments and works on either storage layer. If you need to know which layer is active, ask \Automattic\WooCommerce\Utilities\OrderUtil::custom_orders_table_usage_is_enabled().

Which hook replaces the old order columns filter under HPOS?

The old manage_edit-shop_order_columns filter no longer runs for orders. Use woocommerce_shop_order_list_table_columns to add or remove columns, and the action woocommerce_shop_order_list_table_custom_column to print each cell. Both pass a WC_Order object for the cell action, not a post id. We confirmed in the list table source (ListTable.php) that the filter name is built as woocommerce_{order_type}_list_table_columns and the cell action as woocommerce_{order_type}_list_table_custom_column, both marked since WooCommerce 7.3.0, so for regular orders (shop_order) you get the names above. The generic WordPress hooks for the HPOS screen also fire: manage_woocommerce_page_wc-orders_columns and manage_woocommerce_page_wc-orders_custom_column. The source says the order-type specific action takes precedence over the generic one.

add_filter( &#x27;woocommerce_shop_order_list_table_columns&#x27;, function ( $columns ) {
    $columns[&#x27;po_number&#x27;] = __( &#x27;PO number&#x27;, &#x27;your-textdomain&#x27; );
    return $columns;
} );

add_action( &#x27;woocommerce_shop_order_list_table_custom_column&#x27;, function ( $column, $order ) {
    if ( &#x27;po_number&#x27; === $column ) {
        echo esc_html( $order->get_meta( &#x27;_po_number&#x27; ) );
    }
}, 10, 2 );

Does the order save hook still fire under HPOS?

Yes, woocommerce_after_order_object_save still fires. It is not tied to the storage layer. In the abstract data and order classes, save() fires woocommerce_before_{object_type}_object_save and woocommerce_after_{object_type}_object_save around the datastore call, with the object and its data store as arguments, and for orders the object type is order. That is why this hook is the recommended replacement for post-era hooks: it runs the same way on both storage layers. It fires once per $order->save() call. An earlier version of this post claimed it fires twice while sync is on. We could not reproduce that from the source, so we removed the claim. If you see duplicate side effects, look for two separate save() calls, which is the usual cause when plugins touch the same order in one request.

What replaces save_post_shop_order?

Use woocommerce_after_order_object_save for “any save”, woocommerce_new_order for creation, and woocommerce_update_order for updates. The HPOS datastore fires woocommerce_new_order and woocommerce_update_order itself, as we saw in its source. With sync on you may see post hooks fire when WooCommerce backfills the posts layer, but that is a side effect of compatibility mode and it disappears when you retire sync. Code that depends on post hooks for orders will break at that moment, which is a reason to find it during the migration, not afterwards.

Why does get_post_meta return nothing for an order after enabling HPOS?

Because the data is no longer in postmeta, or no longer kept current there. With sync on, WooCommerce copies order data to the posts layer, so a stray get_post_meta() may still appear to work, and that is what makes this bug dangerous: it passes testing on staging with sync on and fails in production the day sync is switched off. With sync off, the HPOS datastore creates only a placeholder post and writes nothing to postmeta, as the developer documentation describes. A support thread on wordpress.org shows the same confusion from the user side: a plugin that adds an order meta box showed nothing because HPOS orders are no longer post objects (see the box below). The fix is $order->get_meta().

Which screen id do meta boxes use under HPOS?

A meta box registered on the shop_order screen does not appear on the new order edit page. The recipe book uses wc_get_page_screen_id( 'shop-order' ) when HPOS is active and falls back to 'shop_order' otherwise. Your callback may receive either a WP_Post or a WC_Order, so the first line of the callback should be $order = wc_get_order( $post_or_order_object->ID ?? $post_or_order_object->get_id() ); or the equivalent through OrderUtil::init_theorder_object().

What about CSS and JavaScript aimed at the old Orders screen?

The Orders list is a different screen, at admin.php?page=wc-orders instead of edit.php?post_type=shop_order. Selectors that start with .post-type-shop_order stop matching, and links built with get_edit_post_link() on an order id point at the wrong place. Use OrderUtil::get_order_admin_edit_url( $order_id ) for links.

Common mistakes people report

Reports we checked on 14 November 2026. These are paraphrased from public threads and official posts. We link each one so you can read the original and check whether the vendor has since shipped a fix.

  • An order columns plugin stops working after HPOS. A user of Ni WooCommerce Admin Order Columns reported that version 1.6.1 and later did not work with HPOS. The thread closed without a recorded fix. wordpress.org thread.
  • A fatal error on the Orders page from a plugin that is not ready. In May 2023 a store owner hit a fatal TypeError on the orders screen after migrating with post meta replication on, and traced it to the premium Local Pickup Plus plugin, which was not yet HPOS compatible. They switched to WooCommerce’s built-in local pickup. wordpress.org thread.
  • Order meta boxes that show nothing. Someone installed an order-metadata viewer expecting meta boxes on the order page and saw none. The author explained that HPOS no longer treats orders as post objects, which is the same cause as the meta box screen id above. wordpress.org thread.
  • The data sync action never finishes. A store owner described the Action Scheduler job woocommerce_run_data_sync staying pending and coming back after manual deletion, and asked how to disable HPOS safely. The support reply asked for the Scheduled Actions screen and the System Status Report, and suggested WP Crontrol to check WP-Cron. wordpress.org thread.
  • Subscriptions reports empty after sync is off. WooCommerce’s own announcement says legacy Subscriptions reports were disabled on HPOS stores without data sync, and advises keeping sync on if you need them. WooCommerce developer blog.
  • Deactivating Subscriptions or Bookings before enabling HPOS. The merchant documentation warns that this can cause data discrepancies, and recommends switching back to posts storage, letting sync finish and trying again if it already happened. WooCommerce documentation.

How do you roll back from HPOS to posts storage?

Rollback is a supported path, and it works best if you have not retired compatibility mode. The official steps: make sure compatibility mode is enabled (if it was off, wait for synchronization to finish), choose “WordPress posts storage (legacy)” under WooCommerce > Settings > Advanced > Features, save, and optionally disable compatibility mode afterwards. The merchant documentation says reverting can be done instantly once the layers are in sync. From the command line the equivalent is:

wp wc hpos status
wp wc hpos sync          # if status shows unsynced orders
wp wc hpos disable       # refused while orders are pending sync
wp wc hpos verify_data   # confirm the posts layer holds everything

If you already switched sync off and ran cleanup, you no longer have an easy way back. Orders placed since the cutover exist only in the order tables. You can still re-enable compatibility mode and let WooCommerce copy them across to the posts tables, then disable HPOS, but you are now doing surgery on live data and the backup is the real safety net. This is the strongest argument for the one-week soak in step 8 of the migration: the rollback window stays short and the way back stays open.

Staging checklist before you touch production

Run through this on a clone with recent order data. We keep it as a short list because the point is to run it, not to read it.

  • Place a test order with each live payment method, then refund it partially and fully.
  • Edit an order status from the Orders list, from the order screen and by bulk action.
  • Open an order that contains a subscription, a booking or any custom order type and edit it.
  • Run every scheduled report, export and ERP or accounting sync once and compare totals with the same period on production.
  • Pull /wp-json/wc/v3/orders and compare the response shape with production.
  • Search the order list by email, by order number and by customer name.
  • Check debug.log for notices that mention shop_order, get_post_meta or deprecated order functions, and wc-logs for sync failures.
  • Time the Orders screen and a checkout before and after. Write the numbers down so you can answer “was it worth it” with data.

If your store has custom order statuses or automated status transitions, read our guide to custom WooCommerce order workflows first, because workflow code is where direct post queries tend to hide. Our WooCommerce performance checklist lists the other speed items worth doing in the same maintenance window.

When should you not migrate to HPOS yet?

Wait when the Features screen lists an incompatible plugin that does something the store cannot do without, and the vendor has no date for a fix. Wait when a custom reporting tool queries wp_postmeta directly and nobody can rewrite it this quarter. Wait when you are a week from a major sale.

Do you need help, or can you do this yourself?

A store with mainstream plugins, a staging site and someone comfortable with WP-CLI can do this from the steps above. Where we get called in is the other kind of store: custom checkout code, a home-made ERP sync, scripts that query order meta directly, or no staging copy. Our team does this as part of our WooCommerce development services: we audit the codebase for post-based order access, move the code to the order object, run the migration on a staging clone, and hand over the repository and a rollback plan. It is one option, and for a simple store the free route is perfectly fine.

Frequently asked questions

Will HPOS delete my existing orders?

No. Enabling compatibility mode copies orders into the new tables and leaves the posts data in place. Data is removed only if you later run wp wc hpos cleanup, which refuses to run until HPOS is authoritative and compatibility mode is off.

How long does the sync take?

It depends on order count, hosting and whether your cron runs reliably. The admin sync processes 25 orders per Action Scheduler batch, and wp wc hpos sync defaults to 500 per batch. WooCommerce publishes no time per thousand orders and hosts vary widely, so run it on staging with a copy of your data and measure.

Do I need to put the store in maintenance mode?

WooCommerce does not require it, and compatibility mode keeps the layers in step while orders arrive. We still pick a quiet window for the authoritative switch, because that is the one moment you want few customers placing orders while you watch.

Can I use HPOS with WooCommerce Subscriptions and Bookings?

Subscriptions has declared HPOS compatibility since version 4.9.0 according to the March 2023 announcement. Keep both extensions active while you migrate. Check each extension’s current changelog for the version you run.

Does HPOS change what customers see?

No. The storefront, emails and order pages look the same. Only admin screens, custom code and integrations that touched order storage directly are affected.

My HPOS option is greyed out. Why?

Almost always because WooCommerce found an active plugin that is incompatible, or because orders are still pending sync. Open “View and manage” on the Features screen and run wp wc hpos status.

Is the wp wc cot sync command still valid?

It is deprecated. In the WooCommerce source, the wc cot commands warn that they are deprecated since 8.9.0 and point to wc hpos, and wc cot migrate no longer works. Some official pages still show the older name, so use wp wc hpos sync and check --help on your version.

What we would do on your store

Run wp wc hpos compatibility-info on staging today. It takes a minute and tells you whether the migration is a Friday task or a quarter-long project. If the answer is “a Friday”, follow the nine steps, keep sync on for a full business cycle, and measure the Orders screen before and after. If the answer is “a quarter”, you now know what you are waiting for.

Last checked on 14 November 2026 against the WooCommerce documentation and source linked above. Commands and defaults change between WooCommerce releases, so confirm with --help on the version you run.

Part of the Wbcom Designs family

The all-in-one WordPress community stack

Also ours: wbcomdesigns.comvapvarun.combrndle.com