WooCommerce HPOS: The Migration Behind the Settings Toggle

By Greg Nowak. Last updated 2026-07-29.

High-Performance Order Storage (HPOS) appears in WooCommerce as a settings option. On an established store, it should be managed as a data migration.

The distinction matters because changing the authoritative order datastore can affect checkout extensions, refunds, subscriptions, admin tools, exports, accounting feeds, warehouse systems, and custom reports. The technical switch may be quick; proving that the surrounding operation still works is the real project.

What HPOS changes

WooCommerce historically stored orders as WordPress posts and post metadata. HPOS uses dedicated tables, including _wc_orders, _wc_order_addresses, _wc_order_operational_data, and _wc_orders_meta. These tables give WooCommerce a structure and indexes designed specifically for order data.

HPOS has been the default for new WooCommerce installations since version 8.2, released in October 2023. Older stores can still use posts as their authoritative datastore while WooCommerce synchronises order data into the HPOS tables. After migration, those roles can be reversed: HPOS becomes authoritative and posts can remain as a synchronised backup during the observation period.

WooCommerce will not allow the authoritative datastore to be changed while orders are waiting to synchronise. That safeguard is useful, but it does not establish that every plugin, report, or external integration is compatible.

How large is your HPOS project?

The number of orders matters, but operational complexity is often the better sizing signal. A modest store with subscriptions, custom fulfilment logic, and direct database reports may require more care than a larger store running a clean, standard stack.

Store profile	Main risk	Sensible approach
Standard plugins, no custom order code	An extension has incomplete HPOS support	Check compatibility, migrate on staging, then test every important order flow
Custom snippets or admin screens	Code assumes an order is a WordPress post	Audit and update the code before production migration
Subscriptions, multiple payment methods, or complex refunds	Less common lifecycle events fail after cutover	Build a test matrix covering purchases, renewals, failures, cancellations, and refunds
BI, accounting, shipping, or warehouse connections	External systems read legacy tables directly	Trace each order-data consumer and test it against HPOS
High order volume or long history	Backfill overruns the change window	Time the complete migration on a recent production copy

A practical HPOS scoping matrix for established WooCommerce stores.

Find the dependencies the plugin screen cannot see

WooCommerce can block HPOS when an active extension declares itself incompatible. Treat that as a useful first check, not a complete audit. Undeclared custom code, legacy snippets, must-use plugins, SQL reports, and external database readers remain your responsibility.

The most important code smell is direct order access through wp_posts, wp_postmeta, get_post(), get_post_meta(), or raw SQL. With HPOS authoritative, a direct read from legacy tables may be stale and a direct write may update data WooCommerce no longer uses.

Order code should normally work through WooCommerce APIs. For example, retrieve an order with wc_get_order(), change metadata using methods such as update_meta_data(), and call save(). Also inspect custom columns, meta boxes, bulk actions, and hooks attached to the legacy order editor: HPOS uses its own order administration screens.

Then look outside WordPress. Ask finance, fulfilment, customer support, and the agency or developer maintaining the store which systems consume order data. A CSV export launched by an employee can be just as operationally important as a formal API integration.

A safer migration sequence

1. Rehearse on representative data

Create a staging environment that closely reflects production, including current plugins, custom code, configuration, and a recent database copy. Enable compatibility mode while WordPress posts remain authoritative, then allow or trigger the historical-order backfill.

WooCommerce’s scheduled process backfills 25 orders per batch. That may be adequate for a smaller store. For larger datasets, use wp wc hpos sync and record the duration so the production plan is based on evidence rather than guesswork.

2. Test business workflows, not only checkout

Run checkout with every live payment method. Test failed and retried payments, refunds, order edits, emails, stock changes, coupons, webhooks, exports, and fulfilment hand-offs. Where relevant, test subscription purchases, renewals, cancellations, and payment-method changes.

Repeat critical tests with synchronisation enabled and disabled. Check what staff see in the order screen and what downstream systems receive. Reconcile a sample of order totals, statuses, addresses, tax, payment references, and custom metadata.

3. Cut over with an observation window

In production, begin with posts authoritative and compatibility mode enabled. Complete the backfill, confirm that no orders remain pending, and verify the data before selecting the WooCommerce order tables as authoritative.

Choose a naturally quieter period, but do not treat this as an unattended night-time toggle. Have technical and operational owners available to watch new orders, payment callbacks, scheduled actions, logs, support contacts, and key integrations.

Use the current CLI commands

WooCommerce’s current CLI tooling lives under wp wc hpos; the older wp wc cot namespace is deprecated. Useful read and migration commands include:

wp wc hpos status — show HPOS, compatibility-mode, and pending-sync status.
wp wc hpos count_unmigrated — count orders still awaiting synchronisation.
wp wc hpos sync — synchronise from the currently authoritative datastore to the other.
wp wc hpos verify_data — compare order data across both datastores while compatibility mode is enabled.
wp wc hpos diff <order_id> — inspect differences for a particular order.

The dedicated CLI documentation now uses verify_data. That supersedes the older verify_cot_data command still found in some migration guidance. Take extra care with repair, backfill, and cleanup options: they can overwrite or remove data and should follow a reviewed discrepancy analysis and a current backup.

Rollback is part of the release plan

Keep compatibility mode enabled after making HPOS authoritative. If a serious problem appears while both datastores are current, WooCommerce can switch back to posts quickly. If synchronisation has already been disabled, reverting remains possible, but posts must first be brought up to date.

Define rollback triggers before cutover: missing payment data, incorrect totals, broken renewals, failed fulfilment exports, or unexplained datastore differences are clearer signals than “the site feels odd.” Record who can make the decision and how affected orders will be checked afterward.

Turn the toggle into a controlled change

A good HPOS project leaves the store with more than a new database setting. It produces an integration inventory, cleaner order-access code, a repeatable test plan, verified data, and an understood fallback route.

If you need someone to coordinate the technical audit with payment, reporting, fulfilment, and agency teams, talk to Greg about an HPOS migration review. The first useful step is usually a scoped audit—not a production toggle.