Redirects

Redirects allow Ecommerce Search to detect that a search phrase points at a specific destination — either a known entity in the product catalog, such as a category name, product name, SKU, or custom attribute, or a URL chosen by an administrator — and instruct the frontend to navigate the user there 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.

Not every search intent has a destination in the catalog, however. Phrases such as "opening hours", "customer service", "store finder", and "delivery terms" refer to pages that sit around the catalog rather than inside it, and such a page may even live on another domain, such as a hosted support portal. A URL redirect covers this gap by pointing a phrase directly at a relative or absolute URL.

How it works

When a user searches with a FullSearch or QuickSearch scope, Ecommerce Search performs a redirect check before executing the 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 the redirect target │
└──────────────────────────┘

A phrase mapping short-circuits the remaining steps. A mapping to a URL is returned straight away, because a URL has nothing to verify against the product data.

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 — at least one redirect field is enabled, or URL redirects are

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).

URL redirect

When enabled, a search phrase can redirect to a URL instead of a page derived from the product catalog:

• A relative URL points at a page on the shop itself, such as /campaign/black-friday. The frontend routes to it within the storefront.
• An absolute URL points at a page outside the shop, such as https://external-customer-support/faq. The frontend navigates away from the storefront.

The distinction is carried in the search response so the frontend can pick the right kind of navigation without inspecting the URL itself.

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, and regardless of whether it is mapped to a URL.

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 redirect target — a category, a custom attribute value, or a URL — 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)
• The phrase has no destination in the catalog at all and should lead to a URL instead (e.g., mapping "opening hours" to /openingHours)
• Marketing campaigns require specific redirects for branded search terms

Each phrase mapping specifies:

Exactly one target is set per mapping: either the field name and field value ID, or the URL.

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 describing the redirect. The redirectType property states which kind of redirect fired, and exactly one payload member is populated to match:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
    "action": {
        "redirect": {
            "redirectType": "Filter",
            "filters": {
                "CategoryIds": "42"
            }
        }
    },
    "originalPhrase": "running shoes",
    "usedPhrase": "running shoes",
    "products": [],
    "totalProducts": 0
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "action": {
        "redirect": {
            "redirectType": "RelativeUrl",
            "relativeUrl": "/openingHours"
        }
    },
    "originalPhrase": "opening hours",
    "usedPhrase": "opening hours",
    "products": [],
    "totalProducts": 0
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "action": {
        "redirect": {
            "redirectType": "AbsoluteUrl",
            "absoluteUrl": "https://external-customer-support/faq"
        }
    },
    "originalPhrase": "customer service",
    "usedPhrase": "customer service",
    "products": [],
    "totalProducts": 0
}

Full search vs. quick search

Redirect behavior depends on both the search type and the kind of redirect:

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.