By Greg Nowak. Updated 13 November 2026.
Enabling High-Performance Order Storage (HPOS) looks straightforward in WooCommerce settings. For an established store, the work sits behind that switch: checking that payments, fulfilment, subscriptions, reporting, and staff workflows still function when orders move to a different datastore.
A useful migration plan gives the owner three answers: what needs fixing, what evidence makes the store ready, and how the team will recover if something fails. Here is how to organise that work.
What actually changes with HPOS?
HPOS stores orders in dedicated WooCommerce tables instead of WordPress posts and post metadata. It has been the default for new installations since WooCommerce 8.2. Existing stores may still use the older storage. The four HPOS tables have suffixes _wc_orders, _wc_order_addresses, _wc_order_operational_data, and _wc_orders_meta; the full names depend on your database prefix.
One datastore is authoritative: WooCommerce reads and writes orders there. Compatibility mode synchronises a secondary copy. WooCommerce blocks changing authority while synchronisation is pending, but that check does not validate integrations. The official HPOS documentation explains these roles. A synchronised copy also does not replace a recoverable backup.
Scope the migration around business dependencies
Order volume affects the time needed to copy data. Dependencies determine how much investigation and testing you need. Use this matrix to scope the work before booking a release window.
| Store dependency | What to investigate | Evidence needed |
|---|---|---|
| Payment gateways and subscriptions | Callbacks, renewals, retries, refunds | Successful lifecycle tests for each method |
| Custom plugins and snippets | Direct order access through WordPress tables | Code review and tests under HPOS |
| Warehouse, accounting, and reporting | Database queries and export jobs | Correct records reaching each destination |
| Large order history | Migration duration and server load | Timed rehearsal with representative data |
Audit beyond the plugin compatibility screen
Start with wp wc hpos compatibility-info, then inspect what it cannot classify: must-use plugins, snippets, scheduled SQL exports, and external database readers. Ask finance, support, and fulfilment which tools they depend on. Record an owner and a test for each dependency.
Developers should review order-related uses of get_post(), get_post_meta(), update_post_meta(), WP_Query, and raw SQL. These functions remain valid elsewhere in WordPress; investigate matches involving orders.
Follow the HPOS extension recipe book: retrieve orders with wc_get_order(), query with wc_get_orders(), and use order getters, setters, or metadata methods followed by save(). Where behaviour must differ, check \Automattic\WooCommerce\Utilities\OrderUtil::custom_orders_table_usage_is_enabled(). For custom meta boxes, select wc_get_page_screen_id( 'shop-order' ) under HPOS and the legacy shop_order screen otherwise; handle the order object correctly.
After testing, declare compatibility from the main plugin 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 );
}
} );That declaration records support; it does not repair incompatible code.
Compatibility mode cannot rescue legacy writes
WooCommerce’s 10.7 advisory disables “sync on read” by default. Previously, this mechanism could pull newer posts-table changes into HPOS during a read. Ordinary compatibility synchronisation from HPOS to posts continues.
The practical consequence: code writing directly to wp_posts or wp_postmeta must be corrected. Keeping compatibility mode enabled does not make those writes supported. Re-enabling sync on read is a temporary workaround, not a migration completion criterion.
Rehearse and test the whole order lifecycle
Use a recent production copy with the intended plugin versions and configuration. Restrict access and isolate outgoing payments, email, and fulfilment jobs so staging cannot process real business activity. Confirm you can restore a backup.
Keep posts authoritative, enable compatibility mode, and time the historical synchronisation. Then make HPOS authoritative on staging. Following WooCommerce’s large-store migration guide, test with compatibility synchronisation both enabled and disabled.
Cover every payment method, delayed callbacks, failures, refunds, order edits, stock changes, email, webhooks, and exports. Include subscription purchases, renewals, retries, and cancellations where relevant. Check totals, tax, addresses, payment references, and custom metadata against what staff and downstream systems receive.
Verify the data before switching production
Use the current HPOS CLI reference; some older guidance still shows earlier command names.
wp wc hpos status— inspect storage and synchronisation status.wp wc hpos count_unmigrated— count orders awaiting synchronisation.wp wc hpos sync— synchronise pending changes from the authoritative datastore.wp wc hpos verify_data— verify migrated order data.wp wc hpos diff <order_id>— investigate an individual discrepancy.
The wc cot namespace is deprecated. Investigate differences before using backfill, cleanup, --re-migrate, or force options: these can overwrite or remove data. A completed sync job is only one part of acceptance.
Agree on cutover and rollback before release
Assign one person to the technical switch and one to operational acceptance. During a quieter trading period, finish production synchronisation, verify the data, and select HPOS under WooCommerce → Settings → Advanced → Features. Watch new orders, payment callbacks, scheduled actions, logs, and fulfilment hand-offs.
Keep compatibility mode enabled through an agreed observation period covering your important workflows. Define rollback triggers, such as missing payment references or failed exports. Before switching back, confirm posts are synchronised. If compatibility mode has been disabled, bring them current first.
Record who can authorise rollback and how affected orders will be reconciled. Restoring an old database can discard newer orders, so treat backup restoration as a separate recovery decision.
If you need help coordinating developers, agency teams, and store operations, talk to Greg about an HPOS migration review. Bring your plugin list, integrations, and custom workflows; those are the starting point for a realistic scope.
Related on GrN.dk
- Claude Sonnet 4.5 Retires This Month: Check Your Workflows
- EU OpenAI Residency Is a Migration Project, Not a Dashboard Toggle
- NGINX 1.30 and upstream connection reuse: what to check before upgrading
Need help with this kind of work?
Discuss your HPOS migration with Greg Get in touch with Greg.