High-Performance Order Storage (HPOS) was introduced in WooCommerce 7.1 and became the recommended storage engine from WooCommerce 8.0 onwards. Instead of storing orders as WordPress posts in wp_posts and order meta in wp_postmeta, a WooCommerce HPOS migration moves all order data into purpose-built relational tables: wc_orders, wc_order_addresses, wc_order_operational_data, and wc_orders_meta. These tables are indexed specifically for order queries, making the Orders admin list, reporting, and REST API order endpoints dramatically faster on stores with thousands of orders.

Before starting a WooCommerce HPOS migration on a live store, always run it on a full staging environment first. The migration synchronises order data between the old and new tables rather than replacing it, so both storage engines run in parallel during the transition. This means a rollback to legacy storage is possible if any plugin incompatibility surfaces after enabling HPOS.

WooCommerce HPOS migration — complete 5-step process from plugin compatibility check to post-migration verification

Step 1: Check Plugin Compatibility Before WooCommerce HPOS Migration

The biggest risk in any WooCommerce HPOS migration is plugins that query the wp_posts table directly using raw SQL or WP_Query rather than WooCommerce’s order API. These plugins will silently miss orders after the WooCommerce HPOS migration unless they are updated or replaced.

WooCommerce flags incompatible plugins automatically. Go to WooCommerce → Settings → Advanced → Features and look for the compatibility warning under the HPOS option. Any plugin listed there must be updated before completing the WooCommerce HPOS migration.

// INCOMPATIBLE: direct wp_posts query — breaks after WooCommerce HPOS migration
$orders = $wpdb->get_results(
    "SELECT ID FROM wp_posts WHERE post_type='shop_order' AND post_status='wc-processing'"
);

// COMPATIBLE: use WooCommerce order API — works before and after HPOS migration
$orders = wc_get_orders([
    'status' => 'processing',
    'limit'  => -1,
    'return' => 'ids',
]);

// COMPATIBLE: HPOS-safe direct query using the wc_orders table
global $wpdb;
$orders = $wpdb->get_results(
    "SELECT id FROM {$wpdb->prefix}wc_orders WHERE status='wc-processing' AND type='shop_order'"
);

Step 2: Enable Compatibility Mode for the WooCommerce HPOS Migration

WooCommerce provides a compatibility mode that keeps both the posts table and the HPOS orders table synchronised. Enable this before flipping to HPOS-only so that any plugin that hasn’t been updated yet continues to function during the WooCommerce HPOS migration transition period.

// Via WooCommerce Settings UI:
// WooCommerce → Settings → Advanced → Features
// 1. Tick "High-Performance Order Storage (recommended)"
// 2. Tick "Compatibility mode" (keeps posts table in sync during transition)
// 3. Save changes

// Verify via WP-CLI after enabling:
wp option get woocommerce_feature_hpos_orders_enabled
// Should return: yes

// Check sync status of WooCommerce HPOS migration:
wp wc hpos verify-order-data --all

With compatibility mode on, WooCommerce writes every order change to both tables simultaneously. This doubles the write load briefly during the WooCommerce HPOS migration but means any plugin reading from wp_posts still sees current data. Once you have confirmed all plugins are HPOS-compatible, you can turn off compatibility mode to stop the double-write overhead.

Step 3: Run the WooCommerce HPOS Migration Data Sync

For stores with existing orders, WooCommerce must copy all historical order data into the new tables. This is handled automatically when you enable HPOS — WooCommerce queues a background sync job. For large order volumes, the sync can take hours on production. Run it via WP-CLI on a staging environment to get an accurate time estimate first.

# Check how many orders need syncing before WooCommerce HPOS migration
wp wc hpos count-unmigrated-orders

# Run the WooCommerce HPOS migration sync in the foreground
# Add --batch-size=500 for large stores to control memory usage
wp wc hpos migrate-order-data --batch-size=500

# Monitor progress
wp wc hpos verify-order-data --order-id=12345

# After WooCommerce HPOS migration: verify a sample of orders
wp wc hpos verify-order-data --all --verbose 2>&1 | tail -50

Step 4: Verify Data Integrity After WooCommerce HPOS Migration

After the sync completes, verify that the WooCommerce HPOS migration moved all data correctly. WooCommerce includes a built-in verification tool that checks a configurable sample of orders against both tables and reports any discrepancies.

<?php
// Verify a specific order exists correctly in HPOS tables after migration
$order_id = 12345;
$order    = wc_get_order( $order_id );

if ( $order ) {
    // This now reads from wc_orders table after WooCommerce HPOS migration
    echo 'Order status: ' . $order->get_status() . PHP_EOL;
    echo 'Customer:     ' . $order->get_billing_email() . PHP_EOL;
    echo 'Total:        ' . $order->get_total() . PHP_EOL;
    echo 'Storage type: ' . get_class( $order->get_data_store() ) . PHP_EOL;
    // Should show: AutomatticWooCommerceInternalDataStoresOrdersOrdersTableDataStore
}

// Check which storage engine is currently active after WooCommerce HPOS migration
$is_hpos = wc_get_container()
    ->get( AutomatticWooCommerceInternalDataStoresOrdersCustomOrdersTableController::class )
    ->custom_orders_table_usage_is_enabled();

echo 'HPOS active: ' . ( $is_hpos ? 'YES' : 'NO' );

Step 5: Disable Compatibility Mode and Complete the WooCommerce HPOS Migration

Once you have verified data integrity and confirmed all active plugins are HPOS-compatible, disable compatibility mode. This stops the double-write to the legacy wp_posts table and completes the WooCommerce HPOS migration. Order queries now run exclusively against the optimised wc_orders tables.

// WooCommerce → Settings → Advanced → Features
// 1. Ensure "High-Performance Order Storage" remains ticked
// 2. UNTICK "Compatibility mode" once all plugins are verified
// 3. Save

// Post-migration: benchmark order list load time
// wp eval 'echo microtime(true); wc_get_orders(["limit"=>50]); echo " " . microtime(true);'

// Expected improvement after WooCommerce HPOS migration:
// - Orders admin list:  50-80% faster on stores with 10,000+ orders
// - Order REST API:     30-60% faster on filtered queries
// - Reporting queries: 40-70% faster

The official WooCommerce HPOS documentation covers the full schema and migration internals. The WooCommerce HPOS CRUD documentation covers how to build HPOS-compatible custom order types. See our WooCommerce performance optimisation guide for complementary performance improvements, and our WooCommerce hooks reference for HPOS-compatible order hooks.

WooCommerce HPOS Migration: Rollback Procedure

If a critical plugin incompatibility is discovered after completing the WooCommerce HPOS migration, you can roll back. Go to WooCommerce → Settings → Advanced → Features, re-enable compatibility mode first, then untick High-Performance Order Storage. WooCommerce will revert to reading and writing from the wp_posts table. The wc_orders tables remain in the database but are no longer used — data written during the HPOS period is synced back to posts when compatibility mode is active.

Frequently Asked Questions — WooCommerce HPOS Migration