What Search Matches
Search in v2.0 matches the same fields on the till and on the server, matches order line items and the shipping recipient, and finds phone numbers however they were typed. The field list is fixed (there is no setting); developers extend it with one filter, and the till picks up the added fields too.
How a search is matched
- The text you type is split on whitespace into terms. Every term must appear somewhere in the record, in any order and across fields:
shirt lovelacefinds an order for Ada Lovelace that contains a shirt. - A term matches as a substring, anywhere in a field:
saippuafindsKuorintasaippua;jofindsBjorn. There is no minimum length. - Matching ignores case and accents:
cremefindsCrème. - Punctuation inside a term is part of it (
0.4,K-2,3/4), while punctuation wrapping a term is not ((shirt)searches forshirt). A term is never split on punctuation, so a full email address is one term. - Phone numbers also match by their digits. A term made of digits (with or without
+ - ( ) .and spaces) is compared with the stored number's digits, so0412finds(04) 1234 5678and412345finds+61 412-345-678. Country codes and trunk prefixes are not normalised:0412does not find+61 412 345 678.
Results on the till come from the records already on the device; the server searches the same fields, so the rows that arrive from the server for a term are the rows the till would have found with them.
What each screen searches
| Screen | Fields |
|---|---|
| Products | Name, SKU, barcode |
| Variations | SKU, barcode, and the parent product's name |
| Orders | Order number; billing first name, last name, company, email, phone; shipping first name, last name, company, phone; each line item's name and SKU |
| Customers | First name, last name, email, username; billing first name, last name, company, email, phone; shipping first name, last name, company, phone; tax IDs |
| Categories, tags, brands | Name |
| Coupons | Code, description |
Line items match the product name as it was sold — an order is still found after the product is renamed — and the product's current SKU. The shipping recipient is searched because a click-and-collect or delivery order is often looked up by the person collecting it, who is not the person who paid.
Order numbers from sequential-order-number plugins (_order_number, _order_number_formatted) are searched on the server alongside the WooCommerce order id.
Why there is no search-fields setting
Searching more fields costs nothing noticeable, and a term only matches a phone or a company name when that is what the cashier typed, so there is nothing to gain from turning fields off. A setting would also have to reach every till and the server together before the two agreed. The field list above is therefore fixed, and the one case that needs more — a store's own custom field — is a developer filter.
Adding a custom field
wcpos_search_fields receives a collection's search declaration and the collection slug. Before WCPOS 2.0 this filter was named woocommerce_pos_search_fields; that name still works but is deprecated since 2.0 and is removed in 2.2 at the earliest (see Hook naming). To make a customer findable by a loyalty number stored in user meta:
add_filter( 'wcpos_search_fields', function ( array $search, string $collection ) {
if ( 'customers' === $collection ) {
$search['meta'][] = 'loyalty_number';
}
return $search;
}, 10, 2 );
For orders, append to $search['posts']['meta']; the key is searched in post meta on legacy storage and in the order meta table under HPOS.
An added meta key is searched on both sides: the server matches it in its query, and the till folds it into its local search as well, because wcpos/v2/site publishes the keys a store added and the till stores them when it connects. Two limits follow from how WooCommerce exposes meta:
- Only keys without a leading underscore reach the till. WooCommerce treats
_privatemeta as protected and leaves it out of the RESTmeta_datathe till syncs, so such a key is searched on the server only. - A key added after a till connected reaches that till the next time it connects, with the rest of the site payload.
Store the value the way the cashier will type it, or in a form the digits rule covers: the filter adds the field to the match list, it does not change how a term is matched.