WooCommerce High-Performance Order Storage (HPOS): Migration Best Practices

Recently, I migrated one of my client’s WooCommerce stores from the old legacy order system to High-Performance Order Storage (HPOS). The process brought a noticeable boost in speed and reliability, but I also ran into a few unexpected issues—especially around plugin compatibility and custom code.

What surprised me most? Some challenges didn’t show up until I started testing in a real-world environment. Things that seemed simple on paper needed a bit of extra troubleshooting, and I quickly realized there are certain steps every store owner or developer should take to make HPOS migration smooth.

After getting everything up and running, I decided to put together this step-by-step guide. Here, you’ll find practical advice based on hands-on experience: how to prepare, what to check, and how to handle common snags—plus the key code changes that make your store truly future-ready.

Let’s walk through the best practices for migrating to WooCommerce HPOS, so you can enjoy the benefits without the guesswork.

1. What Is HPOS (High-Performance Order Storage)?

High-Performance Order Storage, or HPOS, is WooCommerce’s new system for saving order data. In the past, WooCommerce stored orders in the same tables as posts and pages (wp_posts and wp_postmeta). That worked for smaller stores, but as sales grow, performance problems begin.

HPOS moves order data to special, dedicated database tables designed just for orders, such as:

• wp_wc_orders
  
• wp_wc_order_addresses
  
• wp_wc_order_operational_data
  
• wp_wc_orders_meta

This means your site can handle more orders, run faster, and scale more easily as your business grows.

2. Why Should You Care About HPOS?

• Faster admin and frontend performance—especially when searching, filtering, or exporting orders.
  
• Less database “bloat”—orders are kept separate from posts and pages, making backups and queries simpler.
  
• Easier troubleshooting and scaling—order-related slowdowns are much less common.
  
• WooCommerce’s future is built on HPOS—all new WooCommerce features will expect it.

3. Understanding Legacy Order Storage vs. HPOS

Legacy storage:

• Orders = Custom posts (shop_order) in wp_posts
  
• Order meta (like customer info) in wp_postmeta
  
• Plugins and custom code often query these tables directly
  

HPOS storage:

• Orders, addresses, and order metadata in their own, purpose-built tables (see above)
  
• Much faster for large stores
  
• Requires updated plugins and code

4. Pre-Migration Checklist: Are You Ready?

Before you jump into HPOS migration, it’s important to make sure your store environment is fully prepared. A smooth migration depends on having the right software versions, reliable backups, and knowing your plugins and themes are compatible. Taking a few minutes to run through this checklist will help you avoid downtime, data loss, or unexpected errors. Let’s set your WooCommerce store up for success before making the switch to High-Performance Order Storage.

4.1 Confirm Your Software Versions

• WooCommerce: 8.2 or newer (HPOS enabled by default on new installs)
  
• WordPress: 6.2 or newer
  
• PHP: 7.4 or newer (PHP 8.0+ is best)

Go to WooCommerce → Status to see your versions.

4.2 Take a Backup

Before making any big updates—especially something as major as migrating to HPOS—it’s essential to back up your entire website. This means backing up both your files and your database.
A backup ensures that if anything goes wrong (like a plugin conflict, migration error, or accidental data loss), you can quickly restore your store to its previous state without losing orders or customer data.

4.3 Test on a Staging Site First

Never make big changes—like enabling HPOS or updating dozens of plugins—on your live, customer-facing WooCommerce store.
Instead, create a staging site: a private, copy of your website where you can test upgrades, new plugins, and custom code without any risk to your customers or data.

How to set up a staging site:

• Most modern WordPress hosts (like Kinsta, SiteGround, WP Engine, Cloudways, and others) offer one-click staging. You can clone your site with a button in your hosting dashboard.
• If your host doesn’t offer staging, use a plugin such as WP Staging to create a safe test environment.
• Once you have a staging site, perform your HPOS migration there first. Thoroughly test all your store’s critical functions—checkout, orders, payment gateways, reports, and any custom workflows.
• Only migrate your real (live) store after you’re sure everything works perfectly in staging.

Pro tip:
Staging is also great for training your team or testing plugin updates—make it a habit for all major changes!

4.4 Check Plugin & Theme Compatibility

You can review your store’s HPOS compatibility settings by going to WooCommerce → Settings → Advanced → Features → Order data storage. Here, you’ll see which order storage system is active and whether your plugins have officially declared HPOS compatibility using OrderUtil::declare_compatibility().

But keep in mind:

• This tool only checks if a plugin or theme has “declared” compatibility. It does not scan every line of code. If a plugin claims HPOS support but still uses outdated order queries or unsupported methods, WooCommerce won’t catch those issues automatically.
• It does not review your custom or child theme code. If your theme (or a custom plugin) includes code that interacts with order data using direct database queries or functions like get_post_meta() on orders, you need to check and update these yourself.
• Manual review is essential for all custom development. Don’t assume a “compatible” label covers every edge case. If you’ve built or customized any WooCommerce features that read or write order data, review them to ensure they use WooCommerce’s official CRUD methods.

Bottom line:
WooCommerce’s compatibility setting is a helpful indicator, but not a complete safety check. Always review your custom plugins and theme files before migrating to HPOS to avoid issues after the switch.

4.5 Plugin & Theme Compatibility Tips

HPOS changes how order data is stored and accessed. Any extension or custom code that reads or writes order data must be HPOS-ready.

• Most major WooCommerce plugins are HPOS compatible—but check!
  
• Custom code must use WooCommerce CRUD functions (wc_get_order(), $order->get_meta(), etc.) instead of raw SQL or get_post_meta().
  
• Developers declare compatibility using OrderUtil::declare_compatibility().
  

If a plugin isn’t compatible, don’t migrate yet—wait for an update or consider replacing it.

 5 Refactoring Custom Code: A Real-World Example

If you’ve run your WooCommerce store for a while, there’s a good chance you—or a developer—have added custom features that work with orders. This could include things like:

• Adding extra columns to the Orders admin screen
• Custom order exports or reports
• Automations or workflows that trigger on order data
• Special emails or notifications based on order details

Why is this important?
Many customizations made for the old (legacy) order storage system won’t work with HPOS. That’s because HPOS uses new database tables and different ways to access order data.

What are we going to do in this step?
We’re going to:

• Identify the types of custom code most affected by the HPOS switch (especially anything that reads or writes order data directly)
• Show exactly how to spot “legacy” code patterns (like direct SQL or get_post_meta())
• Provide side-by-side examples: first, how a feature was typically coded before HPOS, and then how you need to update it for HPOS compatibility

This isn’t a full programming tutorial, but a clear demonstration of the most common change you—or your developer—may need to make. If you have extra columns in your orders list, custom order exports, or workflows tied to order meta, you’ll see what to look for and how to update it.te.

Legacy Example: Adding a “Billing Country” Column

if ( class_exists( OrderUtil::class ) && OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // Use HPOS-specific admin hooks.
    add_filter( 'manage_woocommerce_page_wc-orders_columns', function( $cols ) {
        $cols['billing_country'] = __( 'Billing Country', 'text-domain' );
        return $cols;
    });

    add_action( 'manage_woocommerce_page_wc-orders_custom_column', function( $column, $post_id ) {
        if ( 'billing_country' === $column ) {
            $order = wc_get_order( $post_id );
            if ( $order ) {
                $cc = $order->get_billing_country();
                $countries = WC()->countries->get_countries();
                echo $countries[ $cc ] ?? esc_html( $cc );
            }
        }
    }, 10, 2 );
}

if ( class_exists( OrderUtil::class ) && OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // Use HPOS-specific admin hooks.
    add_filter( 'manage_woocommerce_page_wc-orders_columns', function( $cols ) {
        $cols['billing_country'] = __( 'Billing Country', 'text-domain' );
        return $cols;
    });

    add_action( 'manage_woocommerce_page_wc-orders_custom_column', function( $column, $post_id ) {
        if ( 'billing_country' === $column ) {
            $order = wc_get_order( $post_id );
            if ( $order ) {
                $cc = $order->get_billing_country();
                $countries = WC()->countries->get_countries();
                echo $countries[ $cc ] ?? esc_html( $cc );
            }
        }
    }, 10, 2 );
}

Problem: This will not work in HPOS-only mode! get_post_meta() doesn’t work with the new order tables.

HPOS-Compatible Example

use Automattic\WooCommerce\Utilities\OrderUtil;

if ( class_exists( OrderUtil::class ) && OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // Use HPOS-specific admin hooks.
    add_filter( 'manage_woocommerce_page_wc-orders_columns', function( $cols ) {
        $cols['billing_country'] = __( 'Billing Country', 'text-domain' );
        return $cols;
    });

    add_action( 'manage_woocommerce_page_wc-orders_custom_column', function( $column, $post_id ) {
        if ( 'billing_country' === $column ) {
            $order = wc_get_order( $post_id );
            if ( $order ) {
                $cc = $order->get_billing_country();
                $countries = WC()->countries->get_countries();
                echo $countries[ $cc ] ?? esc_html( $cc );
            }
        }
    }, 10, 2 );
}

use Automattic\WooCommerce\Utilities\OrderUtil;

if ( class_exists( OrderUtil::class ) && OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // Use HPOS-specific admin hooks.
    add_filter( 'manage_woocommerce_page_wc-orders_columns', function( $cols ) {
        $cols['billing_country'] = __( 'Billing Country', 'text-domain' );
        return $cols;
    });

    add_action( 'manage_woocommerce_page_wc-orders_custom_column', function( $column, $post_id ) {
        if ( 'billing_country' === $column ) {
            $order = wc_get_order( $post_id );
            if ( $order ) {
                $cc = $order->get_billing_country();
                $countries = WC()->countries->get_countries();
                echo $countries[ $cc ] ?? esc_html( $cc );
            }
        }
    }, 10, 2 );
}

Why is this better?

• Uses HPOS admin hooks, which only work when HPOS is enabled
  
• Fetches order data using the WooCommerce API, not direct meta queries
  

Summary Table: Code Changes for HPOS

6. How to Enable  High-Performance Order Storag in WooCommerce

Before enabling HPOS, it’s important to check that your current theme, plugins, and any custom code are fully compatible. HPOS changes how WooCommerce stores order data, so taking this step ensures everything will keep working smoothly.

Once you’ve reviewed your setup and feel confident that everything is compatible, follow these steps:

1. Select Compatibility Mode:

• Go to WooCommerce → Settings → Advanced → Features → Order data storage.
• In the WooCommerce HPOS settings, select Compatibility mode.
• This syncs orders to both the old (posts) and new (custom tables) systems so you can test without risk.

2. Save Changes:

• Click Save changes to start the syncing process in the background.
• For large stores, this may take a while, but you can use your site as normal.

3. Wait for Sync to Finish:

• Wait until WooCommerce notifies you that syncing is complete.

4. Switch to High-Performance Order Storage:

• Go back to HPOS settings and select High-Performance Order Storage (recommended).
• Click Save changes to fully enable HPOS.

5. Test Your Store:

• Thoroughly check your store—place test orders, review order management, and confirm all key features (and plugins) work as expected.

6. Disable Compatibility Mode:

• If everything works perfectly with HPOS enabled, return to the HPOS settings.
• Uncheck the Enable compatibility mode option, so only the new order storage is used.
• Click Save changes.

7. Final Confirmation:

• Do a final round of testing to ensure your website works as expected without compatibility mode enabled.
• This helps confirm your site is fully compatible with HPOS.

7. Testing After Migration

Don’t skip this!

• Place a test order.
  
• Make sure the order appears in the admin and all order data looks correct.
  
• Try order refunds, status changes, exports, and anything your plugins or custom code affect.
  
• Review the WooCommerce logs (WooCommerce → Status → Logs) for new errors.
• When you are sure everything is working in stating site then you can apply it to the live site.
  

Make sure new orders are shown in the new HPOS tables (wp_wc_orders, etc.).

8. Rolling Back or Troubleshooting

If you used Compatibility Mode:

• You can switch HPOS off and go back to legacy storage if you find issues.
  

If you used HPOS Only:

• It’s much harder to go back—so don’t switch until you’re sure everything works!
  

Always keep your backups until you’re 100% confident.

9. Conclusion & Further Resources

Migrating to HPOS is a major step toward WooCommerce store performance and reliability. Take your time, follow these best practices, and test everything thoroughly.
With the right prep, HPOS will keep your store fast, future-ready, and easier to manage as you grow.

Useful Links:

• Official WooCommerce HPOS Documentation
  
• HPOS Developer Recipe Guide
  

Need expert help with HPOS migration or WooCommerce development? Contact our team at CoderPlus!

FAQ