HPOS and WooCommerce order search: what changed

What is HPOS, briefly?

High-Performance Order Storage is how WooCommerce stores orders now. Before it, an order was a WordPress post, and everything about it (addresses, totals, custom fields) sat in the shared posts and post meta tables alongside your pages and products.

HPOS moves orders into four tables of their own: orders, order addresses, operational data and order meta. WooCommerce’s HPOS documentation says it has been on by default for new stores since WooCommerce 8.2, released in October 2023. Older stores switch under WooCommerce → Settings → Advanced → Features.

What changed about searching orders?

Three things, and only one is visible.

1. A dropdown appeared. Next to the search box on WooCommerce → Orders, HPOS stores get a selector: All, Order ID, Customer email address, Customers and Products. It narrows the search to one kind of match.
2. The query underneath is new. Search now runs against the order tables and the address table, not post meta. Our guide on searching orders by SKU, note or custom field lists exactly what it covers. We read the WooCommerce source (September 2026): “All” covers the order ID, transaction ID, billing email, the customer and address fields, and product names.
3. The old customisation hook no longer applies. This is the one that catches stores out, and it’s worth its own section.

Why did a search that used to work stop finding orders?

On post-based storage, developers extended order search with the woocommerce_shop_order_search_fields filter. It’s a list of meta keys to search, and adding a key (say, a PO number or a gift recipient) made that field searchable. Plenty of stores had a snippet like that in a theme or a small plugin, often added years ago by someone who has since moved on.

That filter belongs to the post-based data store. The HPOS search doesn’t read it. So a store switches to HPOS, everything else carries on, and a few weeks later someone notices that searching a PO number returns nothing. Nothing errors. The field is simply no longer part of the search.

How do you check whether your store is affected?

1. Confirm which storage you’re on under WooCommerce → Settings → Advanced → Features.
2. Search your code for woocommerce_shop_order_search_fields: the active theme, child theme, any code snippets plugin and small custom plugins. A developer can do this in minutes.
3. If you find it, list the meta keys it adds. Those are the searches that stopped working when you switched.
4. Test each one: take a recent order where you know the value, and search for it.

Also ask the people who use the Orders screen. “Is there anything you used to be able to search for and can’t now?” often finds the problem faster than the code does.

How do you add a custom field to HPOS search?

WooCommerce 8.9 added two filters for this. woocommerce_hpos_admin_search_filters adds (or removes) an option in the dropdown. woocommerce_hpos_generate_where_for_search_filter supplies the query that option runs.

It’s more work than the old one-line filter, because you write the query yourself, including the join to the order meta table. And the new option only runs when someone picks it in the dropdown. It doesn’t join the “All” search, so staff have to know to choose it.

Why do custom order reports return nothing after the switch?

Because they query posts, and orders aren’t posts any more. Code that fetches orders with WP_Query or get_posts() using the shop_order post type finds nothing on an HPOS store, or finds stale copies if compatibility mode is keeping the old tables in sync. The same goes for raw SQL against the post meta table.

The fix is to fetch orders through WooCommerce instead: wc_get_orders() for lists and wc_get_order() for one order. Both work on either storage type, so code written that way survives the switch in both directions.

Can you switch back if something breaks?

Yes, as long as compatibility mode was on. With synchronisation running, both sets of tables hold the same orders, so switching the authoritative storage back to posts under WooCommerce → Settings → Advanced → Features is a setting change, not a migration. Leave compatibility mode on for a while after switching for exactly this reason, then turn it off once you’re confident, since keeping two copies in sync has a cost on busy stores.

Is order search faster with HPOS?

For most lookups, yes, because orders no longer share tables with everything else on the site. The exception is the “All” option on very large stores, which runs every lookup at once. An issue on WooCommerce’s tracker describes it as expensive on stores with lots of orders. If you know what kind of value you’re searching for, choosing it in the dropdown first is quicker.

What is compatibility mode, and does it affect search?

Compatibility mode keeps a copy of order data in the old post tables, synchronised with the new ones. It exists so plugins that still read orders the old way keep working while you switch.

It doesn’t bring the old search back. With HPOS as the authoritative storage, the Orders screen searches the new tables, whatever is synchronised underneath. Treat compatibility mode as a bridge for other plugins, not as a way to keep old search customisations alive.

What’s the alternative to writing search code?

An order search index that works the same on both storage types. WC Order Search Pro builds its index by reading each order through WooCommerce’s own order functions, not the database tables directly. It declares HPOS compatibility, and it doesn’t rely on the old woocommerce_shop_order_search_fields filter, so it keeps working when a store switches.

Its index covers SKUs, coupon codes, order notes and any custom field you tick under WooCommerce → Order Search Pro → Searchable Fields, as well as the usual customer and address details. One search covers all of them, and a Matched in column shows which field matched.

If you’ve just switched to HPOS and lost a search, that’s the quickest fix: tick the meta key your old snippet used, then run Rebuild search index on the General tab so older orders are included.

What to check before switching an older store to HPOS

• Every plugin that touches orders declares HPOS compatibility. WooCommerce lists incompatible ones on the Features screen.
• Custom search code is found and rewritten, or replaced with an index.
• Reports and exports built on direct database queries against post meta are rewritten, because those tables stop being the source.
• A staging copy gets switched first, and the people who use the Orders screen try their usual searches there.

The last point matters most. The problems HPOS causes are rarely errors. They’re searches that return nothing, and only the people who search every day will notice.