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 with a FullSearch scope, 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
20
21
22
23
24
25
26
27
28
29
30
31

User searches "Running Shoes"
         │
         ▼
┌──────────────────────────┐
│   Excluded Phrases       │ ◄── Is this phrase excluded from redirects?
│   (HashSet lookup)       │
└────────────┬─────────────┘
             │ Not excluded
             ▼
┌──────────────────────────┐
│   Phrase Mappings        │ ◄── Is there a manual mapping for this phrase?
│   (Dictionary lookup)    │
└────────────┬─────────────┘
             │ No mapping found
             ▼
┌──────────────────────────┐
│   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:

Excluded search phrases

Certain search phrases can be excluded from ever triggering a redirect. This is useful for generic or high-traffic terms like "sale", "new arrivals", or "clearance" where a redirect would be disruptive to the browsing experience.

When a user searches for an excluded phrase, the redirect check is skipped entirely — the search proceeds as a normal search regardless of whether the phrase matches a category, product, or custom attribute.

Excluded phrases are matched case-insensitively.

Phrase mappings

Phrase mappings provide a manual override for redirect behavior. A phrase mapping links a specific search phrase to a category or custom attribute value, bypassing the normal redirect resolution logic.

This is useful when:

• The automatic redirect resolves to the wrong target (e.g., a phrase matches multiple categories)
• A desired redirect cannot be detected automatically (e.g., mapping "sneakers" to the "Running Shoes" category)
• Marketing campaigns require specific redirects for branded search terms

Each phrase mapping specifies:

Resolution priority

When a search phrase is received, the redirect system evaluates in this order:

1. Excluded phrases — if the phrase is excluded, no redirect is triggered
2. Phrase mappings — if a manual mapping exists, use it directly
3. Automatic redirect resolution — standard category/product/SKU/attribute matching

Search response

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

 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
}

Full search vs. quick search

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.

Both excluded phrases and phrase mappings are configured per segment and go through the publication flow.

See Handling Redirects for frontend implementation details and API reference.