Skip to content

Redirects

Redirects allow Ecommerce Search to detect when a search phrase exactly matches a known entity — such as a category name, product name, SKU, or custom attribute — and instruct the frontend to navigate the user to a dedicated page rather than displaying generic search results.

Why redirects?

Many shops invest significant effort in optimizing category landing pages with curated branding, boost configurations, quick filters, and subcategory navigation. However, when a user searches for "running shoes", the search result page returns a broad result set — missing all the curated work done on the "Running Shoes" category page.

Redirects bridge this gap by sending users directly to these optimized pages when their search intent clearly maps to a specific category or product.

How it works

When a user searches, Ecommerce Search performs a redirect check before executing the full search:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
User searches "Running Shoes"
         │
         ▼
┌──────────────────────────┐
│   Possible Hit Cache     │ ◄── Fast pre-check: could this phrase match?
│   (bloom filter)         │
└────────────┬─────────────┘
             │ Possible match
             ▼
┌──────────────────────────┐
│   Redirect Resolver      │ ◄── Validates against actual product data
│   (cached + ES)          │
└────────────┬─────────────┘
             │ Confirmed match
             ▼
┌──────────────────────────┐
│   Return action object   │
│   with redirect filters  │
└──────────────────────────┘

The redirect check only runs when:

  • A search phrase is present
  • The search is a pristine search (no user-applied filters or facets)
  • Redirect settings are enabled for the segment

Redirect types

Category redirect

When enabled, if the search phrase exactly matches a category name that exists uniquely in the product catalog, the response includes a redirect to that category.

Example: Searching "Running Shoes" when a category named "Running Shoes" exists with a unique category path and contains at least one product.

Product name redirect

When enabled, if the search phrase exactly matches a product name and resolves to exactly one unique product, the response includes a redirect to that product detail page (PDP).

SKU ID / SKU number redirect

When enabled, if the search phrase matches a SKU ID or SKU number and resolves to exactly one unique product, the response includes a redirect to that product.

Custom attribute redirect

Custom string attributes from the product catalog can be configured as redirect sources. For example, if a "brand" attribute is configured, searching for "Nike" could redirect to a brand-filtered product listing page (PLP).

Validation rules

Before a redirect is triggered, it must pass validation:

Redirect type Validation rule
Category Category name must be globally unique (only one category path) and contain at least one product
Product name Must resolve to exactly one unique product ID (variants are allowed)
SKU ID Must resolve to exactly one unique sku
SKU number Must resolve to exactly one unique sku
Custom attribute Must resolve to at least one product with matching attribute value

Search response

When a redirect is detected, the search response includes an action object containing the redirect filters the frontend should apply.

Full search response with redirect

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "action": {
        "redirect": {
            "filters": {
                "CategoryIds": "42"
            }
        }
    },
    "originalPhrase": "running shoes",
    "usedPhrase": "running shoes",
    "products": [],
    "totalProducts": 0
}
Search type Redirect behavior
Full search Returns only the action object — no products, content, or other results. The frontend should navigate immediately.
Quick search Returns the action object and limited results. The redirect filters are applied internally, so the returned products match the redirect target.

Configuration

Redirect settings are configured per segment through the Admin API or the admin UI. Changes go through the publication flow, meaning they must be published before they take effect in live searches.

Setting Description
categoryEnabled Enable redirects when the search phrase matches a category name
productNameEnabled Enable redirects when the search phrase matches a product name
skuIdEnabled Enable redirects when the search phrase matches a SKU ID
skuNoEnabled Enable redirects when the search phrase matches a SKU number
customAttributes List of custom string attributes to enable for redirects

See Handling Redirects for frontend implementation details.