Skip to content

Search and Discovery

Badger Commerce's search and discovery layer is built around a single principle: search is the substrate for browsing, not a feature bolted on top of it. Category pages, search results, virtual categories, megamenu queries, and curated landing pages all resolve through the same Typesense-backed search platform over the same per-tenant index.

For the architectural principles and domain model behind this, see Search Architecture. This document covers the customer-facing surface and what operators can author.

Operator Surface

Operators author discovery through four primitives, all of which are unified into a single merchandising tree model:

Manual Collections

Hand-curated groupings of products by seoName. Suit small catalogues, hero collections, and any case where editorial control beats classification. Existing customers' collections continue to work without migration — collections are now one node-type within the merchandising tree.

Taxonomy Projections

A node in the merchandising tree backed by a Taxonomy level. Products assigned to that level (or any descendant) appear automatically. Optional attribute filters narrow the projection further. The right tool when a customer's taxonomy already organises the catalogue the way customers should browse it.

Virtual Categories

A node backed by a saved query — "orange clothes under £100", "in-stock vegan footwear", "manufacturer = Apple AND rating > 4". Authored once in admin and indexed; behaves to the customer like any other category, with its own URL, SEO, and breadcrumb. Powerful for seasonal pages, themed landings, and merchandising experiments without code.

Manual Lists

A node backed by an explicit, ordered list of products. Useful for landing pages, gift guides, "Featured Today", and curated experiences where ordering and exact membership matter.

Any node except a manual list can also pin, boost and bury products by SKU, and each search term can have its own rule: see Pins, Boosts and Buries.

These can be mixed freely within a tree. A primary tree can use a taxonomy projection at the top, virtual queries on seasonal nodes, manual collections at the leaves, and a manual list for the homepage hero.

Multiple Trees per Site

A site has one primary tree (which drives canonical URLs and SEO) and may define additional named trees for:

  • Megamenus and navigation — different shapes for header, footer, mobile drawer.
  • Gift guides and seasonal landings — built as full trees, reused as needed.
  • A/B testing alternative information architectures (planned for round 2).

The same product can appear in many nodes across many trees without duplication; node membership is computed once at index time.

Search Engine

The platform uses Typesense as its search engine. A shared cluster runs one Typesense collection per tenant, addressed through the stable alias products__{catalogueId}, giving each site:

  • Sub-50ms typeahead and full-text search at typical catalogue sizes.
  • Typo tolerance out of the box, and stemming, so "boot" finds "Boots".
  • Category names, so "shoes" finds the trainers and boots in the Shoes category even when neither product says "shoe" (see Searching by category name).
  • Opt-in semantic search, so "footwear" finds boots with no synonym (see Semantic search).
  • Taxonomy-driven facets — each product's taxonomy attributes are indexed as facetable values, so a tenant's facets come from its own taxonomy.
  • Strong tenant isolation — cross-tenant queries are impossible by construction.

Index freshness is best-effort within seconds (event-driven via RabbitMQ) with nightly reconciliation against Mongo to catch drift.

Search is off by default and switched on per site with Use Search (useSearch, search-config). Without it a site has no search box on any theme, /search is a 404, suggestions are empty and its search index is dropped. Category pages (/c/...) keep working with search off, as they are listed from the same index: a catalogue with a merchandising tree keeps its product index for them, and only free-text search (including search within a category) is switched off. Which products search can find is a site setting too: Products Search Can Find (search-product-scope: in an enabled collection, the default; in a visible category of the primary tree; or all) and, optionally, Search Only These Collections (search-root-collections). See Search on or off and Which products are indexed.

Every product search carries a filter. Typesense (29 and 30.1) over-counts found for a query on stemmed fields with no filter_by: a deleted document's stemmed tokens still count, so after a catalogue re-import a search reported about twice its real hits and pagination ran into empty pages. Any filter makes the count exact, so a search with no filter of its own sends a match-all one (MerchandisingQueryService.MATCH_ALL_FILTER). Keep it until Typesense fixes the bug.

Faceted Navigation

Facets are derived from the active taxonomy and surfaced according to a three-level fallback (node → tree default → taxonomy default). Most sites configure a tree-level default and rarely touch individual nodes. The taxonomy default, used by /search and by any node with no list of its own, is every select-type attribute of the active taxonomy, then Price, Brand (manufacturer) and On sale.

How facets are chosen

The result set decides which filters show, so a broad search across a mixed catalogue doesn't list every attribute in the taxonomy. Each indexed product lists the taxonomy attributes it has a value for (taxonomyAttributeIds), and the main query facets on that field, which gives each attribute's coverage: the share of the results that carry it.

  • Taxonomy default (search, and nodes without a list): an attribute shows only when at least 20% of the results carry it, best-covered first (ties by the attribute's taxonomy display order). Price goes second, after the best-covered attribute, Brand third (shoppers, trade buyers especially, filter by brand early, so it never falls behind "More filters") and In stock fourth; other platform toggles follow the attributes, then On sale last. In stock only appears when some of the results are out of stock, as a facet that can't narrow the results is hidden. A search for "screw" on a builders' merchant shows drive, length and head, because screws dominate the results; a search for "a" shows the handful of attributes most products share.
  • Curated lists (a node's or tree's own facet list): the list's order is kept, and an attribute is dropped only when fewer than 5% of the results carry it, which is stray data rather than a real filter. Price is added second when the list doesn't name it, In stock straight after it, and Rating after that; list price, inStock or rating to put them somewhere else. In stock only shows when some results are out of stock, and Rating only when a threshold would narrow the results (some are rated, and not all of them clear it), so a category whose range is all in stock and unrated looks unchanged.
  • A facet with a value selected always stays, whatever its coverage, so a shopper can always see and undo a filter.
  • At most six groups show open. The rest sit closed behind a More filters (n) disclosure (a native <details>, no JavaScript). A group with a selection is never tucked away.

The thresholds are site config keys in search-config: facet-min-coverage-percent (default 20), facet-curated-min-coverage-percent (default 5) and facet-visible-groups (default 6). A facet whose values can't narrow the results is still hidden, as below. Set smart-facets-enabled to false to switch off both the coverage threshold and the hiding of facets that can't narrow, so every filter that has values stays in the rail.

Price

The price facet offers a few buckets with counts and min/max inputs.

  • Buckets are shaped by the results. In the same query, Typesense counts the results against a fixed ladder of round bands (£1, £2, £5, £10, £15, £20, £25 … £10,000; facet_by=price(p0:[0, 100], …)). The query layer folds adjacent bands into up to four buckets of roughly equal size, so the boundaries are always round: Under £5, £5 – £10, £10 – £25, £25 and over. Results all at one price get no price facet; prices that spread within one band get the inputs only.
  • Min/max inputs are a plain GET form (price_min, price_max, in pounds, the max inclusive), so they work without JavaScript; every other filter, the sort and the query travel as hidden fields. The placeholders show the lowest and highest price in the results. With JavaScript, a two-thumb slider sits above the boxes (see Range sliders).
  • The URL carries one range in pence, minimum inclusive and maximum exclusive: price=500-1000 (£5 up to £10), price=2500- (£25 and over), price=-500 (under £5). Typed inputs are folded into this token, so every link, chip and "clear" uses it. The filter is price:>=500 && price:<1000.
  • Counts are disjunctive, like the other facets: the buckets are counted without the price selection, so choosing £5 – £10 still shows the other buckets. The applied filter shows as a chip with a readable label (£5 – £25) that removes it. Prices are indexed as int32 minor units and labelled in the site currency (siteCurrencyCode).
  • REST (/api/search, /api/merchandising/{path}) takes the same range as filter=price:500-1000, and returns the facet with type: range, its buckets, and min/max.

The picture for a filtered colour

When a listing is filtered by something a product's options decide (a colour, ticked in the filters or as a colour page such as /c/women/tops/colour/green), each card shows the pictures of the first variant that matches, so a jumper made in five colours shows its green photo on the green page, not its first colour's. A variant matches when one of its options counts towards a selected value, the same way the filter counts it: the option's group feeds that attribute (taxonomyAttributeId, else the group's code) and the option reads as the value (attributeValues, Forest green → Green, else itself). A product with no matching variant, or whose variants have no pictures of their own, keeps its own. It costs nothing per card: ListingImages works from the products the page already loaded and the shop's variant groups (one small lookup, only on a filtered listing), and sets DProduct.listingImages. Category pages and search do this.

Colour swatches and number ranges

Each taxonomy attribute says how it shows as a filter (facetDisplay on the attribute, set in the taxonomy editor, over REST or MCP):

Display Shows Use for
LIST (default) Ticked values with counts Most attributes
SWATCH The same, each value with a colour dot Colour
RANGE Range buckets and min/max inputs over the values as numbers, with a unit Lengths, diameters, widths

Swatches. A value's colour comes from the attribute's swatches map (Heather → #9c7c9c), otherwise from its name: a known colour word (Navy), or the last one in a longer name (Light Grey, Hi-vis yellow). Clear/Transparent draw as a checkerboard and Multi as a rainbow; a value with no colour shows without a dot. Only hex colours and known words are used, as the colour goes into a style attribute (Swatches). The facet is type: swatch and each value carries swatch.

Number ranges. Every attribute value that reads as a number (40, 4.5, 40mm, 1,200 mm; not M8 or 10-12) is also indexed into a float array per attribute, num_<attribute> (num_length_mm), declared once in the schema as the num_.* pattern (NumericFacet). The values come from the stock-trimmed pairs, so a sold-out 50mm variant doesn't match either. A RANGE attribute then:

  • facets on that field, for the lowest and highest value (the inputs' placeholders, whole numbers) and each distinct value's count, counted without its own selection;
  • offers up to four range buckets folded from those values (NumberBuckets), single-select links like price's: roughly equal shares of the results, each running from its lowest to its highest real value so they never overlap and read naturally (16 – 25 mm, 30 – 45 mm, 50 – 80 mm, 100 mm and over; the last is open above, and a bucket of one value is just that value, 5 mm). Where to cut trades evenness against round numbers: a cut that starts the next bucket on a value round for the spread (a multiple of 25 over 16 to 200 mm, of 2 over 3.5 to 12 mm) beats one a value or two away. With two or three distinct values each is a bucket; with one there is no filter. Typesense can't count a float[] into range bands (range facets need a sortable single-value field), so a bucket's count adds up its values' counts: a 40/50 mm pack counts twice in 40 – 60 mm, capped at the number of results counted;
  • filters it inclusively: the URL token length-mm=40-60 is num_length_mm:[40..60], and 40- / -60 are open-ended. A product with several values (40, 50 and 60mm) matches a range holding any of them;
  • takes typed inputs as length-mm_min / length-mm_max (plain GET form, like price), folded into the token for every link and chip (FacetParams);
  • is single-select, type: number, with unit, min and max; its values are the buckets (tokens such as 16-25 and 100-), and a typed range that isn't a bucket is listed first as selected, labelled 40 – 60 mm, as price does;
  • is left out when nothing is selected and its values don't spread.

If Typesense doesn't know an attribute's number field (switched to RANGE though its values aren't numbers, or an index built before revision 4), the query is retried with those attributes as plain lists and their range selections ignored. REST takes filter=length-mm:40-60.

How the rail behaves

  • Headings and value order come from the taxonomy. A taxonomy facet is headed by the attribute's display label ("Length (mm)", not "Length Mm") and lists its values in the attribute's allowed-values order, so sizes run small to large and lengths short to long. Platform facets are headed Price, Brand, In stock, Rating, On sale and Featured.
  • Counts are disjunctive. A facet's counts apply every other facet's selection but not its own, so after choosing 40mm the Length facet still offers 50mm (values within one facet are ORed) with an honest count. Each facet with a selection adds one facet-only query, and the main query and all of these go to Typesense together in a single multi_search request, with the page's category counts (see How category counts are computed).
  • Facets that can't narrow are hidden. A facet whose only value is on every result, and isn't selected (a single-brand shop's Brand, a Finish where everything is zinc), is left out (unless smart-facets-enabled is off).
  • Long groups can be searched. A group with more than 10 values (Brand on a big catalogue, say) has a search box above its list (fragment/facet-search, every theme): typing narrows the list to matching values, all of them rather than the first six, with a No matches note when there are none. It filters the values already on the page (up to 250 per group), so each is still a plain filter link; without JavaScript the box isn't shown and every value is listed.
  • Only real facets filter, and only so many at once. A URL param is a facet only when the shop has one by that id (a platform facet or an attribute of the active taxonomy); anything else is ignored and left out of every link on the page, so a mistyped or invented param can't empty the page. A shopper can combine up to search-max-selected-facets different filters (search-config, Filters Combined at Once, 5 to 10, default 8). Once that many are applied the rail says so (You can combine up to 8 filters), and the groups not yet filtered show their values without links; the filtered groups can still change. A URL naming more is cut to the first ones, with a note that the rest were left out. This keeps the number of distinct filter URLs finite, so a crawler that ignores nofollow can't walk every combination (see Listing traffic guard).
  • Phones get a quick-filter bar. Above the results, a sideways-scrolling row of Filters (n) and a pill for each of the first six groups opens the panel at that group, and In stock / On sale pills apply in one tap (see Quick filters on phones).

Category pages show a category nav above the filters: the parent, then the sub-categories, or for a leaf its siblings with itself highlighted. Each sub-category shows how many products it holds for the current search term and filters, and one with none is left out (a leaf's own entry always stays). A node saved without a stereotype gets merchandisingNode, which carries the header menu and search box. A menu item can link straight to a category page: its link type is Category page (/c/) (MERCHANDISING_NODE) and its target the page's canonical path, e.g. /c/fixings/screws, which survives a site transfer the way a collection's seoName does.

All products (/c)

/c (and /c/) is the primary tree's root: an All products page listing every product in the catalogue, with the same facets, sort, pagination, search-in box and phone quick filters as a category page, in every theme that renders /c/** (the header search box has no scope picker there: the page already is the whole shop). Its category nav lists the top-level categories (departments) with their counts for the current term and filters, so it is the natural target for a "Browse the catalogue" or "Shop all" link, and a menu item can point at it (a menu link to /c counts as a listing, so its dropdown says "Shop all"). It is indexable with a self canonical (https://{domain}/c), is listed first among the category pages in the sitemap, and has a single-crumb breadcrumb.

The page is not a stored node: MerchandisingTreeService.findRootNode builds it on each request (no id, no backing, the primary tree's id so the tree's default facet config applies, and the merchandisingNode stereotype so the header menu and the stereotype's extensions render), findVisibleChildren returns the top-level nodes as its children, and MerchandisingPageController searches the whole catalogue for it (a search with no node, as /search does with no term), so it lists every product in the index: the products in a category, plus, with search on, the products in the site's search scope. A product in no category and outside the search scope (one sold only through a direct link) is not listed. Its heading is the merchandising.root.name message ("All products") and its meta description merchandising.root.metaDescription ("Browse every product from {site name} by category, or narrow the range with filters."); both can be changed per site as Site Text. A site with no primary tree has no /c page: it is a 404, like any unmapped path. The root has no brand landing pages, and existing category breadcrumbs do not (yet) start with it.

/search opens its rail with a Category group: the primary tree's top-level categories with how many of the results each holds, in tree order, leaving out categories with none. When one category holds 90% or more of the results and has visible sub-categories, its sub-categories are listed instead (up to three levels down), so a single "Shop" root doesn't swallow the facet. Category is navigation, not a filter: each entry is a link to /c/<category>?q=<term>, a search within that category, which then shows that category's own facets.

Links carry the facet selections the target category's page can apply (the facets its resolved facet config lists) and drop the rest, so a count always matches the page it opens. Paging and sort are dropped.

Search within a category

A category page accepts q: /c/fixings/screws?q=pozi text-searches the category's products (its backing filter ANDed with the term). The heading reads "Results for "pozi" in Screws" with a link to search the whole shop, sort, pagination and facet links keep q, and the sub-category counts follow it. Without q the page is unchanged. A searched category page is noindex, follow and its canonical stays the plain category URL, so search URLs aren't indexed. Following a category from /search is a refinement, so it is not recorded in search term analytics.

A category page has a Search in {category} box under its heading (every theme), a plain GET form to its own URL, so a search can start inside a category as well as be narrowed to one from search results. The box only appears when there is a list to search through: the category runs to more than one page, or is already searched or filtered (so it doesn't vanish as filters narrow the list).

On a category page the header search box has a scope picker too: All products or the category (fragment/search-scope, a <select name="in"> inside the header form, so it works without JavaScript). It starts on All products, so the header keeps searching the whole shop; on a category already searched (/c/…?q=) it starts on the category and the box holds the term, so the header shows the search on the page. /search?in=<canonical path>&q=<term> redirects to /c/<category>?q=<term>. The path must be a visible node in the site's primary tree, and the redirect is built from the stored node (with the term strictly encoded), never from the parameter, so in can't be used as an open redirect; an unknown, hidden or off-site value is ignored and the whole shop is searched. The suggestions dropdown's See all results link carries the scope too.

Both are controlled by the site config key category-search-enabled (search-config, default on, Search Within a Category in the admin). Turning it off hides the page box and the header scope; /c/<category>?q= links, such as the search page's Category group, keep working. On a site with search switched off (useSearch) neither is offered and a ?q= on a category page is ignored: the page lists the category as usual.

On phones the filter panel (the bottom sheet in Depot, Brock, Pop and Spec, Nova's inline drawer, Atelier's drop-down drawer at any width) stages taps and applies them together, keeping its Show N products count current by asking the staged URL for its facet-total fragment (see Storefront Fragments). /search, /c/... and /collection/... answer that with the count alone, straight after their search, and never record it as a search, a page view or product impressions. Requests with the older X-Badger-Count-Preview header, from pages opened before the change, are still not recorded. The behaviour is one shared script, nova/js/modules/facet-sheet.js, driven by data-facet-* attributes (panel, value links, single-select groups such as price, rating and number ranges with the params each owns in data-facet-keys, their min/max forms (data-facet-range), apply and dismiss controls, and the long-group search box), so a theme opts in with markup alone; it needs nova/js/fragments.js on the page too, which every theme's head loads. It also folds long groups to six values behind Show all where a theme marks the button data-facet-more.

Quick filters on phones

Below 1024px, where every Nova-family theme turns the rail into its panel, the listing (/search and /c/**) shows a quick-filter bar above the results: one row that scrolls sideways on its own (the page never does), in all six themes. It holds:

  • Filters (n): opens the full filter panel; n is how many filters are applied. It replaces the toolbar's phone Filters button (which is still drawn when a page has categories to show but no filters), and in Atelier the Filter pill, so there is one way in.
  • A pill per top filter group: the rail's first six visible groups that have values to pick (FacetRailModel.quickGroups(); a number filter with only min/max inputs is left to the panel). A list group (Size, Colour, Brand) opens the panel at that group: its section is opened (and More filters around it, if it's there), scrolled to and focused. A group with a selection is drawn active and says what was chosen: Size: 9, or Colour (2) for several.
  • Toggle groups are the toggle: In stock and On sale pills link straight to their toggle URL, so one tap applies or removes them. Screen readers hear a chosen one, like a chosen filter value, as "In stock (selected)": the state is part of the link's name, since a link can't carry a pressed state.

The bar is server-rendered from the facetRail model (nova/fragment/quick-filters.html, styled once in bdgr.css in the theme's Nova tokens), so it keeps no state of its own. Each pill is a real link: the Filters button points at the panel (#depot-filters) and a group pill at its group's section (#facet-size, FacetRailModel.Group.anchor()), which is where it lands without JavaScript in Nova and Atelier, whose panels are always open then. With JavaScript, facet-sheet.js handles any [data-facet-open] control: aria-controls names the panel, an empty value is the Filters button and otherwise the value is the group section's id. A <details> panel (Nova) is opened directly; any other panel gets a cancelable facet:open / facet:close event that the theme's own script takes (focus, scroll lock), falling back to toggling .is-open. Where the panel doesn't cover the bar (Nova, Atelier), Filters closes it again and discards what was staged. The bar's aria-expanded follows the panel. Pills are 44px tall with a visible focus ring, and the scroll to a group is instant under reduced motion.

Range sliders

The same script puts a two-thumb slider above every min/max form (price and number filters) whose boxes have numeric placeholders, in every theme; it is styled once in bdgr.css (.bdgr-range-slider, in the theme's --color-primary). Each thumb is a native <input type="range"> without a name, so arrow keys, Home/End and screen readers work, it is labelled by its box's caption (Min, Max) with the currency or unit in aria-valuetext, and it never submits anything itself: moving a thumb fills in its box (a thumb at its end leaves the box blank, so no bound is applied), and the box's form applies it with Go, or stages it in the phone sheet like a typed range. Typing in a box moves its thumb, and the thumbs can't cross. Without JavaScript there is no slider and the boxes work as before.

How category counts are computed

CategoryCountService (commerce-core, search.query) counts what each category's own page would find: the node's backing filter (a group node is the OR of its descendants), the term, and the applicable facet selections, with per_page=0.

A listing page fetches its products and its category counts together, so the page is one Typesense round trip: the controller calls CategoryCountService.searchWithNodeCounts (/c/**: the sub-categories, or a leaf's siblings) or searchWithCategoryCounts (/search), which plans the count searches and hands them to MerchandisingQueryService.search(siteContext, spec, extras). They ride in the same multi_search request as the main query, the disjunctive-count queries and the combination counts, after them, and come back as BatchedSearch.extraResults().

  • The Category facet on /search. The top-level categories' counts ride in the request. While a level of the tree is a single node (a Shop root), its children's counts ride too, since that node is the only one that can hold nearly all the results and be opened up. Opening up one of several top-level categories needs the first level's counts first, so that one case is a second request.
  • The 50-search limit. Typesense takes at most 50 searches per multi_search request (MerchandisingQueryService.MAX_MULTI_SEARCHES, its default limit_multi_searches). When the page's own searches plus the counts would pass it, the page is sent alone and the counts follow in their own request, batched at 50, so the page costs two round trips, as it did before.
  • Failures stay separate. A count search that fails only loses its count; the page renders as it would without it. When the page's main search fails and is retried (an index without the coverage, combination or number fields), counts already answered aren't sent again. Counts lost because the whole request failed (a transport error) ride the retry.

CategoryCountService.count, countsForChildren and countsForSearch still count on their own (the sitemap uses count), one multi_search request per 50 nodes. Nodes come from MerchandisingTreeService scoped to the request's SiteContext, so only the tenant's own primary tree is read, and hidden nodes are never counted. When search isn't configured or Typesense fails, a category page keeps its sub-category links without numbers, and the search page shows no Category group.

Supported facet types:

  • Categorical — colour, size, manufacturer, material (any taxonomy attribute); colours can show as swatches.
  • Boolean — on sale, featured, in stock. In stock is part of the taxonomy default (see Stock and the In stock filter).
  • Range — price (buckets and min/max inputs), and numeric taxonomy attributes set to RANGE (buckets folded from their values and min/max inputs; see Colour swatches and number ranges). Both get a slider with JavaScript.
  • Rating — 4★ & up, 3★ & up, 2★ & up, single-select like price (rating=4 in the URL; ratings are stored out of 100, so rating:>=80 in the filter). Typesense counts the indexed rating into whole-star bands in the same query and each threshold sums the bands at or above it; a threshold every result meets is left out, and unrated products never match, so the group only shows when it narrows the results. Part of the taxonomy default, after In stock, and added to curated lists after In stock unless they name it.

Facets are product-level, but sizes and colours follow the variants' stock: Size 9 matches a product only while a size-9 variant can be bought (see Sizes and colours follow stock).

Theme support

Every theme (Nova, Depot, Brock, Pop, Spec and Atelier) renders the facets the platform chooses with the More filters fold, price buckets and min/max inputs, colour swatches (a .bdgr-swatch dot from the shared nova/css/bdgr.css) and number-range inputs with their unit, disjunctive counts, the Category group on search and the category nav with counts on category pages, the staged filter panel and the Search in {category} box. Atelier draws the category nav as a row of chips above its filter bar (its filters live in a drop-down drawer, not a side rail) and stages taps in that drawer at every width, not just on phones.

Variants in Listings

A search returns one document per product: the red shirt appears once, not once per variant, and facet counts are by product. The variants decide three things on that document: whether it is in stock, which sizes and colours it offers, and which codes find it (an enabled variant's SKU and barcodes, see Searching by SKU or barcode). An option the parent's taxonomy attributes don't list can't be filtered on.

Colour swatches on the cards

On collection, category and search listings, a product that comes in two or more colours shows a dot per colour under its name: up to five, then "+N" for the rest. The colour group is the product's first option group (by the picker's order) that the variant picker draws as swatches: one coded colour (or color), or one with swatch colours set (manageVariantGroups setSwatches). Each dot's colour is worked out as the picker's and the swatch filter's are (Swatches); a value that names no colour is a plain ring. Disabled variants are left out.

Each dot links to the product page at that colour (?v= the colour's first variant), so it works without JavaScript. With it (nova/js/modules/product-cards.js), pointing at a dot or tabbing to it shows that colour's photo on the card and points the card's links at that colour; a click then follows the link. On a touch screen the first tap shows the colour and the second opens the page.

The photo isn't in the page: the first time a dot is chosen, the script asks the public gallery endpoint for that colour (GET /api/public/v1/products/{seoName}/gallery?variant={sku}, the endpoint image scrubbing uses), which answers the variant's photos, or those of the first variant in the same colour that has some. Each colour is fetched once per page; the card keeps its own photo while it loads, and for good if the colour has none or the request fails. Nothing is fetched ahead of a choice, so Save-Data costs nothing extra, and the swap is instant, so it needs no reduced-motion variant. Each dot carries only its colour and its variant's SKU; the list carries the product's seoName and the site image path once (data-swatch-product, data-swatch-base).

The swatches are worked out by ListingCardOptions (CardSwatches) from the products the listing already loaded (their variants' option values, stored on the product) and the shop's variant groups (one cached read), so they cost no query per card and need none of the variants' images. They are on by default; Colour Swatches on Product Cards (product-card-swatches, Listings settings) turns them off. Every theme except Atelier shows them.

Quick add

On the same listings, "Choose options" on a product with options (not a bespoke product, a donation or an amount the shopper types) opens a dialog over the listing with the product's options, price, stock and Add to basket, instead of going to the product page. The choices are the product page's own: the enabled variants, their stock as the product page counts it and each colour's swatch. If the shopper was looking at a colour on the card, that colour starts chosen; a group with one option is chosen already. A choice that leads only to something sold out, or to a combination that doesn't exist, is struck through but can still be chosen, and Add to basket then says why it can't add.

The dialog is the product page's quick-add fragment (see Storefront Fragments), and the add is the shared background add to basket: the header basket and the drawer are updated, and in the Brock family the "added to basket" pop-over opens, as on the product page. Without JavaScript, or for anything the dialog can't sell (an event ticket, a dish ordered from the restaurant menu, an appointment), the button goes to the product page as before. On by default; Quick Add on Product Cards (product-card-quick-add) turns it off. Every theme except Atelier offers it.

SEO

Each merchandising node owns its SEO surface:

  • seoName and a denormalised canonicalPath (mirrors the existing Collection.canonicalPath model).
  • Optional override of meta title, meta description, and canonical URL.
  • Sitemap inclusion controlled per-node (seo.excludeFromSitemap). The sitemap lists every visible node of the primary tree that has products; a hidden node takes its subtree out with it. The All products page (/c) is listed first when any category is.
  • Breadcrumb chain denormalised onto each node for cheap rendering.
  • With the site's category-navigation-source set to MERCH_TREE, product pages take their breadcrumb from the tree too: Home, the product's home node's chain, then the product. The home node is the product's primaryCategoryNodeId when that node is visible, or else the deepest visible matching node not marked excludeAsProductHome (ties go to tree order). CategoryNavigationService matches with the indexer's rules (ProductNodeMatcher) against a per-catalogue snapshot of the primary tree, cached for a minute, so a product page runs no extra query. See Category navigation.

The primary tree's structure determines canonical URLs; non-primary trees can reuse nodes without competing for canonicality.

A category page searched with q (/c/fixings/screws?q=pozi) is noindex, follow, with its canonical left on the plain category URL, so search URLs never compete with the category. Facet-filtered and sorted URLs get the same treatment, and later pages (?p=N) are indexable with a self canonical; see Catalogue SEO. A category can also generate indexable brand landing pages (/c/tools/brand/halden-pro) from a rule on the node or the tree; see Brand landing pages.

Stock and the In stock filter

Each product's inStock flag comes from the inventory service, the source of truth for stock (Product.quantityInStock is deprecated). A product with variants is in stock when any enabled variant has stock; one without variants when its own SKU does. Untracked stock (-1) counts as in stock, and a product whose stock can't be read is treated as in stock, so the filter never hides products the shop may well have. A rebuild reads stock in bulk, one query per page of 500 products.

Stock changes reach the index without a write per sale:

  1. Only crossings count. The inventory service publishes a StockAvailabilityChangedEvent only when a SKU sells out or comes back in stock. Selling the 40th of 100 drills changes nothing in the index. The crossing is exact even under concurrent orders: the stock update is atomic and returns the new level, so the level before it is known precisely.
  2. Coalesced in Redis. StockIndexQueue adds the SKU to one Redis set (search:stock-changed). A SKU that flips several times before the worker looks, or a stock import touching thousands of SKUs, is still one entry per SKU.
  3. Flushed by the worker. StockIndexFlushJob drains the set every 5 seconds (badger.search.stock-flush.interval-ms) in batches of 500 (badger.search.stock-flush.batch-size, up to 20 batches a run), with SPOP so each SKU goes to one worker replica only, and reindexes each affected product once.

So a busy shop's index sees a write only when something actually sells out or is restocked, a few seconds later. If Redis is unavailable the change is dropped and the nightly reconcile, which recomputes every product's availability, corrects it.

A shop with multiple stock locations on works the same way with one difference: a sale at one warehouse can matter without selling anything out there, so every stock change at any location is queued (StockLevelChangedEvent). The flush job first recomputes those SKUs' SkuNetworkAvailability documents, then reindexes only the products whose availability changed for shoppers. For such a shop inStock means the product can be sent from some shipping location after safety stock, or collected somewhere; the nightly reconcile rebuilds the view before it reindexes.

Sizes and colours follow stock

A product offers a size or colour in the filters only while a variant in it can be bought. Filter on Size UK 12 and a boot whose UK 12 has sold out no longer matches, and UK 12's count drops by one; when it's restocked the boot comes back (the same sell-out and restock path as above).

A filter attribute counts as a variant axis when its values come from the variants (VariantFacets, worker):

  1. a variant's own taxonomyAttributes, when it has them (fashion and synced catalogues give each variant its exact size and colour); otherwise
  2. its variant options. An option counts towards the attribute its option group names (VariantGroup.taxonomyAttributeId), otherwise the attribute whose id is the group's code (a size group feeds size), and only if the product has that attribute. It counts as the value the group maps it to (VariantGroup.attributeValues), otherwise as itself. On Halden the kit group feeds Supplied as, with every battery kit ("2 x 2.0Ah kit", "1 x 5.0Ah kit") counting as "Kit with batteries", so a drill whose kit has sold out drops out of Kit with batteries. An option group that names no attribute and matches none plays no part. Changing a group's mapping (admin, MCP) rebuilds the site's index.

For a variant-axis attribute a value is kept only when an enabled, in-stock variant carries it; a disabled variant never offers its size. Values no variant carries at all, and every other attribute, are left as they are, and when stock can't be read nothing is removed. Coverage still counts the sold-out sizes, so the Size filter doesn't disappear from a category just because its sizes are selling through.

Combinations: Black + Size 9

Choosing values of two filters asks for one variant that has both. A shoe with a black size 8 and a red size 9 in stock doesn't match Black + Size 9 (VariantCombos):

  • The index holds, per product, variantCombos: one token per pair of attributes per enabled, in-stock variant (colour:Black|size:9, attributes in name order), and variantComboAttrs: the attribute pairs its variants vary on together (colour|size), in stock or not.
  • Selecting values of two list attributes adds (variantCombos:=[colour:Black|size:9, …] || variantComboAttrs:!=[colour|size]) to the filter, with a token for every pair of selected values (Black or Navy with 9 or 10 is four). A product whose variants vary on both needs one buyable variant with a selected value of each; any other product (a sock in black, size 9, with no variants; a boot whose only option is size) is judged by its values as before.
  • Three or more selected attributes are checked a pair at a time: colour + size and size + fit can each be met by a different variant. Number ranges and platform filters (brand, price) aren't part of it.
  • Counts follow the combinations: with Orange chosen, L counts a product that varies on colour and size only if it has an orange L in stock, so the count is what choosing L finds. For each list filter counted while another list attribute has a selection, one more facet-only query goes in the same multi_search batch: the products that filter is counted over, narrowed to those varying on both (variantComboAttrs:=[colour|size]), faceted on their pairs and on variantCombos. A value's count is its per-attribute count less the products that vary on both, carry the value, and have no buyable variant with it and a chosen value of the other attribute. The results' own query is unchanged.
  • The cost is one query per counted list filter per other selected list attribute (Orange chosen with Colour, Size and Fit filters is two: Size|Colour and Fit|Colour; nothing extra without a list selection), at most 20 a page. Platform filters, price, rating and number ranges aren't adjusted.
  • It's exact for one other attribute with one chosen value. Facet counts can't tell products apart, so beyond that a count can be slightly high, never low: with Black or Navy chosen, a product with a buyable L in both counts once per colour (capped at the products carrying L), and with two other attributes chosen the larger shortfall is taken off. A chosen value stays listed even at zero, so it can be cleared.

Halden's hi-vis vest comes in yellow and orange in M to XXL, with orange L sold out: Orange + L leaves it out, Orange + M finds it. The index revision (PRODUCT_INDEX_REVISION 6, which makes variantCombos facetable) makes every site rebuild once. Until it has, a query that the old index rejects is retried judging each attribute on its own, without the combination counts, and a combination count the old index can't facet leaves that filter's counts per attribute.

Relevance

How a listing is ordered when the shopper hasn't picked a sort (Featured), and the signals behind it.

Listing Order
No ranking Best text match first (for a search), then well-reviewed and in stock, then the rest in stock, then sold out; best sellers break ties
With a ranking (pins, boosts and buries) Pinned, in the order given, whatever their stock; then boosted, unranked and buried products, each in stock first; within each, best match, then best sellers
  • Text first. For a search, a product that matches better comes first even when it's sold out; stock and sales only order products that match equally well. Browsing a category, every product matches equally, so stock and sales decide.
  • Sold out sinks, pins don't. A merchandiser who pins a sold-out product chose to; it keeps its place. A sold-out boosted product still comes before every unranked one, after the boosted ones in stock.
  • Well reviewed comes first. Among in-stock products, those with at least 3 published reviews averaging 4 stars or more go first. A rating set by hand in the admin never lifts a product; nor does reviewing on a listing with a merchandiser's ranking, whose tiers already decide the order.
  • Best sellers break ties, rather than the price (high to low) order Featured used before. On an Enterprise shop with enough orders, a learned score for the listing's goal (revenue, units, conversion or margin per time shown) breaks them instead, within bands of similar relevance: see Ranking by What Sells.
  • A manual-list category keeps its own order; a sort the shopper picks (price, newest, best selling) is exactly that.

Best selling

A Best selling sort (?sort=best-selling, also on the REST search endpoints) orders by units sold, best match breaking ties. It is in every theme's sort dropdown.

Top rated

A Top rated sort (?sort=top-rated) puts products with published reviews first, best average first and more reviews breaking ties, then products with only a hand-set rating, then the unrated (_eval(reviewCount:>0):desc,rating(missing_values: last):desc,reviewCount:desc). A hand-set 5 stars never outranks a reviewed 4.7. The sort dropdown offers it only on sites with reviews on (reviews-enabled). The rating is the review average once a product has published reviews (see Product reviews).

Popularity

A product's popularity is the units it sold over the last 90 days (site config search-popularity-days, search-config):

  • Real sales only. Orders that were placed and paid and not cancelled: submitted, packing, dispatched or delivered. Baskets, orders awaiting or failing payment, cancelled orders and cancelled lines don't count.
  • Variants roll up. Selling the drill's 2Ah kit counts for the drill.
  • Nightly. The worker's ProductPopularityJob recomputes it at 02:30 (badger.search.popularity.cron), and once at worker startup after the index schema check (badger.search.popularity.on-startup, off with badger.search.popularity.enabled=false). So a sale moves a product up the next morning, not straight away.
  • Sites sharing a catalogue share its index, so their sales are added together.

Field weights

What a search looks in, and how much a match in each field counts, is the site config search-field-weights (search-config), default name:4,categories:3,searchTerms:3,description:1: a product named "Drill" comes before one that mentions drills in its description. The fields are name, categories (the names of the categories the product is in, see below), searchTerms (the product's search terms and brand) and description, each with a whole-number weight from 0 to 127; a field left out isn't searched. categories is the exception: a setting that doesn't name it (one saved before it existed) searches category names at the searchTerms weight, and leaves them out where it leaves searchTerms out. A value that can't be read (an unknown field, a repeated one, a weight that isn't a number in range) is logged once as a warning and the default used. Every product search uses them: the results, the filter and category counts (so a count is what a click finds) and the search-box suggestions.

How closely a word has to match depends on the field. In the name, category names and search terms a word may have up to two typos ("jumpr" finds a jumper, "shoos" the shoes). In the name and search terms the last word typed may also be the start of a longer one ("trai" finds trainers); not in category names, which shoppers type whole (otherwise "jumpr" found everything in "Dresses & jumpsuits"). A description matches whole words only (still stemmed, so "boot" finds "boots"), with no typos and no half-typed words. Typesense only turns to typos and half-typed words when nothing matches exactly, and in a description they matched anything that looked alike: before this, "shoes" found jeans "showing" off the ankles, a skirt's "sheen" and a T-shirt's "shoulder" seams, and none of the shop's shoes. Under the hood this is the num_typos and prefix sent per query_by field (SearchFieldWeights).

Searching by category name

A product can be found by the name of every category it is in, and of those categories' parents: a pair of trainers under Women › Shoes › Trainers is found by "trainers", "shoes" and "women", so "womens shoes" finds it too. The names come from the merchandising tree categories the product resolves into (hidden categories excepted; their visible parents still count) and from its taxonomy level and that level's parents ("Footwear › Boots"). They are stemmed and forgive a typo ("shoos"), but are typed whole, not as the start of a longer word, and count like search terms: below the name, well above the description.

The names are the categories field of the product document (string[], stemmed, product index revision 12), written by the worker (MerchandisingResolver.resolve). Renaming, moving or adding a category reindexes the catalogue, so the new name finds its products straight away; renaming a taxonomy level reaches existing documents with the nightly reconciliation. An index built before the field existed rejects a search that names it, so, as with codes below, the catalogue searches without category names for a minute at a time until the worker has rebuilt the index (it does so at startup after the deploy). A collection's name doesn't find its products; a shop without a merchandising tree or taxonomy can add the word as a search term or a synonym.

Searching by SKU or barcode

Every product search also looks in the product's codes: its own SKU, its barcodes, and the SKU and barcodes of each enabled variant (a disabled variant's codes don't find it). Typing HB-1042, hb1042 or a variant's SKU finds that product: Typesense drops the punctuation on both sides, so the hyphen doesn't matter. A whole code is needed (1042 alone doesn't match HB-1042), and codes allow no typos, so a mistyped part number finds nothing rather than the part one digit away. The codes field always counts as much as the heaviest field in search-field-weights, and it isn't one of the fields that setting names, so a site that weights its own fields still finds products by SKU. The results show the product, once; when a typed word is an enabled variant's SKU or barcode, that product's links open it with the variant chosen (?v=). This works on /search and on a search within a category, but not yet in the search-box suggestions.

Under the hood the codes are the codes field of the product document (string[], not stemmed, product index revision 11), matched with num_typos 0 while the short text fields keep Typesense's default of 2 (SearchFieldWeights). An index built before the field existed rejects a search that names it, so after a failure naming codes the catalogue searches without it for a minute at a time (MerchandisingQueryService) until the worker has rebuilt the index.

The variant is picked after the search, from the products on the page (VariantCodeMatches: case ignored and punctuation dropped, as Typesense compares codes). A product whose own SKU or barcode was typed gets no variant. The controllers put the matches on the model as matchedVariants (JSON of seoName to variant SKU), and fragment/search-click-ref, the script every theme's results and category pages already include for click tracking, adds v to those products' links, whether or not tracking is on. A link that already names a variant keeps it.

Semantic search (opt-in)

With semantic search on, a typed search matches products by meaning as well as by keyword: "footwear" and "shoes" find the safety boots and rigger boots, though neither word is in their names. No synonym is needed. Keep synonyms for brand language and exact equivalents ("hi-vis" = "high visibility", a brand's own range names), which a general-purpose model doesn't know.

It is off by default, per site, because it costs Typesense CPU, memory and time. Turn it on with the site config search-semantic-enabled (search-config).

Setting Default What it does
search-semantic-enabled false Builds the site's index with an embedding per product, and makes typed searches hybrid
search-semantic-alpha 0.3 How much the meaning match counts against the keyword match when the two rankings are fused, 0 to 1. Low keeps exact keyword matches first and uses meaning to find what keywords miss
search-semantic-distance-threshold 0.7 How close in meaning (cosine distance, 0 to 2) a product must be to be found by meaning alone. Lower is stricter. Keyword matches are always found

When to turn it on. When shoppers describe what they want in other words than your product names use: a trade catalogue named by part ("Rigger boot", "Hi-vis vest") searched by need ("footwear", "protective clothing"), or a gift shop searched by occasion. The admin dashboard's zero-result searches show whether this is happening. A catalogue searched mainly by part number, size or brand gains little; leave it off there.

What it costs. Typesense computes the embeddings itself with a small built-in sentence model (ts/all-MiniLM-L12-v2, 384 dimensions):

Keyword only Semantic on
Indexing a product (measured, Typesense 29 in Docker on an Apple M1 Pro, 500 products) 0.1 ms 19 ms; expect 2 to 5 times that on a small ARM node
Rebuilding 10,000 products seconds about 3 minutes on the M1, roughly 6 to 16 minutes on a small ARM node, with Typesense's CPU busy throughout
A search (5 searches against 500 products, M1) about 2 ms about 12 ms: the term is embedded on every search
Typesense memory about 185 MB once per server for the loaded model (an empty server went from 87 MB to 273 MB), plus 1.5 KB of vector per product
First use the Typesense server downloads the model from Hugging Face (about 6 s here); a server with no internet access can't use semantic search

The nightly popularity updates don't re-embed (they change popularity only: 0.2 ms a product), but every product save and stock change re-indexes the whole document, which does. Typesense runs the embedding on the same CPU that answers searches, so on a shared node a big rebuild slows every site's searches while it runs: switch it on for a large catalogue outside trading hours.

How a search works. Only a typed search on /search (or within a category) is hybrid, and only when the term is worth embedding: not under 3 characters ("xl", "tv": a sentence model has nothing to go on) and not a single token with a digit ("M8", "10mm", "SKU-1042": a part number or size is an exact lookup, where neighbours in meaning are noise). Browsing a category, a category defined by a search query (its membership stays what its keywords say), filter-value landing pages and the search-box suggestions (one search per keystroke, on partial words) stay keyword-only. For a hybrid search MerchandisingQueryService adds the embedding to query_by (with a weight: Typesense wants one per field, and it doesn't affect the ranking) and sends vector_query=embedding:([], alpha: 0.3, distance_threshold: 0.7). Typesense returns every keyword match plus the nearest products by meaning within the threshold (it caps these: 100 in our tests), ranked by rank fusion. The facet, price, combination and category-count queries of the page use the same fields, so a count is still what a click finds.

Ranking. Featured and the merchandiser's rules need no change: in a hybrid search Typesense's _text_match sort field is the fused score, so _text_match:desc,_eval(inStock:true):desc,popularity:desc orders by fused relevance, then stock, then sales, and a pin's _eval tier still comes first (checked against Typesense 29: pinning Rigger boot puts it first for "footwear"). A sort the shopper picks (price, newest, best selling) orders the hybrid result set by that.

If it isn't ready. Switching the setting on takes effect for searches at once, but the index only gets its embeddings when it is rebuilt (below). Until then Typesense rejects the hybrid search (Malformed vector query string: could not find a field named 'embedding'); the query layer retries by keyword, sends again only the category counts that failed, logs it, and stays keyword-only for that site for a minute before trying again. The same happens if Typesense can't embed the term (model not downloaded, out of memory). Shoppers see keyword results, never an error.

Switching on and off. The setting is part of the site's index schema: the worker checks every site's schema every ten minutes (badger.search.schema-check.interval-ms, and at startup), and a site whose setting no longer matches its index is rebuilt behind its alias with no downtime, so semantic results start within about ten minutes plus the rebuild time. Other sites' schemas don't change and they are not rebuilt. To roll back, switch it off: searches are keyword-only at once, and the next check rebuilds the index without embeddings, which frees the memory and the per-save CPU. Search > Overview's rebuild button does either straight away.

How it works

  • Signals in the index. Each product document carries inStock (see Stock), popularity (int32), rating (out of 100) and reviewCount (int32, 0 without reviews). The order is a Typesense sort_by, built by RankingSort.featured (commerce-core, search.query). Typesense allows three sort fields, so:
no ranking:   _text_match:desc,_eval([(inStock:true && reviewCount:>=3 && rating:>=80):2,(inStock:true):1]):desc,popularity:desc
with ranking: _eval([(skuId:=`A`):7,(skuId:=`B`):6,
                     (skuId:=[`C`] && inStock:true):5,(skuId:=[`C`] && inStock:false):4,
                     (skuId:!=[`A`,`B`,`C`,`D`] && inStock:true):3,(skuId:!=[`A`,`B`,`C`,`D`] && inStock:false):2,
                     (skuId:=[`D`] && inStock:true):1]):desc,_text_match:desc,popularity:desc

(pins A, B; boost C; bury D). The ranking's clauses don't overlap, so each product scores one tier. Without a ranking a well-reviewed product in stock matches both stock clauses; it scores at least 2 however Typesense combines them, so it still comes first. Best selling is popularity:desc,_text_match:desc. - Storing popularity. ProductPopularityService (commerce-core, search.popularity) sums units per SKU with one Mongo aggregation per site (OrderService.unitsSoldBySku: match on siteId and submitted using the {siteId, submitted} index, unwind the lines, group; one row per SKU sold, never the orders themselves), matches the SKUs to products 500 at a time, and keeps the result in the productPopularity collection (one document per product that sold, keyed by catalogue and product). It is a collection of its own rather than a field on the product so that recomputing it doesn't touch products: no product save events, reindexes, cache evictions or lastModifiedDate changes. Derived from orders, it isn't part of a site transfer. - Writing only what changed. The job compares the new values with the stored ones and sends only the changes (including back to 0) to Typesense as partial updates (import with action=update, 500 a batch), to the live collection and any being rebuilt, then stores them. A batch Typesense refuses isn't stored, so the next run tries it again. A full index build and a product's own reindex read the stored value, so the index agrees with the store whichever ran last. - Older indexes. popularity arrived with index revision 7 (PRODUCT_INDEX_REVISION), so every site rebuilds once after the deploy. Until it has, a query Typesense refuses for sorting on popularity is retried with the old price tie-break, and Best selling falls back to Featured. reviewCount arrived with revision 8: until a site's index has it, Featured goes without the review lift and Top rated sorts by rating alone.

Indexing Pipeline

Mongo write  ──►  ApplicationEvent  ──►  RabbitMQ  ──►  Worker  ──►  Typesense
                                                                          ▲
                                          Nightly Reconciliation ─────────┘
  • Event-driven updates: product saves, collection edits, taxonomy changes, and merchandising tree mutations all flow through RabbitMQ to a worker that updates Typesense.
  • Reconciliation: a nightly job re-asserts state against Mongo, catching any missed events and removing orphans.
  • Schema migration via alias swap: the worker records a fingerprint of the index schema on each collection. When a deploy changes the schema (a new field, or an option such as stemming), a new versioned collection is built in the background at worker startup and the stable alias is repointed atomically. Zero downtime; if the build fails the old index stays live.

See Search Architecture for the full pipeline detail.

Administration

Operators interact with search through the admin UI:

  • Merchandising → Trees — create and manage merchandising trees, mark one primary.
  • Tree editor — author nodes, choose backing types, configure SEO and facets, preview matching products before indexing.
  • Ranking (tree editor) and Search Ranking — pin, boost and bury products on a category or for a search term (Pins, Boosts and Buries).
  • Taxonomy admin — manage the classification that drives projections and facets.
  • Collection admin — manual collections continue to be authored as before.
  • Reindex search (Merchandising → Trees) — rebuilds the product and content indexes from scratch into fresh collections and swaps them in with no downtime. Use it if search results look wrong; it is never needed after a deploy, which migrates the schema by itself.

The platform handles index lifecycle, schema migrations, breadcrumb computation, alias swaps, and node resolution. Outside the button above, none of these are operator concerns.

The trees can also be managed without the admin UI:

  • REST admin API (Admin Category Trees in the API reference). Trees: GET/POST /v1/admin/merchandising/trees, GET/PUT/DELETE /v1/admin/merchandising/trees/{treeId}, POST .../{treeId}/primary. Categories: GET/POST /v1/admin/merchandising/trees/{treeId}/nodes (flat, parent-ordered), GET/PUT/DELETE /v1/admin/merchandising/nodes/{nodeId} (delete takes the subtree), POST .../{nodeId}/move (parentNodeId, null for the top level, and a 0-based position) and GET .../{nodeId}/preview (a page of its products). Conversion: POST /v1/admin/merchandising/trees/from-collections and POST .../{treeId}/collection-matches. A node's backing is a union discriminated by type (manualCollection, taxonomyProjection, virtualQuery, manualList, group), the same names the domain stores; canonicalPath, breadcrumbChain and childNodeIds are read-only. The REST Product carries primaryCategoryNodeId. Validation is MerchandisingTreeService's (createTree, updateTree, createNode, updateNode, moveNode): names, unique tree slugs, URL names unique among siblings and free of / and spaces, a backing with what it needs, parents in the same tree and no move under itself; failures are 400, a tree or category outside the site 404. Rankings and landing-page rules keep their own endpoints (Pins, Boosts and Buries, Catalogue SEO).
  • MCP: merchandisingTrees and manageMerchandisingTrees, and manageProducts mainCategory (see MCP tool conventions).

The older /v1/admin/catalogues/{catalogueId}/merchandising/... group in the spec (Merchandising Admin: taxonomies with nodeType, taxonomyRef and predicates) predates the trees and was never implemented: nothing serves it. It is marked deprecated.

Search Term Analytics

The platform records what visitors search for on each site, so merchants and AI agents can see the most popular searches and the searches that found nothing (gaps in the range, missing synonyms, products that need better names). Zero-result searches feed Search Synonyms: its AI suggestions start from them, and the dashboard links each one to the synonyms page. It is built into the platform rather than using Typesense analytics, which isn't configured and would mix tenants in one store.

What is recorded. A search is counted when a visitor lands on the results page, /search?q=…, with a fresh query: the first page, with no facet, sort, tab or content-tag refinement. Paging, sorting and filtering the same search don't count it again. Following the Category facet to a search within a category (/c/<category>?q=…) is a refinement and isn't counted either. The search-box dropdown (/search/suggest) is not recorded, because it fires as the visitor types; pressing Enter or choosing "see all results" takes them to /search, which is. Clicking a product or category straight from the dropdown isn't counted. The result count is products plus, when content search is on, matching pages and posts.

Privacy. Only the normalised term, a daily count, a zero-result count and the latest result count are stored. No user id, session id, IP address or user agent is kept. Terms are normalised (trimmed, lower-cased, whitespace collapsed, capped at 100 characters) and dropped entirely when they look like personal data: an email address, a run of 8 or more digits, or a phone-like sequence of 9 or more digits. These checks run on the whole entry, before it is truncated.

Storage and retention. SearchTermAnalyticsServiceImpl (commerce-core, search.analytics) buffers searches in memory, keyed by site, day and term, and writes them every 10 seconds (badger.search-analytics.flush-interval-ms) and at shutdown, as one unordered bulk of $inc upserts into the searchTermDailyStats Mongo collection. The search request itself only does a config lookup and a map update. Each document is one term on one site on one day (siteId, day as yyyy-MM-dd in the site's time zone, term, count, zeroResultCount, lastResultCount, lastSearchedAt), with a unique index on (siteId, day, term), so several web nodes add to the same bucket. A TTL index on expireAt deletes each bucket 90 days after its day. The buffer holds at most 20,000 distinct entries between flushes. Past that, new terms are dropped (repeats still count), so a flood of junk searches can't exhaust the heap. A failed write is retried on the next flush.

Switching it off. The search-term-tracking-enabled site config key (search-config, default on) stops new recording for a site. Searches already recorded stay until they expire.

Click-through and conversion. The same daily buckets also count what each search led to: clicks (results pages from which a shopper opened a product), addToBaskets (products added to a basket within 30 minutes of the search), orders (orders containing such a product, placed within a day of the add) and revenue (those products' line totals in those orders, in minor units). Reports divide each by searches, so terms of any size compare. It is switched by search-click-tracking-enabled (search-config, default on), and needs search-term-tracking-enabled on too. How it works, with no extra request from the page and nothing stored per shopper:

  1. Every /search results page with products gets an sr reference (SearchClickTracker.refFor, web-mvc). SearchRefCodec makes it: the kind of listing (a /search term; category pages get references of their own for product engagement, which term analytics ignores), the normalised term and the time of the search, encrypted and authenticated with AES-GCM under a key derived from the per-deployment storefront secret (badger.security.user-cookie-key), with the site id as associated data. So it is opaque (a shared product link doesn't show what its sharer searched for), can't be forged or moved to another site, is different for each results page (a fresh nonce) and is only accepted for 30 minutes. Terms that look like personal data never get one. A small inline script (fragment/search-click-ref, included by every theme's searchResults.html and merchandisingNode.html) adds ?sr= (and the product's position, sp) to the product links on the page and a hidden sr field to its add-to-basket forms. It sends nothing itself.
  2. ProductController passes the request and the product's SKU to SearchClickTracker.recordClick. A valid /search reference counts one click for its term, once per results page: references already seen are remembered in a bounded in-memory set (10,000, expiring with the window), so a reload or a second product from the same page doesn't count again. Requests that BotDetectionService flags (Cloudflare bot score, user-agent list) are ignored.
  3. BasketController (POST /basket) calls SearchClickTracker.recordAddToBasket once the product is in the basket. The reference comes from the posted sr field (a quick add on the results page) or, failing that, from the sr on the same-host page that posted the form (its Referer, the product page). SearchTermAnalyticsService.recordAddToBasket counts the add (once per product and term) and notes {p: productSkuId, t: term, at} in the basket's orderProperties.searchAttribution, at most 20 products, the latest search winning a product.
  4. OrderServiceImpl.submitOrder, after a successful submit, calls recordOrderPlaced: one order per term whose products are in the order (entries older than 24 hours are dropped), with their line totals as revenue. The attribution is then removed from the order in memory and with a targeted $unset on the stored order, so a placed order keeps no search terms. Analytics never fails a page, a basket or a checkout.

Clicks and sales are counted on the day they happen, so a bucket can hold clicks but no searches; the top-search report ignores those buckets so they don't hide the latest result count. They go through the same buffer, bound and bulk $inc flush as searches. Nothing new is logged beyond site and order ids. The rarelyClicked flag on a term (SearchTermPerformance) marks at least 10 searches in the range, a latest search that found something, and under 10% clicked: results that don't match what shoppers meant, so candidates for a synonym or a search rule. Clicks only count from when the feature is deployed, so older searches look unclicked at first.

Where to see it. The admin dashboard has a Searches tab next to the page-view tabs. It shows the top 20 searches and the top 20 zero-result searches for the last 30 days, each with the result count of the latest search. The admin Search → Analytics page (/admin/search/analytics, see Search section) adds the click, basket and order rates, a "searched often, rarely clicked" list linked to Synonyms and Rules with the term filled in, and a per-term table. AI agents use the MCP siteTraffic tool's topSearches, zeroResultSearches and searchPerformance actions, with optional from/to (yyyy-MM-dd, default the last 30 days, clamped to the 90-day retention) and limit (default 10, max 50). Every read goes through SearchTermAnalyticsService with the caller's SiteContext, and every query filters on its siteId, so a tenant only sees its own terms.

Per product. The same references and hooks also count each product's impressions, position, clicks, views, adds and orders per category and search term: see Product Engagement.

Current State and Roadmap

Category pages (/c/**), search results and autocomplete are served from Typesense. Live: facets (stock- and variant-aware, swatches, number ranges, ratings, searchable long lists), price, category navigation, search within a category, synonyms, search rules (pins, boosts, buries, redirects, banners), relevance from sales and stock with per-site field weights (see Relevance), opt-in semantic search, brand and colour landing pages, phone quick filters, search analytics with click-through and conversion, and zero-downtime index rebuilds. What comes next is in the search and navigation roadmap (kept with the code, not published): product views and click-through as relevance signals, and facet usage per query.