Merchandising

Pin specific items to the top of shopper search results when their query matches a phrase you author. Useful for promoting seasonal picks, sale items, or anything you want to lead with when shoppers ask for the kind of thing they describe.

What a rule is

A merchandising rule has three parts.

Phrase: A few words describing what shoppers might be looking for, written the way a real shopper would write. "Dark navy chinos." "Gift ideas for dads." "Sale picks." The match isn't literal; we match shopper searches that mean the same thing as your phrase, not just identical wording.
Pinned items: A small list of items you want at the top of the result set when this rule fires.
Selectivity: A dial that decides whether close-but-not-quite searches still fire your rule, or whether only near-identical intent does.

Plus a simple on / off toggle. Off means the rule doesn't fire on any shopper traffic, useful while you're authoring it, or while you pause a seasonal rule between runs.

Creating a rule

From the Merchandising page, click New rule. The editor opens with a blank rule, defaulted to off so half-authored work never leaks to shoppers. Fill in:

Rule name: Internal label for you and your team. Shoppers never see this.
Phrase: A short, natural-sounding phrase. The match looks for searches with the same intent, so write the way a shopper would write, not a category name or an internal label.
Selectivity: How specific the match needs to be. See Selectivity below.
Pin cap: A cap on how many of your pinned items actually slot into the top of search results when the rule fires. Pinning more than this lets you rotate without re-authoring.
Pinned items: Use Add items to open the picker and find items by name, by ID, or by describing them. The order you choose is the order they'll surface.

Flip the toggle on at the top of the page when you're ready, then save.

Selectivity

Selectivity is the dial that decides what counts as a match. A 1-10 slider you tune per rule.

1–3

Loose

Fires easily, even on loosely related searches. Useful for broad coverage.

4–6

Balanced

Fires on clearly related searches. The default zone for most rules.

7–8

Tight

Fires only when the search is a close match to your phrase. Recommended for new rules.

9–10

Strict

Fires only when the search is nearly identical in intent.

The same dial appears on Search Lab as a property-wide search selectivity. Both behave the same way: lower lets more borderline matches through, higher only shows the closest. The per-rule dial is independent: a strict rule lives in a property whose general selectivity is looser, and vice versa.

Pinned items and the slot cap

The How many to pin per search slider caps how many of your pinned items actually slot into the top of shopper results. If you pin 8 items but the slider's at 3, only the first 3 appear in any given search; the other 5 stay on the bench. Useful when you want to author a deeper bench of options that you rotate through manually by reordering the list, without having to add and remove items.

The cap also protects shopper UX: pinning too many items pushes legitimate organic matches off the page. Three or four is the typical sweet spot.

Testing a rule

The Merchandising page has a Test a search panel below the rules list. Type a query the way a shopper might and the playground shows you which rule (if any) would fire on it, and which pinned items would surface. Every rule you have is scored against the query; the "Rules considered" table at the bottom tells you for each one whether it fired, and at what selectivity it would have fired (useful when you're tuning the dial).

The playground doesn't write a search query log or affect any metrics; it's a sandbox for tuning rules before turning them on.

Editing or removing a rule

Each row on the Merchandising page links into the rule. From there you can change the phrase, the items, the selectivity, or the pin cap. Changing the phrase puts the rule into a brief "updating" state while we prepare the new match. The previous version stays live during the update, so shopper searches never see an empty result.

To remove a rule, open it and use Delete rule in the danger zone at the bottom. Deletion is immediate and can't be undone; shopper searches stop seeing your picks right away.

Where rules fire

Rules apply across every search surface a shopper can use: your direct API integration through /v1/items/search, and the Shopify storefront search if you have the block installed.

Similar items (the row on product pages) and curated rows don't run merchandising. They're shopper-driven navigation, not search.

Rule limits per plan

Starter

Growth

Pro

100

Scale

The current cap and your usage appear at the top of the Merchandising page. If you hit the cap, you'll need to either remove an unused rule or move to a plan that fits. The number of pinned items per rule is also capped (10), separately from the slot cap.