Search help

The searches your theme answers with an empty page.

Search help is one of the five storefront blocks, and the narrowest one. It sits on top of your theme’s own search results and picks up the queries that normally come back empty — a barcode, a word your shoppers use where your titles use another, a misspelling, a product you stock but cannot sell today. It runs on your catalogue alone. Behind it is a resolver that tries six things in a fixed order, and this page is that order.

The six steps The two sentences What it covers

Placement

A section block on your search results template, above your own results.

You place it yourself, in Shopify’s own theme editor: open the search results template, Add block, Apps. The extension pins it to that template, so Shopify offers it on the one page that has a query to read — and anywhere else it prints a note to you in the editor while your shoppers see the page as it was.

What it does

Sits above your theme’s results and leaves every one of them exactly as your theme ranked it
Loads on the search results template only — one page out of your whole storefront
Prints its container empty and fills it after its own stylesheet has landed, so nobody watches an unstyled list appear and then shift the page under their thumb
Loads that stylesheet outside the critical path, and falls back to the plain tag when scripting is off

What it leaves alone

Your theme’s own search, and the empty state your theme shows underneath
The order, the filtering and the visibility of the results your theme found
Your theme files — it is a block you switch on, and switching it off is the whole removal
Every other page on your store: the corner bubble is the site-wide surface, this one keeps to search results

One neighbouring surface lives elsewhere on purpose. The “ask the assistant” row that appears inside your header’s type-ahead suggestion layer used to belong to this block, and because this block loads on the search results template alone, that row arrived only after a shopper had already left the layer. It moved to the site-wide chat embed, where the suggestion layer actually opens. If that row is what you came looking for, it ships with the chat bubble.

Resolution order

Six steps, in this order, and the sixth hands the page back to your theme.

This is the entire decision, and it is a walk down a list: the resolver takes the steps in turn and stops at the first one that can answer. Your shopper’s question goes through the same function whether they typed it into search or into the chat bubble — the difference is that the bubble wraps the result in a sentence a model wrote, and this block prints the result itself.

Step one

Is it a barcode?

Eight to fourteen digits, and digits alone: letters, spaces and dashes all send the query on to step two. That gets answered from a barcode index built alongside the catalogue, in a single lookup where a text search would scan. A theme reads titles and descriptions, so a shopper reading the number off the back of a bottle is the query this index exists for.

A number your catalogue carries is answered here, and any other number ends the walk at step one with the guess left unmade.

Step two

Is it a question about the shop?

Some searches ask about the shop itself. Color chart names a reference page, and so do questions about shipping, returns and how to use something. Your industry pack carries the patterns for those, and a match here ends the walk.

A product list would walk the shopper away from the thing they wanted, so the block offers to put the question to the assistant.

Step three

Does the catalogue match it as typed?

Every word has to appear somewhere in the product: its title, its series, an active ingredient, the short summary, or the handle. A product that misses one of the words drops out, because loose matching produces a list the shopper has to sift.

Accents and Turkish letters are folded before matching, so two spellings of the same word land on the same product.

Step four

Does it match after a synonym?

Reached when step three came back empty. A table in your industry pack maps the word the shopper used onto the word your titles use — mascarilla and ceras de cabello onto mask and wax, Conditoner onto the spelling you actually wrote — and the search runs again.

When that is what happened, the block says so above the results. Nobody should have to wonder whether they searched for something else.

Step five

Does it match if sold-out products count?

The last attempt in the walk. The same search runs once more with sold-out products included. If one turns up, the answer is that product named, plus alternatives from the same series and the same step of the routine.

Alternatives are drawn from your own catalogue by shared purpose, and every one of them is a product a shopper can buy today.

Step six

Nothing.

When all five have been tried, the block leaves its container empty. Your theme’s own empty state is what the shopper reads, unchanged, because a heading over an empty list reads as a broken section.

This is the step the whole order exists to avoid, and it is the only honest answer left when a word is in nobody’s catalogue.

Interface illustration, drawn from this page’s own six steps — the resolver takes them in turn and stops at the first one that can answer, so a step runs only when the one before it came back empty. The five fields carry the weighting order named below, and the dashed sixth box is your theme’s own empty state rather than anything this block prints. Nothing here is a measured figure: the recovery rate is still the placeholder further down.

Two details about step three, because they decide what a shopper sees first. A word found in the product title counts for more than the same word found in the handle, in a fixed order that is the same in every store: title, then series, then active ingredient, then summary, then handle. And when two products come out level, the cheaper one is listed first — a deliberate choice, applied the same way everywhere.

Two sentences

“Sold out” and “we don’t sell that one on this store” are different sentences.

A product can be sitting in your warehouse, fully in stock, and still belong to another sales channel — published there, absent here. Calling that sold out costs you the sale twice: once now, and once on the visit the shopper skips. So the server sends the reason along with the answer, and the block picks the sentence to match.

Three states, three answers

Out of stock: the product is named and the alternatives are offered, so the shopper keeps shopping
In stock, published to another channel: the second sentence, because the stock is there
A barcode that lands on either of those: the product is named and not linked, because the link would open a page this storefront lacks
Both sentences are yours to edit in the theme editor, and the editor field for the second one spells out which of the two states it covers

An older version of the block had one sentence for both states. It was changed after a product with tens of thousands of units in stock was described to shoppers as sold out.

When the block keeps quiet

Your theme already answered correctly — a plain query, matched as typed, everything in stock. A second list underneath would be a copy of the first, so by default the block appears only when it adds something
You would rather see it every time anyway: there is a switch for that, off to begin with
Your plan covers the other surfaces: the server answers with an empty result where an error would be, so the block stays empty and the page stays whole
Anything else went wrong: only a successful reply draws anything at all. An earlier version drew a heading over an error body, which is exactly the failure this block exists to prevent

The search request is stateless by design: it reads your catalogue, answers, and returns. The console lists unanswered conversations, because a conversation is a record the shopper opened, while a search is one read and one reply. A merchant-facing list of the searches that came back empty would be a change to what this request stores, and it is the most useful thing that change would buy.

Your pack

Two of the six steps come out of your industry pack — and one pack has neither.

Synonyms and question patterns ship as data, inside the industry pack your store is placed in during setup. That is worth knowing before you count on them, because the two packs that exist today are furnished differently, and the neutral one is the fallback.

The beauty pack, as it ships

Fifty synonym entries: Spanish words for hair care, Turkish words for hair care and make-up, and misspellings that turned up as real searches
Four question patterns: colour chart, shipping, returns, and how to use something
Entries that carry an accent are written twice, once each way, so either keyboard finds them
A longer Turkish entry also matches its own suffixed forms, because a shopper asking about their order types the inflected word

The neutral pack, as it ships

Synonyms and question patterns both ship at zero — both lists are empty
So on that pack four of the six steps carry the work, and translation, misspelling rescue and the question hand-off wait for a furnished pack
Barcode lookup, the plain catalogue match and the sold-out answer all still work, which is four of the six steps
The base rule set every pack gets covers other ground, so those two lists stay with the pack itself

And the limit that follows from all of this: the synonym table belongs to the pack, and the pack ships with the app. An entry your catalogue needs is a change we make and release, so the way to get one is to tell us which word your shoppers use where your titles use another. That request is the whole process today: you name the word, and it arrives in the pack with the next release.

Honesty

What it covers, and where it hands over.

A block that recovers empty searches is easy to oversell, because the thing it is supposed to fix is invisible until someone measures it. So here is the shape of what it does, in the same voice as the rest.

It matches words

The whole resolver runs on your catalogue and your pack, which is why a search costs what a database read costs and returns at that speed. Meaning is the chat bubble’s job: a shopper describing a problem in a full sentence is handed there.
It matches what you wrote

Every step reads the same five fields: a product’s title, its series, its ingredients, its summary and its handle. A synonym entry bridges two words for one thing, and the attribute itself has to be written on the product first.
A recovery rate from a live store

Which query shapes have a branch and a test behind them is on this page, step by step. The figure that belongs beside them is the share of empty searches that become orders, and it belongs to a store that has run the block.
One thing needs the chat embed

The assistant’s name and the hand-off for a question come from the site-wide chat embed. With that embed switched off, this block still lists products and falls back to a neutral name, while the hand-off waits for a panel to open. It says so in the theme editor, in a note you alone see.

Questions

The questions merchants actually ask about it.

How long after I change a product does search help see it?

A product update arrives from Shopify as a webhook, and all that request does is write one row into a queue — a single insert, which is what keeps your admin moving. A scheduled job works through that queue once an hour, and the server holds its copy of your catalogue for up to a minute after that. So the practical answer is: by the next hourly pass, plus that minute. We say the hour out loud because that is the number the schedule holds.

Does it really index my barcodes?

Yes, and as its own index, built at the same time as the product knowledge. The barcode branch is a direct lookup that leaves the text search untouched, which is why it is the fastest and the most exact of the six steps. It also means stock and publication are read in a second step straight afterwards — and it is that step that turns a barcode hit into a product named on the page.

Which plan includes this block?

Growth and above. On the entry plan the chat bubble is the one storefront surface, and the server holds that line as well as the theme — a flag left behind in a theme is checked against the server before the block draws. The server deliberately fails open: where it struggles to read which plan you are on, it answers. A lookup that went wrong on our side leaves a block you are paying for on the page. What the plans cost is on the pricing page.

What makes a product eligible to come back as a result?

A condition in the search itself, held below the assistant: a product has to be in stock and published to this storefront before it can come back as a result, and that same condition is applied again to the alternatives offered beside a sold-out product. The single place the condition is relaxed is step five, whose entire job is to find the sold-out product so it can be named on the page.

Why does it sometimes show a result my theme also showed?

Because you turned on the switch that shows it on every search. With that switch off — which is how it arrives — the block draws itself when the answer came from a barcode, a synonym, or a sold-out product. A plain search your theme already got right leaves this block quiet on purpose, since the alternative is showing the same products twice and asking the shopper to work out why.

What happens to a search that is just gibberish?

All six steps run and all six come up short, at the cost of six catalogue reads, and then the block leaves its container empty. A query longer than two hundred characters is cut to that length first, and a query made only of spaces is answered at step six directly. Every branch in the resolver returns a product your own catalogue carries.

Everything on this page was read out of the code that ships: the order of the steps, the two sentences for two kinds of absence, the counts in each industry pack, and the four limits named above. Where this page and your own storefront disagree, the bug is on this page and we would like to hear about it. You can see the other four surfaces on where Refik answers, and what it reads before it answers anything under what it reads.