Search section (admin)¶
The Search section in the admin gathers everything about how shoppers find things: whether search is healthy, rebuilding its index, what people search for, the synonyms that help them, and a place to test a search. It is open to merchandisers, admins and super admins.
| Page | Address | What it's for |
|---|---|---|
| Overview | /admin/search |
Health, rebuild controls, today's activity |
| Analytics | /admin/search/analytics |
Top searches, searches that found nothing, and what searches lead to (clicks, baskets, orders) |
| Product engagement | /admin/search/engagement |
How each product does in each category and search: shown, opened, added, bought, and what it earns per slot |
| Ranking goals | /admin/search/goals |
What ranking by what sells optimises, for the shop, per category and for set dates |
| Learned boosts | /admin/search/boosts |
Products doing clearly better in one category or search, suggested for a lift there |
| Experiments | /admin/search/experiments |
Split visitors between two ranking set-ups and compare what each earns per visitor |
| Synonyms | /admin/search/synonyms |
Words shoppers use interchangeably |
| Search terms | /admin/search/terms |
Extra words that find one particular product |
| Rules and ranking | /admin/search/ranking |
Pin, boost or bury products for a search term, send a search to a page, or show a banner |
| Test a search | /admin/search/test |
See what a search returns, and why a product is missing |
| Settings | /admin/settings/search |
The search switch, which products search finds, engine details, content search, tracking, filters |
Every page has the same section menu: a column beside the page on a desktop, a row of chips you can swipe along on a phone.
Switching search on¶
Search is off for every site until you switch it on. In Search settings (/admin/settings/search) turn on Use Search. Saving it indexes the site straight away (products, and pages if Enable Content Search is on too), and from then on shoppers get a search box on every theme, the search results page and as-you-type suggestions.
With Use Search off, the site has no search box, its search page answers "not found", and its search index is removed. Category pages (/c/...) keep working: if the site has a merchandising tree, its products stay indexed for those pages only.
Two settings decide which products search can find:
- Products Search Can Find (
search-product-scope):- IN_COLLECTION (the default): products in at least one enabled collection. A product you only link to directly (a raffle or "200 club" entry, say) stays out of search.
- MERCH_TREE: products in at least one visible category of your primary merchandising tree.
- ALL: every enabled product.
- Search Only These Collections (
search-root-collections, optional): pick collections, and search only finds products in them or in a collection below them.
Changing either reindexes the site. Disabling or enabling a collection, or changing its parents, updates search by itself. On a site with a merchandising tree, a product shown in a category can still be found by search even outside these settings, because category pages and search share one index.
Overview¶
Health cards show:
- Search engine: Healthy, Unreachable, or Not set up. If search isn't set up the page says so and links to Search settings; if the engine isn't answering it shows the error. The rest of the page still works. If Use Search is off, a warning says search is switched off for the site (and whether products stay indexed for its category pages), with a link to turn it on.
- Products indexed and Pages indexed: how many documents the engine holds, and which products search finds. Pages show Off when content search, or search itself, is off.
- Last reindex: the most recent rebuild, its outcome and who asked.
- Searches today, when search tracking is on.
Rebuild the search index builds a fresh index from your catalogue and swaps it in with no downtime. Shoppers keep using the old index until the new one is ready, and if the rebuild fails the old one stays live. Pick:
- Rebuild everything: products and content.
- Products only.
- Content only: needs content search switched on.
The buttons are disabled, with a note saying why, while search is switched off for the site (unless its category pages keep a product index, when a rebuild refreshes just that).
You're asked to confirm, and the page then follows the rebuild (waiting, running, done or failed, with the document count). You can leave the page; come back and it picks the run up again. If someone has already started a rebuild in the last 30 minutes, your click joins it instead of starting a second. A rebuild that finds nothing to do (for example, content search or search is off for the shop) shows as failed, with a reason starting "Skipped:", rather than as done with no documents.
You rarely need this. Changes to products and pages are indexed as you save, and a nightly job reconciles any drift. Rebuild after a large import, after changing facets on a merchandising tree, or when search looks out of date.
Shoppers can also search by code: a product's SKU, a variant's SKU or a barcode finds the product, exactly as typed apart from punctuation (no typos allowed, so a wrong part number doesn't show its neighbour). A variant's code opens the product with that variant chosen. See Searching by SKU or barcode.
Top searches and Searches that found nothing cover the last 7 days, with links to the full reports, plus quick links to Synonyms, Test a search, Merchandising trees and Search settings.
Analytics¶
Choose the last 7, 30 or 90 days (90 is how long search terms are kept). You get the total searches and how many found nothing and, with click tracking on, how many searches led to a product being opened (Clicked), to a product being added to a basket (Added to basket) and to an order (Ordered, with the revenue those products brought in). Then:
- Searches that found nothing: each has Add synonym (opens the Synonyms page with the word filled in), Add to a product (opens Search terms with the word filled in) and Test (opens Test a search with it filled in).
- Searched often, rarely clicked: searches made at least 10 times that find products, but under 10% of which lead to a product being opened. The results probably aren't what shoppers meant. Each has Add synonym, Add rule (opens Rules and ranking with a rule for the word started) and Test.
- What searches lead to: for the most common searches, the share that led to a click, an add to basket and an order, and the revenue. Rarely clicked searches are flagged here too.
- Top searches: the most common searches and how many results the latest one found.
A click is the first product a shopper opens from a page of results. An add to basket counts when the product goes in the basket within 30 minutes of the search, and an order when the basket is ordered within a day. Rates are per search, so you can compare searches of any size. Clicks and sales only start counting once click tracking is on, so searches from before then look unclicked.
If search term tracking is off, the page explains and links to Search settings; if only Record Search Clicks and Sales is off, the page shows searches alone and says so. Only the search words and daily counts are kept, never who searched or from where. On a phone each table row becomes a card.
Product engagement¶
Pick a listing (Every listing, a category, or one of the most common searches) and the last 7, 30 or 90 days. You get its impressions (products shown), the share opened (Clicked), added to a basket and ordered once opened, the revenue, and the revenue per 1,000 impressions: what a place in the listing earned. Then:
- Viewed a lot, rarely bought: products opened at least 20 times but bought less than half as often as the listing's average. Check the price, stock and sizes, the photos and description, or whether it belongs there.
- Sells well, rarely shown: products bought at least half as often again as the average but shown less than most sellers. Candidates to boost in Rules and ranking or the category's ranking.
- Clicks by position: how much more the top of the listing is clicked than further down.
- Products: each product's impressions, average position, click-through, views, add and order rates, revenue and revenue per 1,000 impressions. Choose a column heading to order by it.
- Margin (admins and finance only, once products have cost prices): the margin rate and estimated margin of the listing and each product, margin per 1,000 impressions, and the share of revenue whose cost was known.
The Ranking by what sells card says whether the shop qualifies for listings ranked by how shoppers respond to each product: it's part of Enterprise and needs enough orders (1,000 in 30 days by default) for the numbers to be reliable.
Recording needs an Enterprise subscription and Record Product Engagement on in Search settings. Only daily totals per product and listing are kept, for 90 days, never who looked. Bots and the phone filter sheet's count previews aren't counted.
Ranking goals¶
When ranking by what sells is in use (an Enterprise shop with enough orders, Rank by What Sells on in Search settings), products that match equally well under Featured are ordered by how shoppers respond to them, for a goal: Units sold, Conversion (orders), Revenue or Margin, each per time a product is shown. Margin is the same as revenue until products have cost prices. The top card says whether it's in use and, if not, why (for example "412 orders in 30 days, 1000 needed"), and when the scores were last worked out (every night).
- Shop default: the goal everywhere nothing else applies, searches included.
- Schedules: a goal for set dates, for the whole shop or chosen categories and everything below them, such as units sold in the January sale. While one runs it beats a category's own goal; one for categories beats one for the whole shop. Running and finished schedules are marked.
- Categories: give a category its own goal (the ones below it follow), or Inherit. The Today column shows the goal applying to each category now, and why.
Changes apply within a minute. Product engagement shows the goal for the listing you choose and each product's score for it (1,000 is average, 1,250 a product not shown enough to judge yet).
Learned boosts¶
Each night, products doing clearly better in one category or search than its average (for that listing's goal) and not already near its top are suggested for a boost there. How they're decided is the Learned Boosts setting in Search settings: review (each waits here for you), AI-checked (the shop's AI decides and says why; you can undo it, or decide yourself while it waits), autopilot (applied at once) or off.
- Waiting for a decision: the listing, the product, its score (1,000 is the listing's average), and the evidence: orders, impressions and where it's usually shown. Accept or Reject (with an optional reason).
- Applied: who decided, why, and until when. Remove takes it out.
- Recently decided against, withdrawn or lapsed, with why.
A learned boost sits after your own boosts and ahead of everything else. It never touches a product you pinned, boosted or buried in that listing, a listing has at most a few (5 by default), each lapses after 14 days unless the nightly run finds it still earns its place, and a rejected product isn't suggested in that listing again for 30 days. Admins and finance also see each product's margin compared with the shop's.
Experiments¶
Search > Experiments tests a ranking change on part of your visitors before you roll it out: two ways of ranking the Featured order (for example the shop as it is, against ranking for margin) share the visitors you choose, and each arm's conversion and revenue per visitor are compared with a 95% range. Create a draft (name, what each arm does, the share of visitors, planned visitors per arm), start it, and open it for the results: a plain-English verdict, the two arms side by side, a day-by-day chart, and warnings when it's too early to call or the split looks wrong. Only one runs at a time. It needs the same plan as ranking by what sells and the Search Experiments setting. See Search experiments.
Synonyms¶
Add, edit and delete synonyms, accept or reject AI suggestions, ask AI to suggest more (Suggest with AI), and Resync the saved synonyms into search if some show a warning icon. Details of the two types and the AI review are in Search Synonyms. The page's list of searches that found nothing links straight to Test a search and offers Add synonym for each.
The old "Explain a search" box on this page now lives on its own page, Test a search.
Search terms¶
A product's search terms are extra words shoppers use for it that aren't in its name or description, like "coach bolt" for hex-head bolts or "decking screws" for a pack of wood screws. Search matches them like the name (stemmed, so "bolts" finds "coach bolt"), but shoppers never see them. Use a synonym instead when the word means a whole kind of thing you sell ("wellies" for every welly boot); use a search term when it should find one product.
The page has three parts:
- Add a search term to a product: type the term, then find the product by name or SKU and press Add. The term is added to the product's own (a duplicate is skipped).
- Products with search terms: every product that has some, by name, with its terms as chips and a filter by name, SKU or term. Edit turns a row's terms into a comma-separated box; save an empty box to remove them all. The product name opens the product editor.
- Searches that found nothing in the last 30 days: Add to a product fills the term in above, ready to pick the product.
The same field is on the product editor's Details tab, in the Shop search card, as a comma-separated list.
The rules are the same everywhere (the editor, this page and the MCP tools): terms are trimmed, duplicates are dropped ignoring case (the first spelling is kept), a term can't contain a comma and is at most 50 characters, and a product can have at most 50. A list that breaks a rule is refused with the reason; on the product editor the rest of the product still saves and the old terms stay. Saving reindexes the product like any other edit, so the change reaches search within seconds.
Rules and ranking¶
A rule applies when a shopper searches exactly its term (case and spacing ignored). It can pin, boost or bury products by SKU, send the search to a page on your site, and show a banner above the results. Add rule opens a form; each row has Edit and a delete button that says what will change before it deletes. A category's own order is set on the node in Merchandising trees. The full behaviour is in Search Rules: Pins, Redirects, Banners.
Test a search¶
Type what a shopper would. You see:
- how many products are found and the first ten, in the order the shop shows them;
- the words the search split it into, the live synonyms that applied and any suggested ones that would apply once accepted;
- when you also give a product's SKU, SEO name or id, why that product is or isn't found: whether it is in the catalogue, enabled and indexed, where it ranks, and which searchable fields contain which of your words;
- what to do next.
The search and product are in the address (?q=wellies&product=SKU-1), so you can send a result to a colleague.
Permissions and data¶
All Search pages and the /admin/search/rest endpoints require the MERCHANDISER, ADMIN or SUPERADMIN role and act on the site you're signed in to. Rebuild history is kept for 30 days. For how rebuilds work internally, see Search Architecture.
For developers¶
| Endpoint | Purpose |
|---|---|
GET /admin/search/rest/status |
Index status and latest run |
POST /admin/search/rest/reindex with {"scope":"ALL"}, "PRODUCTS" or "CONTENT" |
Start (or join) a rebuild; 202 new, 200 joined, 409 if search or content search isn't set up |
GET /admin/search/rest/reindex/{runId} |
Poll one run; 404 if it isn't this site's |
GET /admin/search/terms/rest/products?q= |
Products whose name, SEO name or SKU contains q, with their search terms (up to 10) |
PUT /admin/search/terms/rest/{productId} with {"terms":[...]} |
Replace a product's search terms ([] clears); 400 with the reason if a term is invalid, 404 if the product isn't this site's |
POST /admin/search/terms/rest/{productId}/add with {"terms":[...]} |
Add to a product's search terms |
POST /admin/merchandising/rest/reindex |
Legacy endpoint, same as scope ALL |
These are same-origin admin endpoints over the admin session, not part of the public REST API.