Handling Redirects

When redirects are enabled, the Unified Search response may include an action object instructing the frontend to navigate the user to a specific page instead of displaying search results.

Detecting a redirect

Check for the presence of action.redirect in the search response. When present, the filters dictionary contains the field name and target identifier for the 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
}

Filter keys

The filters dictionary maps field names to target identifiers. The key tells you the type of redirect:

Implementation

The general pattern for handling redirects is:

1. Perform the search request
2. Check if action.redirect exists in the response
3. If present, map the filter to a URL in your application and navigate

 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
32
33
34
35
36

async function handleSearch(phrase) {
    const response = await fetch('/api/search', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            segmentId: 'b2c-dk-en',
            scopeId: 'full-search',
            phrase: phrase
        })
    });

    const result = await response.json();

    // Check for redirect action
    if (result.action?.redirect) {
        const url = mapFiltersToUrl(result.action.redirect.filters);
        window.location.href = url;
        return;
    }

    // No redirect — display search results normally
    displayResults(result);
}

function mapFiltersToUrl(filters) {
    if (filters.CategoryIds) {
        return `/category/${filters.CategoryIds}`;
    }
    if (filters.ProductId || filters.SkuId || filters.SkuNo) {
        const productId = filters.ProductId || filters.SkuId || filters.SkuNo;
        return `/product/${productId}`;
    }
    // Custom attribute — build a filtered PLP URL
    const [attribute, value] = Object.entries(filters)[0];
    return `/products?${attribute}=${encodeURIComponent(value)}`;
}

Full search vs. quick search

Redirect behavior differs depending on the search type:

For full search, always check for redirects before rendering results. For quick search, you can show a preview of matching products while offering a link to the redirect target.

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

{
    "action": {
        "redirect": {
            "filters": {
                "CategoryIds": "42"
            }
        }
    },
    "products": [
        { "id": "prod-1", "name": "Trail Runner Pro" },
        { "id": "prod-2", "name": "Road Runner Lite" }
    ],
    "totalProducts": 87,
    "originalPhrase": "running shoes",
    "usedPhrase": "running shoes"
}

When redirects do not trigger

Redirects are skipped when:

• No search phrase is provided
• The user has applied filters or facets (not a pristine search)
• The search phrase does not match any configured redirect source
• The matched entity is ambiguous (e.g., a category name exists in multiple category paths)
• No products exist for the matched entity
• For PDP redirects: more than one unique product matches

Admin API reference

Redirect settings are managed per segment and go through the publication flow.

Get current settings

1

GET /segment/{segmentId}/redirect-settings

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

{
    "categoryEnabled": true,
    "productNameEnabled": false,
    "skuIdEnabled": true,
    "skuNoEnabled": false,
    "customAttributes": [
        {
            "fieldName": "brand",
            "displayName": "Brand"
        }
    ]
}

Update settings

1

POST /segment/{segmentId}/redirect-settings

1
2
3
4
5
6
7

{
    "categoryEnabled": true,
    "productNameEnabled": true,
    "skuIdEnabled": true,
    "skuNoEnabled": false,
    "customAttributes": ["brand"]
}

Response: 204 No Content

Get available custom attributes

1

GET /segment/{segmentId}/redirect-settings/available-attributes

Returns all string-type product attributes that can be used for redirect configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[
    {
        "fieldName": "brand",
        "displayName": "Brand"
    },
    {
        "fieldName": "material",
        "displayName": "Material"
    }
]

Error responses

Migration from external redirects

If you currently handle redirects outside of Ecommerce Search (e.g., in a middleware or frontend layer):

1. Enable redirect settings for the relevant segment via the Admin API
2. Publish the segment to activate the settings
3. Verify using the Playground in the admin UI to test specific search phrases
4. Update your search handler to check for action.redirect in responses
5. Remove external redirect logic once ECS-native redirects are confirmed working

Troubleshooting