WooCommerce HPOS Compatibility: Custom Code Migration Guide

Updating your store for WooCommerce HPOS compatibility custom code requires moving away from WordPress post meta functions and shifting to native order data stores. High-Performance Order Storage (HPOS) moves orders out of wp_posts and wp_postmeta into dedicated relational tables (wp_wc_orders and related tables). If your custom snippets, themes, or plugins still read and write directly to post meta, your site will drop data, display stale records, or block HPOS activation entirely.

Quick answer

• Stop calling get_post_meta(), update_post_meta(), and direct $wpdb post queries on order IDs; use $order = wc_get_order( $id ) and $order->get_meta() or $order->update_meta_data() instead.
• Declare explicit compatibility in your custom plugin or theme using the before_woocommerce_init action hook.
• Replace get_posts() and WP_Query with wc_get_orders() whenever fetching collections of orders.
• Enable dual-run sync mode in WooCommerce settings during your staging review to mirror data between legacy tables and HPOS tables before making HPOS authoritative.

Why legacy order code fails under HPOS

Historically, WooCommerce stored every order as a custom post type (shop_order) in wp_posts, with order attributes, billing details, and metadata stored as key-value pairs in wp_postmeta. While this made it easy to query orders with standard WordPress functions, it caused massive table bloat and performance degradation on high-volume stores.

HPOS replaces this flat post-type design with dedicated tables:

• wp_wc_orders: Primary order data (status, currency, customer ID, dates).
• wp_wc_order_addresses: Structured billing and shipping addresses.
• wp_wc_order_operational_data: Shipping methods, payment methods, and operational dates.
• wp_wc_orders_meta: Extension and custom metadata.

When a store makes HPOS authoritative and disables compatibility sync, calls like get_post_meta( $order_id, '_billing_phone', true ) return empty strings because the record no longer exists in wp_postmeta. Direct updates via update_post_meta() write to the legacy table, which the core HPOS order viewer completely ignores.

Never rely on compatibility sync mode in a long-term production environment. Sync mode writes to both table structures simultaneously to assist migration, but running dual writes permanently doubles your database overhead and degrades checkout performance.

Auditing your codebase for legacy order calls

Before modifying code, search your custom plugins and child theme for patterns that interact with orders through the post engine. Run these grep commands from your wp-content directory:

# Find direct post meta operations on orders
grep -rnE "(get_post_meta|update_post_meta|delete_post_meta|add_post_meta)" plugins/ themes/

# Find WP_Query or get_posts targeting shop_order
grep -rnE "('post_type'\s*=>\s*'shop_order'|\"post_type\"\s*=>\s*\"shop_order\")" plugins/ themes/

# Find direct database post queries
grep -rnE "\$wpdb->prefix\s*\.\s*['\"]posts['\"]" plugins/ themes/

Review the results. Any line operating on an order ID or targeting the shop_order post type must be refactored to use the WooCommerce CRUD API.

Refactoring custom code to WooCommerce CRUD methods

Converting your code to the CRUD pattern ensures compatibility whether the store runs on HPOS or legacy posts storage. The WC_Order object abstracts the underlying database structure entirely.

1. Reading and writing custom order metadata

Legacy code typically fetches and updates custom checkout or integration fields using post meta functions. Here is the transformation:

// BAD: Direct post meta access
$tracking_number = get_post_meta( $order_id, '_custom_tracking_number', true );
update_post_meta( $order_id, '_custom_tracking_number', sanitize_text_field( $new_tracking ) );

// GOOD: WC_Order CRUD methods
$order = wc_get_order( $order_id );

if ( $order instanceof \WC_Order ) {
    // Reading meta
    $tracking_number = $order->get_meta( '_custom_tracking_number', true );

    // Writing meta
    $order->update_meta_data( '_custom_tracking_number', sanitize_text_field( $new_tracking ) );
    $order->save();
}

Always call $order->save() after using update_meta_data(), add_meta_data(), or delete_meta_data(). Without save(), changes exist only in memory during that PHP execution cycle and will not persist to the database.

2. Reading core order properties

In legacy setups, developers frequently retrieved customer emails or billing addresses directly from post meta using keys like _billing_email or _customer_user. HPOS splits these into distinct columns and tables. Use dedicated getters instead:

$order = wc_get_order( $order_id );

if ( ! $order ) {
    return;
}

// BAD: Assuming fields live as meta keys
// $customer_id = get_post_meta( $order_id, '_customer_user', true );
// $billing_email = get_post_meta( $order_id, '_billing_email', true );

// GOOD: First-class getters
$customer_id   = $order->get_customer_id();
$billing_email = $order->get_billing_email();
$order_status  = $order->get_status(); // Returns status without 'wc-' prefix
$total         = $order->get_total();

3. Replacing WP_Query with wc_get_orders

Running WP_Query or get_posts with 'post_type' => 'shop_order' will return zero results on stores where HPOS is authoritative and sync is disabled. Migrate those queries to wc_get_orders().

// BAD: Standard post query
$args = array(
    'post_type'      => 'shop_order',
    'post_status'    => array( 'wc-processing' ),
    'posts_per_page' => 20,
    'meta_key'       => '_custom_processing_flag',
    'meta_value'     => 'pending',
);
$orders = get_posts( $args );

// GOOD: High-Performance Order Storage query
$args = array(
    'limit'  => 20,
    'status' => array( 'processing' ),
    'return' => 'ids', // Return array of IDs or 'objects' for WC_Order instances
    'meta_query' => array(
        array(
            'key'     => '_custom_processing_flag',
            'value'   => 'pending',
            'compare' => '=',
        ),
    ),
);
$order_ids = wc_get_orders( $args );

Using 'return' => 'ids' is the best approach when processing large sets, as it minimizes memory overhead until you instantiate individual objects inside your processing loop.

Declaring WooCommerce HPOS compatibility in custom code

WooCommerce actively disables HPOS selection in the admin interface if an active plugin has not declared compatibility. If you maintain custom site-specific plugins or custom modules, you must register compatibility via the before_woocommerce_init action.

Place this snippet inside your main custom plugin file (or child theme functions.php, though custom plugins are preferred for store logic):

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 // true for compatible, false to explicitly flag incompatibility
        );
    }
} );

If your code is housed entirely in a child theme rather than a standalone plugin, pass the child theme's style sheet file or master entry point:

add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            get_stylesheet_directory() . '/functions.php',
            true
        );
    }
} );

If you deliberately maintain a legacy integration that cannot yet support HPOS, pass false as the third parameter. This prevents site administrators from accidentally toggling HPOS and corrupting incoming customer transactions.

Migrating order hooks and lifecycle events

Legacy WordPress hooks used to trigger during order creation and updates do not always fire predictably under HPOS. Update your action references to their modern WooCommerce counterparts:

1. The save_post hook

// BAD: Runs when posts are saved, unreliable under HPOS
add_action( 'save_post_shop_order', 'my_custom_order_save', 10, 3 );

// GOOD: Core WooCommerce order save hook
add_action( 'woocommerce_update_order', 'my_custom_order_save', 10, 2 );

function my_custom_order_save( $order_id, $order ) {
    // Prevent infinite recursion if modifying the order inside this hook
    $processed = $order->get_meta( '_sync_processed', true );
    if ( $processed === 'yes' ) {
        return;
    }

    $order->update_meta_data( '_sync_processed', 'yes' );
    $order->save();
}

Use woocommerce_new_order when handling actions specifically targeted at newly created orders, passing the order ID as the first parameter.

2. Admin order edit screens

HPOS changes the screen identifiers in the WordPress admin dashboard. The legacy screen ID is shop_order, whereas HPOS displays orders using woocommerce_page_wc-orders.

If your custom code enqueues scripts, registers meta boxes, or modifies columns, update your screen checks:

add_action( 'admin_enqueue_scripts', function( $hook_suffix ) {
    $screen = get_current_screen();
    
    if ( ! $screen ) {
        return;
    }

    // Check for both legacy and HPOS admin screens
    $is_legacy_order_screen = 'shop_order' === $screen->id;
    $is_hpos_order_screen   = 'woocommerce_page_wc-orders' === $screen->id;

    if ( $is_legacy_order_screen || $is_hpos_order_screen ) {
        wp_enqueue_script(
            'my-order-admin-js',
            plugin_dir_url( __FILE__ ) . 'assets/order-admin.js',
            array( 'jquery' ),
            '1.0.0',
            true
        );
    }
} );

Testing the database synchronization using WP-CLI

Before switching HPOS to authoritative mode on a production build, verify data integrity on staging using WooCommerce WP-CLI commands. This lets you sync records safely without timing out the web server.

Step 1: Check feature status

Verify that the feature is available and check which data store is currently authoritative:

wp wc hpos status

Step 2: Run the backfill sync

If you have existing orders in wp_posts, run the backfill command to copy all records and metadata into the new wp_wc_orders* tables:

wp wc hpos sync --batch-size=500

Monitor the output for errors or missed records. The batch size can be lowered to 100 if your server has tight memory limits.

Step 3: Verify data consistency

Run the verification command to confirm that the row counts and values match between both storage systems:

wp wc hpos verify-data

If verification passes without discrepancies, log into the WordPress dashboard and navigate to WooCommerce > Settings > Advanced > Features. Set Order data storage to "High-performance order storage" and deselect "Keep level of synchronization between tables active" once your final QA checks pass.

Checklist

• Grep custom plugins and themes for get_post_meta, update_post_meta, and wp_posts queries.
• Replace direct meta operations with $order->get_meta() and $order->update_meta_data().
• Add $order->save() to any routine modifying order data via CRUD.
• Replace WP_Query and get_posts with wc_get_orders().
• Replace save_post_shop_order hooks with woocommerce_update_order or woocommerce_new_order.
• Update admin script and style loaders to check for the woocommerce_page_wc-orders screen ID.
• Add the declare_compatibility call to the before_woocommerce_init action hook.
• Backfill order tables via wp wc hpos sync on staging.
• Verify records with wp wc hpos verify-data before disabling sync mode.

Frequently asked questions