A custom reference appearing on a WooCommerce order does not prove the Orders search box knows how to search it. After an HPOS change, check the stored value, the query path and the admin search integration separately. Do not duplicate orders or edit database tables to make a search result appear.
Start with a known order
Use a synthetic staging order with a unique reference such as DEMO-REF-104. Record its order ID and the extension or custom code that creates the field. Verify whether the value is order metadata, a built-in order property, line-item metadata or an external-system field.
Those locations require different queries. A label shown on an admin screen may be calculated from another service rather than stored under the meta key you expect.
Confirm the active storage and field contract
Check whether HPOS is actually the authoritative store, not merely whether synchronization is enabled. Have the integration owner read the value through the WooCommerce order object.
WooCommerce recommends its order-query APIs instead of direct posts-table assumptions. Its current documentation notes that meta_query support in wc_get_orders requires HPOS. Do not assume a snippet written for one storage mode supports both.
Storage: Correct authoritative mode. Metadata: Exact key confirmed. Staff role: Can find intended order. Privacy: No broad private-field search. Explanatory checklist, not a customer test result.
Test data access before the search box
For developers, this bounded read-only example illustrates an exact metadata lookup on an HPOS staging store. Replace the fictional key with the documented key and run only in an authorized WordPress environment:
$ids = wc_get_orders( array(
'limit' => 10,
'return' => 'ids',
'meta_query' => array(
array(
'key' => 'demo_external_reference',
'value' => 'DEMO-REF-104',
'compare' => '=',
),
),
) );
This does not modify orders or register a field with the admin search UI. Avoid printing complete order objects or customer details into shared logs.
If the known order is absent, inspect the exact key, value, storage mode and status filters. If it is returned, the data exists and the next question is how the admin search invokes its query.
Repair the owning integration
Ask the extension vendor whether its custom-search hook supports the installed WooCommerce version and HPOS Orders screen. A legacy hook connected to the posts list may not affect the new screen.
Do not copy every private meta key into a broad searchable list. Decide which references staff need, which roles may use them and whether the lookup should be exact or partial. Test common references and no-match input with realistic order volume.
The HPOS compatibility checklist covers the wider migration. This task is complete only when the intended staff role can find the known order through the real UI without exposing unrelated private fields. HandL WP can repair an order lookup from the field contract and a sanitized example.
References reviewed October 13, 2026. Examples are explanatory, not customer test results.