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 100 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 | Out-of-stock products appear in results (default) |
| Demote | In-stock products are ordered first |
| Exclude | Out-of-stock products do not appear at all |
On a store set to Exclude, filter_available=false (out-of-stock only) returns nothing. A filter must not dig out what the merchant decided to hide.
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, or automatically from best sellers
- Candidate terms — the response's
suggestions - What other shoppers searched next — the response's
related_keywords
Next: Multilingual stores