WooCommerce HPOS: The Migration Behind the Settings Toggle

Illustrated infographic summarizing: WooCommerce HPOS: The Migration Behind the Settings Toggle

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
HPOS readiness depends on the complete order workflow.

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

Need help with this kind of work?

Discuss your HPOS migration with Greg Get in touch with Greg.

Sources

Latest articles

Before changing an AI workflow, check that it still does the job. Use realistic examples, clear release criteria and a comparison with the version running today.

Sending an invoice does not mean it has arrived. Understand delivery statuses, the system requirements coming in 2027, and how focused AI support can help finance teams handle errors and follow-up.

Before scaling AI content, check the pages you already have. Verify claims, resolve overlapping coverage, and give WordPress reviewers control over publication.

Build a refund approval workflow in n8n and Stripe that shows reviewers the exact action, expires old approvals and tracks refunds through to completion.

A timeout can hide a successful job creation. Use stable operation IDs, destination API rules and a clear recovery process to prevent duplicate work.

Does your ChatGPT subscription cover website translation? Understand API credits, access and a WordPress workflow that turns approved Danish content into translation drafts.

An internal AI can keep quoting a deleted policy. Check document updates, indexed passages and cached answers to find where outdated guidance survives.

Codex drew all ten pages of my Ninjai comic from the script Claude wrote in the first test. What made that handover work, and what it cost.

ChatGPT delivered ten painted comic pages; Claude drew one page in code. A practical look at AI tool selection, creative briefs and approval decisions.

Get missing supporting documents under control with a clearly scoped AI workflow that sorts replies, coordinates reminders and gives the bookkeeper a clear follow-up list.