Search & Discovery

One shopper’s discovery session, from the search box to a priced product card. A search matches, comes back empty, is filtered, or is paged; a recommendation rail is served directly or falls back; a price resolves differently in New York, London, and Berlin. Every shape below is captured from a live call against the canonical test store. The calls are read-only and run with the publishable client in the browser, except recommendations, which run server-side with the secret client (a publishable key returns 403). Workflow Examples has the client setup. The shopper is hunting for a Samsung Galaxy Watch 6 (0186665f-f0a1-4c79-976a-919b5b1c2daa, variant e98631a9-…, $299), which carries forward through every surface.

1. Searching the catalog

Two search surfaces answer different questions. Both return product ids and relevance scores rather than full product objects, so the cards are hydrated from the ids (step 5).

1a. Text search (keyword) — a match

searchProducts matches the literal query against product names and attributes. It is exact and fast, which suits a search box where the shopper types a brand or model. Publishable key.

const results = await storefront.search.searchProducts({ q: 'headphones' });

Response

{
  "query": "headphones",
  "results": [
    { "productId": "69fbb1fe-6b96-4e7b-b86d-07c3799aa626", "score": 1, "matchReason": "Text match" }
  ],
  "totalResults": 1
}

1b. Text search — an empty result

A mistyped query, or one for something the store doesn’t stock, still succeeds with 200: the same envelope comes back with an empty results array and totalResults: 0. There is no error to catch, so an empty state branches on results.length.

const miss = await storefront.search.searchProducts({ q: 'zxqwerty' });
// → miss.results.length === 0 — render "no results", NOT an error

Response

{
  "query": "zxqwerty",
  "results": [],
  "totalResults": 0
}

1c. Semantic search (natural language)

semanticSearch matches the meaning of a conversational query against product meaning using AI embeddings, rather than literal keyword overlap, which fits a shopper who describes what they want (“wireless earbuds for the gym”) instead of naming it. Each hit carries a similarity score; minScore sets the floor (default 0.3) and limit caps the count.

const semantic = await storefront.search.semanticSearch({
  requestBody: { query: 'wireless earbuds for the gym', limit: 8, minScore: 0.2 },
});

Response

{
  "query": "wireless earbuds for the gym",
  "results": [
    { "productId": "f4992a40-38a1-4ebd-9390-3ecfb9d10093", "score": 0.89 },
    { "productId": "f6a2629e-f899-4615-b17a-e78e2e4c35a4", "score": 0.88 },
    { "productId": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8", "score": 0.85 },
    { "productId": "69fbb1fe-6b96-4e7b-b86d-07c3799aa626", "score": 0.83 },
    { "productId": "3422935b-88ee-43ad-a7df-c03161a35cb4", "score": 0.81 }
  ],
  "totalResults": 50
}

totalResults is the size of the candidate set considered, not the number returned — here 50 products were ranked and the top 8 above minScore came back. A higher minScore tightens relevance, a lower one widens the net. Semantic hits carry a score but no matchReason, which is a text-search field.

The two surfaces above search the index. A results grid usually reads the catalog directly instead: listProducts takes a search term, a categoryId filter, and cursor paging in one call, and returns full product rows rather than ids. This is the shape behind a “Headphones → Sony” filtered grid.

const page1 = await storefront.products.listProducts({
  search: 'sony', limit: 3,
});
// → page1.products[0].name === 'Sony WH-1000XM4', category_name 'Audio & Headphones'

Each product row carries the default variant inline (variant_id, sku, price, stock) plus category_name/subcategory_name, so the grid needs no second call. Paging passes pagination.next_cursor back as cursor:

const grid = await storefront.products.listProducts({ limit: 3, fields: 'name,price,sku' });

Response

{
  "products": [
    { "name": "Samsung Galaxy Watch 6", "price": 299, "sku": "SAM-WATCH-6-44-0186" },
    { "name": "Dell XPS 13", "price": 1199, "sku": "DEL-XPS-13-068a" },
    { "name": "Everyday Commuter Backpack", "price": 89, "sku": "API-BACKPACK-01-0c49" }
  ],
  "pagination": {
    "limit": 3,
    "next_cursor": "MGM0OThhYzItNGI3Ny00YjAzLWE5YjgtZGJkNDY2MWVmYTU0",
    "has_more": true
  }
}

// has_more === true → fetch the next page with the opaque cursor
const page2 = await storefront.products.listProducts({
  limit: 3, cursor: grid.pagination.next_cursor,
});
// → when has_more === false, next_cursor is null and you've reached the end

Both search surfaces return ids and scores only. Cards hydrate by passing each id to storefront.products.getProduct({ id }), or by quoting prices for the whole result set at once with storefront.pricing.getProductPrices(...) (step 4). fields= trims the payload to the columns a grid renders.

1e. Browsing by brand — a featured-brands row into a brand page

Brand is a second axis alongside categories. listBrands returns the catalog’s distinct brands with a product count, most products first, which is the shape a featured-brands strip renders from; a click passes the brand to listProducts({ brand }).

// 1. The brands strip — take the top 5 for a featured row.
const { brands } = await storefront.products.listBrands();
const featured = brands.slice(0, 5);
// → [ { brand: 'Samsung', product_count: 12 }, { brand: 'Apple', product_count: 9 }, ... ]

// 2. Shopper taps "Samsung" → the brand's product grid (case-insensitive exact match).
const { products } = await storefront.products.listProducts({
  brand: 'Samsung',
  limit: 20,
  fields: 'id,name,price,thumbnail_url',
});

brand combines with categoryId/search — e.g. listProducts({ brand: 'Samsung', categoryId }) for “Samsung in Audio”. On a marketplace operator key, listBrands aggregates brands across all merchants; pass storeId to scope the strip to one merchant’s shop page.

2. Recommendation rails — every type, and the fallback

Recommendations back the “you might also like” and “frequently bought together” rails. This is the one discovery call that is secret-key only, running on your server (a publishable key returns 403). One method, getRecommendations, serves every rail through the type field, and every response shares the same { type, recommendations[], fromCache, computedAt } envelope, each item carrying productId, score, and reason. A rail is never empty, because the engine cascades through fallbacks: a cold product with no co-purchase or similarity signal falls back bundle → also-bought → similar → trending → random. An also-bought rail on a product with no purchase history therefore comes back with reason strings reading “Similar product…” or “Trending #1…” — the requested type had nothing behind it and the engine served the next-best signal it had, under the same envelope. Each rail below is anchored on the Watch the shopper is viewing (0186665f-…).

2a. Similar products

// On your server — secret client
const similar = await server.recommendations.getRecommendations({
  requestBody: { type: 'similar', productId: '0186665f-f0a1-4c79-976a-919b5b1c2daa', limit: 5 },
});

Response

{
  "type": "similar",
  "recommendations": [
    { "productId": "3422935b-88ee-43ad-a7df-c03161a35cb4", "score": 0.87, "reason": "Similar product based on description and attributes" },
    { "productId": "068aa59d-1adf-4685-adf5-9793b1ffb9c9", "score": 0.82, "reason": "Similar product based on description and attributes" },
    { "productId": "7c378f6b-6c4b-4608-882e-6b6c6cc0a3e8", "score": 0.81, "reason": "Similar product based on description and attributes" },
    { "productId": "37ecdce9-e95d-445c-9908-9ffea7f5f419", "score": 0.8, "reason": "Similar product based on description and attributes" },
    { "productId": "a45fae07-761e-453c-9c4c-cf88cf24a9f7", "score": 0.8, "reason": "Similar product based on description and attributes" }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:53:58.158Z"
}

2b. Frequently bought together (`also-bought`)

Ranks products co-purchased with the anchor. Without co-purchase history the engine falls back to the similarity signal, so the reason strings are the similar rail’s and fromCache is false — this rail was computed fresh.

const alsoBought = await server.recommendations.getRecommendations({
  requestBody: { type: 'also-bought', productId: '0186665f-f0a1-4c79-976a-919b5b1c2daa', limit: 5 },
});

Response

{
  "type": "also-bought",
  "recommendations": [
    { "productId": "3422935b-88ee-43ad-a7df-c03161a35cb4", "score": 0.87, "reason": "Similar product based on description and attributes" },
    { "productId": "068aa59d-1adf-4685-adf5-9793b1ffb9c9", "score": 0.82, "reason": "Similar product based on description and attributes" },
    { "productId": "7c378f6b-6c4b-4608-882e-6b6c6cc0a3e8", "score": 0.81, "reason": "Similar product based on description and attributes" }
  ],
  "fromCache": false,
  "computedAt": "2026-06-20T10:53:58.158Z"
}

2c. Bundle pairings (`bundle`) — complements, not substitutes

bundle surfaces complementary products that pair with the anchor — a case for the watch — rather than alternatives to it. The reason carries the co-purchase rate, here 0%, so these are ranked by complementarity alone, and the scores near 0.32 are what a pairing suggestion scores rather than a close substitute.

const bundle = await server.recommendations.getRecommendations({
  requestBody: { type: 'bundle', productId: '0186665f-f0a1-4c79-976a-919b5b1c2daa', limit: 5 },
});

Response

{
  "type": "bundle",
  "recommendations": [
    { "productId": "068aa59d-1adf-4685-adf5-9793b1ffb9c9", "score": 0.33, "reason": "Pairs well together (0% co-purchased)" },
    { "productId": "7c378f6b-6c4b-4608-882e-6b6c6cc0a3e8", "score": 0.32, "reason": "Pairs well together (0% co-purchased)" },
    { "productId": "37ecdce9-e95d-445c-9908-9ffea7f5f419", "score": 0.32, "reason": "Pairs well together (0% co-purchased)" }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:53:58.158Z"
}

trending and new take no productId, which makes them homepage rails. trending ranks by recent sales velocity, reported as units/day in the reason; new ranks by recency.

const trending = await server.recommendations.getRecommendations({
  requestBody: { type: 'trending', limit: 10 },
});

Response

{
  "type": "trending",
  "recommendations": [
    { "productId": "0186665f-f0a1-4c79-976a-919b5b1c2daa", "score": 1, "reason": "Trending #1 - 2.1 units/day" },
    { "productId": "068aa59d-1adf-4685-adf5-9793b1ffb9c9", "score": 0.2009345794392523, "reason": "Trending #2 - 0.4 units/day" },
    { "productId": "0c498ac2-4b77-4b03-a9b8-dbd4661efa54", "score": 0.2009345794392523, "reason": "Trending #3 - 0.4 units/day" }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:53:58.158Z"
}

const arrivals = await server.recommendations.getRecommendations({
  requestBody: { type: 'new', limit: 5 },
});
// → each item carries reason: "New arrival", scored by recency (1, 0.99, 0.98, …)

Response

{
  "type": "new",
  "recommendations": [
    { "productId": "e99bf2b2-e466-4472-aadc-1a5d99391ad5", "score": 1, "reason": "New arrival" },
    { "productId": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8", "score": 0.99, "reason": "New arrival" },
    { "productId": "f6a2629e-f899-4615-b17a-e78e2e4c35a4", "score": 0.98, "reason": "New arrival" }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:53:58.158Z"
}

2e. Personalized (`personalized`) — for a signed-in shopper

Identify the shopper with a credential header (x-auth-token, x-external-auth, or x-idp-token); the recommendations are keyed to whoever that credential resolves to, not to a customer id in the body. Without a valid credential (or per-shopper signal) it falls back to trending, which is why the reason strings here are the trending ones. The same call returns personalized ranks once the customer’s history builds.

const forYou = await server.recommendations.getRecommendations({
  requestBody: { type: 'personalized', limit: 10 },
  // identify the shopper on the request, e.g. { headers: { 'x-auth-token': token } }
});

Response

{
  "type": "personalized",
  "recommendations": [
    { "productId": "0186665f-f0a1-4c79-976a-919b5b1c2daa", "score": 1, "reason": "Trending #1 - 2.1 units/day" },
    { "productId": "068aa59d-1adf-4685-adf5-9793b1ffb9c9", "score": 0.2009345794392523, "reason": "Trending #2 - 0.4 units/day" },
    { "productId": "0c498ac2-4b77-4b03-a9b8-dbd4661efa54", "score": 0.2009345794392523, "reason": "Trending #3 - 0.4 units/day" }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:53:58.158Z"
}

Asking for a rail on a product that doesn’t exist returns 404. A publishable key on any recommendation call returns 403 — keep these on your server.

2f. Discovery shelves — “Popular now” and a product-page “hot” badge (publishable key)

Where recommendations are personalized and secret-key, Discovery is the non-personalized counterpart that renders straight from the browser: windowed rankings built from live shopper signals — views, cart-adds, view-to-purchase. It is publishable-key and available on every plan. Each call returns { metric, window_hours, products: [{ product_id, score }] }, with cards hydrated through products.getProduct. score is a raw sortable signal — a count, or a ratio for converting — already ordered highest-first.

// A "Popular now" homepage shelf — most-viewed over the last 30 days.
const popular = await storefront.discovery.getMostViewedProducts({ windowHours: 720, limit: 12 });

Response

{
  "metric": "most-viewed",
  "window_hours": 720,
  "products": [
    { "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa", "score": 15 },
    { "product_id": "068aa59d-1adf-4685-adf5-9793b1ffb9c9", "score": 10 },
    { "product_id": "0c498ac2-4b77-4b03-a9b8-dbd4661efa54", "score": 8 }
  ]
}

// A "Trending in carts" strip, and a "Customer favorites" (best-converting) shelf.
const inCarts   = await storefront.discovery.getMostAddedToCartProducts({ windowHours: 168, limit: 8 });
const favorites = await storefront.discovery.getBestConvertingProducts({ windowHours: 720, limit: 8 });

// PDP "hot" badge: fetch the 1-hour most-viewed once per page, badge any product in the list.
const hotNow = await storefront.discovery.getMostViewedProducts({ windowHours: 1, limit: 20 });
const isHot = (productId) => hotNow.products.some((p) => p.product_id === productId);

storefront here uses a publishable key, since Discovery is browser-safe. Allowed windowHours differ per metric — 1|24|168|720 for most-viewed, 24|168 for carts, 168|720 for converting — and an unlisted value returns 400. Discovery covers organic “what’s hot” shelves; Recommendations covers personalized and anchored rails.

3. Capturing browsing behaviour for the `next` rail

The next-item rail sharpens on what the shopper does as they browse. recordEvent logs one event per call against a variant_id (or product_id), grouped by the same session_id the anonymous cart uses. It is publishable-key and safe in the browser, and it is fire-and-forget: it returns 202 immediately without blocking the page. Three event_type values exist, one per shopper action.

3a. `view` — the shopper opens the Watch’s page

await storefront.events.recordEvent({
  requestBody: {
    event_type: 'view',
    variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a',
    session_id: '7c1f0e8a-2b3c-4d5e-9f01-23456789abcd',
  },
});
// → { recorded: true }

Response

{ "recorded": true }

3b. `add_to_cart` — they add it

await storefront.events.recordEvent({
  requestBody: {
    event_type: 'add_to_cart',
    variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a',
    session_id: '7c1f0e8a-2b3c-4d5e-9f01-23456789abcd',
  },
});
// → { recorded: true }

3c. `add_to_wishlist` — or they save it for later

await storefront.events.recordEvent({
  requestBody: {
    event_type: 'add_to_wishlist',
    variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a',
    session_id: '7c1f0e8a-2b3c-4d5e-9f01-23456789abcd',
  },
});
// → { recorded: true }

These events feed the session-sequence model. Once several are logged under one session_id, the next rail (secret key) answers what the shopper is likely to look at next, from what other shoppers viewed after the same sequence:

const next = await server.recommendations.getRecommendations({
  requestBody: { type: 'next', sessionId: '7c1f0e8a-2b3c-4d5e-9f01-23456789abcd', limit: 5 },
});

Response

{
  "type": "next",
  "recommendations": [
    { "productId": "068aa59d-1adf-4685-adf5-9793b1ffb9c9", "score": 0.6, "reason": "Customers viewed this next" },
    { "productId": "0c498ac2-4b77-4b03-a9b8-dbd4661efa54", "score": 0.4, "reason": "Customers viewed this next" }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:53:58.158Z"
}

4. Dynamic, location-aware prices

Search and recommendations return product ids; prices come next, in the shopper’s currency. getProductPrices resolves each product’s display price from the shopper’s location — coordinates (latitude/longitude) or a placeName — matching it to a region and converting from the store’s base currency. USD is the store default here, with GBP and EUR enabled. The same Watch priced from three locations covers every conversion shape.

4a. New York → USD (store base, rate 1)

No conversion happens: display_currency is USD, exchange_rate is 1, and price_breakdown.currency_conversion is null.

const usd = await storefront.pricing.getProductPrices({
  limit: 3, latitude: 40.7128, longitude: -74.006,
});

Response

{
  "products": [
    {
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "name": "Samsung Galaxy Watch 6",
      "category_name": "Wearables",
      "brand": "Samsung",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "sku": "SAM-WATCH-6-44-0186",
      "price": 299,
      "sale_price": null,
      "display_currency": "USD",
      "currency_symbol": "$",
      "base_price": 299,
      "base_currency": "USD",
      "display_price": 299,
      "exchange_rate": 1,
      "price_breakdown": { "base_price": 299, "discounts": [], "final_price": 299, "currency_conversion": null }
    }
  ]
}

4b. London → GBP (rate 0.79)

With placeName: 'London, UK' (or London coordinates) the same product comes back priced in GBP, and currency_conversion is populated with the from/to/rate/converted_amount.

const gbp = await storefront.pricing.getProductPrices({
  limit: 3, placeName: 'London, UK',
});
// → gbp.products[0].display_price === 236.21 · display_currency 'GBP' · exchange_rate 0.79

Response

{
  "products": [
    {
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "name": "Samsung Galaxy Watch 6",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "sku": "SAM-WATCH-6-44-0186",
      "price": 299,
      "display_currency": "GBP",
      "currency_symbol": "£",
      "base_price": 299,
      "base_currency": "USD",
      "display_price": 236.21,
      "exchange_rate": 0.79,
      "price_breakdown": {
        "base_price": 299,
        "discounts": [],
        "final_price": 299,
        "currency_conversion": { "from_currency": "USD", "to_currency": "GBP", "rate": 0.79, "converted_amount": 236.21 }
      }
    }
  ]
}

4c. Berlin → EUR (rate 0.92)

latitude: 52.52, longitude: 13.405 resolves to EUR — the same envelope, different rate and converted_amount.

const eur = await storefront.pricing.getProductPrices({
  limit: 3, latitude: 52.52, longitude: 13.405,
});
// → eur.products[0].display_price === 275.08 · display_currency 'EUR' · exchange_rate 0.92

Response

{
  "products": [
    {
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "name": "Samsung Galaxy Watch 6",
      "variant_id": "e98631a9-7852-4fe8-8efe-988935d5922a",
      "sku": "SAM-WATCH-6-44-0186",
      "price": 299,
      "display_currency": "EUR",
      "currency_symbol": "€",
      "base_price": 299,
      "base_currency": "USD",
      "display_price": 275.08,
      "exchange_rate": 0.92,
      "price_breakdown": {
        "base_price": 299,
        "discounts": [],
        "final_price": 299,
        "currency_conversion": { "from_currency": "USD", "to_currency": "EUR", "rate": 0.92, "converted_amount": 275.08 }
      }
    }
  ]
}

4d. No location → store default (USD)

Without coordinates or a placeName, pricing falls back to the store’s default currency, USD here — the same shape as New York, with no conversion.

const fallback = await storefront.pricing.getProductPrices({ limit: 3 });
// → display_currency 'USD', exchange_rate 1, currency_conversion null

For a single product, storefront.pricing.getProductPrice({ id, placeName: 'Berlin' }) returns a price_range ({ min, max }) on a multi-variant product plus a per-variant display_price. Berlin resolves the Nebula Ceramic Mug to EUR at rate 0.92, turning its $14.99–$15.55 range into €13.79–€14.31, each variant carrying its own converted price_breakdown.

5. Browsing by category

A navigation menu or category landing page starts from listCategories (publishable key), then filters the catalog or pricing by categoryId — the same filter the grid used in step 1d.

const { categories } = await storefront.taxonomy.listCategories();

Response

{
  "categories": [
    { "id": "28186b12-5790-4a50-ab87-a7b70d301d00", "name": "Bags & Accessories", "description": "Handbags, wallets, belts", "active": true, "image": "https://images.unsplash.com/photo-1553062407-98eeb64c6a62?w=800&q=80" },
    { "id": "3310356e-7ca4-4056-93b4-80c612536b5d", "name": "Wearables", "description": "Smartwatches, fitness trackers, wearable tech", "active": true, "image": "https://images.unsplash.com/photo-1434493789847-2f02dc6ca35d?w=800&q=80" }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

Both listProducts and getProductPrices accept a categoryId to scope a catalog read to that category. The Watch lives in Wearables (3310356e-…), the same product this page followed through search, recommendations, behaviour, and pricing:

const wearables = await storefront.pricing.getProductPrices({
  categoryId: '3310356e-7ca4-4056-93b4-80c612536b5d', limit: 20,
});
// → every product in wearables.products has category_name === 'Wearables'

Categories are a fixed, store-wide set. Merchants nest subcategories under them to any depth for deeper navigation; storefront.taxonomy.listSubcategories({ tree: true }) fetches them as a tree, and { rootOnly: true } / { parentId } a single level.

What’s next

A shopper who has found a product continues into the storefront checkout — cart, sign-in, and payment.
Reviews & Messaging opens with the wishlist flow, moving a saved Watch into the cart before the post-purchase surfaces.
Returning customer covers order history, returns, and store credit for a shopper coming back.
Search, recommendations, and pricing all accept a marketplace operator key — see Marketplace.

Overview

Storefront

Marketplace

Integrations

Reference

1. Searching the catalog

1a. Text search (keyword) — a match

1b. Text search — an empty result

1c. Semantic search (natural language)

1d. In-catalog search with a category filter and paging

1e. Browsing by brand — a featured-brands row into a brand page

2. Recommendation rails — every type, and the fallback

2a. Similar products

2b. Frequently bought together (`also-bought`)

2c. Bundle pairings (`bundle`) — complements, not substitutes

2e. Personalized (`personalized`) — for a signed-in shopper

2f. Discovery shelves — “Popular now” and a product-page “hot” badge (publishable key)

3. Capturing browsing behaviour for the `next` rail

3a. `view` — the shopper opens the Watch’s page

3b. `add_to_cart` — they add it

3c. `add_to_wishlist` — or they save it for later

4. Dynamic, location-aware prices

4a. New York → USD (store base, rate 1)

4b. London → GBP (rate 0.79)

4c. Berlin → EUR (rate 0.92)

4d. No location → store default (USD)

5. Browsing by category

What’s next

​1. Searching the catalog

​1a. Text search (keyword) — a match

​1b. Text search — an empty result

​1c. Semantic search (natural language)

​1d. In-catalog search with a category filter and paging

​1e. Browsing by brand — a featured-brands row into a brand page

​2. Recommendation rails — every type, and the fallback

​2a. Similar products

​2b. Frequently bought together (also-bought)

​2c. Bundle pairings (bundle) — complements, not substitutes

​2d. Trending and New — store-wide rails (no anchor)

​2e. Personalized (personalized) — for a signed-in shopper

​2f. Discovery shelves — “Popular now” and a product-page “hot” badge (publishable key)

​3. Capturing browsing behaviour for the next rail

​3a. view — the shopper opens the Watch’s page

​3b. add_to_cart — they add it

​3c. add_to_wishlist — or they save it for later

​4. Dynamic, location-aware prices

​4a. New York → USD (store base, rate 1)

​4b. London → GBP (rate 0.79)

​4c. Berlin → EUR (rate 0.92)

​4d. No location → store default (USD)

​5. Browsing by category

​What’s next

1. Searching the catalog

1a. Text search (keyword) — a match

1b. Text search — an empty result

1c. Semantic search (natural language)

1d. In-catalog search with a category filter and paging

1e. Browsing by brand — a featured-brands row into a brand page

2. Recommendation rails — every type, and the fallback

2a. Similar products

2b. Frequently bought together (`also-bought`)

2c. Bundle pairings (`bundle`) — complements, not substitutes

2d. Trending and New — store-wide rails (no anchor)

2e. Personalized (`personalized`) — for a signed-in shopper

2f. Discovery shelves — “Popular now” and a product-page “hot” badge (publishable key)

3. Capturing browsing behaviour for the `next` rail

3a. `view` — the shopper opens the Watch’s page

3b. `add_to_cart` — they add it

3c. `add_to_wishlist` — or they save it for later

4. Dynamic, location-aware prices

4a. New York → USD (store base, rate 1)

4b. London → GBP (rate 0.79)

4c. Berlin → EUR (rate 0.92)

4d. No location → store default (USD)

5. Browsing by category

What’s next