Admin controls
Before writing code, check whether the admin already does it. Most requests to change what search returns can be handled there.
If you are implementing the storefront, share this list with the merchant. It is what saves you a code change the next time they ask for "this product higher up".
Synonyms (Pro)
For changes of wording.
Tシャツ ⇄ カットソー ⇄ ティーシャツGroups are bidirectional: any term in a group reaches the products of every other term.
Do not register spelling variants. Hiragana, katakana, kanji, fullwidth/halfwidth and romaji input are absorbed automatically (see How search works). Register only words that mean the same thing but share no characters.
The limit is 1,000 groups of up to 20 terms.
Search-term redirects (Pro)
Send specific terms to a page instead of to results.
"送料" (shipping) → /pages/shipping
"ギフト包装" (gift wrapping) → /pages/gift-wrappingWhen one matches, the response carries redirect_url. Your code should navigate rather than render results when that field is set (see §6 of the specification).
Boosts and pins (Pro)
- Boost — lift a specific product's rank
- Per-keyword display rules — "for this search term, show this product first"
- Field weighting — how much a title match counts against a description match
This is the supported way to control ordering. We do not publish the score, so re-sorting on your side is not recommended — its basis changes with every search-quality improvement.
Filterable metafields (Pro)
Choose, per metafield, whether it is searched and whether it can be filtered on. Text and list types, up to ten.
Only metafields enabled here work with filter_metafield. A key that is not enabled is ignored rather than rejected (see the FAQ).
The display label is set here too, and arrives as facets.metafields[].label.
Out-of-stock handling
A store-wide choice.
| Setting | Behaviour |
|---|---|
| Show last (recommended) | In-stock products are ordered first (the default) |
| No distinction | Stock is not reflected in the ordering |
| Hide | Out-of-stock products do not appear at all |
A store that has never touched this setting is on Show last (recommended). Out-of-stock products sinking is the default, not a fault. It applies to keyword searches and to collection pages (q=*) alike: they sink in the relevance order (and among equal ratings in the rating order), while price and newest orders ignore stock.
On a store set to Hide, filter_available=false (out-of-stock only) returns nothing. A filter must not dig out what the merchant decided to hide.
Excluded tags
Products carrying one of these tags do not appear in search at all — useful for trade-only or housekeeping products you would rather shoppers did not find.
- A whole tag is matched: excluding
業務用leaves a product tagged業務用に不向きalone. Case is ignored. - Keyword searches, collection pages (
q=*), the filter counts, the zero-result strip and the recommended products in the header and on the results page all drop them alike, so no filter row leads to an empty page. - Blog articles and pages carry no tags and are never hidden by this.
- A change takes effect on the next search. No resync is needed.
- The products' own tags are untouched, so nothing else in the store changes.
The suggestions offered while a shopper types are built from the products' words, so a word from an excluded product can still appear. Searching for it returns none of those products.
Which content types are searched
Products, blog articles and pages can be included or excluded independently.
The zero-result page
- A strip of alternative products — chosen by hand under Settings → Search suggestions → Recommended products (Pro), or automatically from best sellers
- Candidate terms — the response's
suggestions - What other shoppers searched next — the response's
related_keywords
Next: Multilingual stores