WooCommerce HPOS Migration: A Compatibility Audit for Custom Stores

<?php
$orders = wc_get_orders(
    [
        'status'       => [ 'wc-processing', 'wc-completed' ],
        'date_created' => '>=' . gmdate( 'Y-m-d', strtotime( '-30 days' ) ),
        'limit'        => 50,
        'paginate'     => true,
    ]
);

foreach ( $orders->orders as $order ) {
    $external_id = $order->get_meta( '_crm_external_id', true );
    $total       = $order->get_total();
}

<?php
$order = wc_get_order( $order_id );

if ( $order ) {
    $order->update_meta_data( '_crm_external_id', $crm_id );
    $order->add_order_note( 'CRM record linked after HPOS-safe sync.' );
    $order->save();
}

A complete HPOS compatibility audit

Full implementation: High-Performance Order Storage changes where WooCommerce persists order data. The safe question is not whether the site can enable the feature. The safe question is whether every reader and writer of order data uses a supported contract. I audit custom code, extensions, scheduled jobs, reports, exports and operational tools before changing production storage.

Map every order-data consumer

Begin with an inventory of code and business processes. Search for direct references to order post types, post metadata and SQL joins. Then interview the people who use exports, fulfilment screens, accounting feeds, customer-service tools and custom reports. A query can be hidden in a plugin, but it can also be hidden in a spreadsheet export that the warehouse depends on every morning.

rg "shop_order|shop_order_refund" wp-content/
rg "get_post_meta|update_post_meta|delete_post_meta" wp-content/
rg "wp_posts|wp_postmeta" wp-content/
wp wc hpos status

Classify each result as a read, write, report, cache or integration. Reads can return stale or incomplete data. Writes are more dangerous because they may update the legacy tables while WooCommerce reads from HPOS. Reports can look plausible while omitting orders, which makes them harder to detect than a visible fatal error.

Replace storage assumptions with WooCommerce contracts

Use wc_get_orders() for order queries and wc_get_order() for retrieval. Use WC_Order getters and setters for fields, metadata, status and notes. Save the object after a group of related mutations. Do not mix a CRUD write with a direct metadata write in the same operation.

Query arguments need testing too. Date ranges, status values, customer filters, pagination and custom metadata do not always behave like a familiar WP_Query. Build fixtures with known orders and assert exact IDs, totals and counts. A report that happens to return rows is not proof that its business rules survived the refactor.

Understand compatibility mode

During migration, WooCommerce can synchronise data between storage engines. Compatibility mode is useful for testing and rollback, but it is not permission to leave incompatible code indefinitely. Synchronisation adds work, and a direct write can still create confusing timing or authority problems. Treat the period as a controlled transition with an owner and exit criteria.

• Record the authoritative storage setting before every test.
• Check whether synchronisation has a backlog.
• Compare the same order through admin, CRUD and reporting paths.
• Run background actions that create or modify orders.
• Verify refunds, notes and custom metadata in both representations.

Test extensions through their real lifecycle

Do not limit the test to creating a simple order. Subscription renewals, partial refunds, pre-orders, bookings, fulfilment updates and payment webhooks can write order data hours or months later. Trigger each workflow in staging and inspect the final order rather than trusting the extension user interface.

For asynchronous gateways, simulate delayed success, delayed failure and duplicate webhook delivery. For imports, test a small repeatable batch and its rollback. For exports, compare counts and totals against a fixed baseline. I keep order IDs for each scenario so a failed assertion can be traced through logs and scheduled actions.

Audit Action Scheduler and WP-CLI jobs

Many HPOS problems appear outside a browser request. Review recurring actions, custom cron hooks and command-line scripts. Confirm that callbacks receive an order ID and load a WC_Order object rather than querying posts. Run the jobs manually in staging and record memory use, duration and failure output.

wp action-scheduler list --status=pending --per-page=20
wp cron event list
wp wc shop_order list --status=processing --user=1
wp db query "SELECT COUNT(*) FROM wp_wc_orders;"

Command names vary with installed tooling, so verify them in the environment before use. The important practice is to exercise background code explicitly. A storefront checkout test will not expose a nightly accounting query or a weekly clean-up job that still assumes posts.

Build a reversible rollout

1. Take a verified database and file backup.
2. Enable synchronisation in staging and wait for the backlog to reach zero.
3. Run the full order lifecycle matrix and compare known records.
4. Deploy refactored extensions before changing authoritative storage.
5. Enable HPOS during a monitored low-risk window.
6. Run live smoke transactions and downstream checks.
7. Keep the rollback condition and responsible person documented.

A rollback is not simply toggling a feature. Confirm that synchronisation is current and understand which writes happened after the switch. If order volume is significant, define the maximum acceptable divergence and stop the rollout before that threshold is crossed.

Observability after launch

Monitor failed scheduled actions, gateway errors, order counts by status, refund activity and integration queues. Add a temporary reconciliation that compares commercial totals with the previous reporting method. Keep it long enough to cover delayed workflows such as renewals and fulfilment updates.

In my experience, HPOS projects succeed when the team stops treating WordPress tables as the API. The migration becomes manageable once every component speaks through WooCommerce objects and query functions, and once background processes receive the same scrutiny as checkout.

Definition of done

• No custom production code queries legacy order tables directly.
• All writers use WooCommerce CRUD and save deliberately.
• Gateways, refunds, subscriptions and fulfilment paths pass.
• Reports and exports match a fixed baseline.
• Scheduled jobs have been executed and observed.
• Synchronisation is current and rollback is documented.
• Monitoring covers delayed failures after launch.

Need a production review?

If this system carries revenue or customer data, I can review the current architecture, reproduce the risky paths and turn the findings into a prioritised implementation plan. Request a technical review.

A realistic HPOS failure scenario

Consider a custom export that reads processing orders directly from wp_posts. Checkout succeeds, the warehouse dashboard looks normal and administrators can edit orders. After HPOS becomes authoritative, the export gradually misses new records. Nothing crashes, so the defect reaches operations as “today’s order volume looks low”. This is why I test counts and known IDs, not only visible pages.

The repair is to express the report through wc_get_orders() or an approved analytics path, add an automated assertion against a fixture set and monitor exported totals after deployment. The same principle applies to accounting, CRM and fulfilment jobs. Silent readers deserve as much attention as order writers.

I also keep the compatibility declaration close to the extension bootstrap and backed by tests. Declaring HPOS support is a maintenance promise. Future changes must continue using WooCommerce contracts, or the declaration becomes misleading.

The maintenance rule after migration

Every future feature that touches an order must begin with WooCommerce APIs, not a table name. I add that rule to the project documentation and code-review checklist. It keeps new reports, integrations and scheduled jobs compatible with the active storage engine and reduces the chance that a later shortcut quietly reintroduces the same migration risk.