Skip to content

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.

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
}

Filter keys

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

Filter key Redirect type Target page
CategoryIds Category Product listing page (PLP) filtered by category
ProductId Product name Product detail page (PDP)
SkuId SKU ID Product detail page (PDP)
SkuNo SKU number Product detail page (PDP)
(custom attribute fieldId) Custom attribute PLP filtered by the attribute value

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
Vanilla JavaScript
 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)}`;
}

Note

The mapFiltersToUrl function is specific to your frontend's URL structure. Adapt the URL patterns to match your application's routing.

Redirect behavior differs depending on the search type:

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. Products are fetched using the redirect filters, so they match the redirect target.

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.

Quick search with redirect

When quick search detects a redirect, it follows the redirect internally and returns matching products:

Quick search response
 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 is in the excluded phrases list
  • The search phrase does not match any configured redirect source or phrase mapping
  • 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.

Route migration

All redirect settings endpoints have moved from /redirect-settings to /redirects/settings. If your integration uses the old routes, update them to the new paths below.

Get current settings

1
GET /segment/{segmentId}/redirects/settings
Response
 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}/redirects/settings
Request body
1
2
3
4
5
6
7
{
    "categoryEnabled": true,
    "productNameEnabled": true,
    "skuIdEnabled": true,
    "skuNoEnabled": false,
    "customAttributes": ["brand"]
}

Response: 204 No Content

Note

After updating redirect settings, you must publish the segment for changes to take effect in live search.

Get available custom attributes

1
GET /segment/{segmentId}/redirects/settings/available-attributes

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

Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[
    {
        "fieldName": "brand",
        "displayName": "Brand"
    },
    {
        "fieldName": "material",
        "displayName": "Material"
    }
]

Redirect settings error responses

Status Condition
400 Bad Request Duplicate custom attributes in request, or custom attributes not found in product fields
404 Not Found Segment does not exist
429 Too Many Requests Rate limit exceeded

Excluded phrases API

Excluded phrases prevent specific search phrases from triggering redirects. See Excluded search phrases for the concept overview.

Create an excluded phrase

1
POST /segment/{segmentId}/redirects/excluded-phrases
Request body
1
2
3
{
    "searchPhrase": "sale"
}
Response — 201 Created
1
2
3
4
{
    "excludedPhraseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "searchPhrase": "sale"
}
Status Condition
400 Bad Request Search phrase is empty or already exists (case-insensitive)
404 Not Found Segment does not exist

Get an excluded phrase

1
GET /segment/{segmentId}/redirects/excluded-phrases/{excludedPhraseId}
Response — 200 OK
1
2
3
4
{
    "excludedPhraseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "searchPhrase": "sale"
}

Delete an excluded phrase

1
DELETE /segment/{segmentId}/redirects/excluded-phrases/{excludedPhraseId}

Response: 204 No Content

Search excluded phrases

1
POST /segment/{segmentId}/redirects/excluded-phrases/search
Request body
1
2
3
4
5
6
{
    "query": "sa",
    "orderBy": "SearchPhraseAscending",
    "maxResults": 25,
    "offset": 0
}
Field Type Default Description
query string — Optional filter by phrase substring
orderBy string SearchPhraseAscending SearchPhraseAscending or SearchPhraseDescending
maxResults integer 25 Number of results per page (1–500)
offset integer 0 Number of results to skip
Response — 200 OK
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "excludedPhrases": [
        {
            "excludedPhraseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "searchPhrase": "sale"
        },
        {
            "excludedPhraseId": "9dc45f64-5717-4562-b3fc-2c963f66afa6",
            "searchPhrase": "sample"
        }
    ],
    "totalHits": 2
}

Phrase mappings API

Phrase mappings allow you to manually map a search phrase to a specific redirect target. See Phrase mappings for the concept overview.

Create a phrase mapping

1
POST /segment/{segmentId}/redirects/phrase-mappings
Request body
1
2
3
4
5
{
    "searchPhrase": "sneakers",
    "fieldName": "CategoryIds",
    "fieldValueId": "42"
}
Response — 201 Created
1
2
3
4
5
6
{
    "phraseMappingId": "7ab85f64-5717-4562-b3fc-2c963f66afa6",
    "searchPhrase": "sneakers",
    "fieldName": "CategoryIds",
    "fieldValueId": "42"
}
Status Condition
400 Bad Request Search phrase already exists (case-insensitive), or field name is not a valid redirect field
404 Not Found Segment does not exist

Get a phrase mapping

1
GET /segment/{segmentId}/redirects/phrase-mappings/{phraseMappingId}
Response — 200 OK
1
2
3
4
5
6
{
    "phraseMappingId": "7ab85f64-5717-4562-b3fc-2c963f66afa6",
    "searchPhrase": "sneakers",
    "fieldName": "CategoryIds",
    "fieldValueId": "42"
}

Delete a phrase mapping

1
DELETE /segment/{segmentId}/redirects/phrase-mappings/{phraseMappingId}

Response: 204 No Content

Search phrase mappings

1
POST /segment/{segmentId}/redirects/phrase-mappings/search
Request body
1
2
3
4
5
6
{
    "query": "sneak",
    "orderBy": "SearchPhraseAscending",
    "maxResults": 25,
    "offset": 0
}
Field Type Default Description
query string — Optional filter by phrase substring
orderBy string SearchPhraseAscending SearchPhraseAscending or SearchPhraseDescending
maxResults integer 25 Number of results per page (0–500)
offset integer 0 Number of results to skip
Response — 200 OK
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "phraseMappings": [
        {
            "phraseMappingId": "7ab85f64-5717-4562-b3fc-2c963f66afa6",
            "searchPhrase": "sneakers",
            "fieldName": "CategoryIds",
            "fieldValueId": "42"
        }
    ],
    "totalHits": 1
}

Phrase mapping fields API

These endpoints help discover which redirect fields and values are available for phrase mappings.

Get available fields

Returns redirect fields that can be used as phrase mapping targets. Only category and enabled custom string attributes are returned — product name, SKU ID, and SKU number are not supported for phrase mappings.

1
POST /segment/{segmentId}/redirects/phrase-mappings/fields/available
Response — 200 OK
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[
    {
        "fieldName": "CategoryIds",
        "displayName": "Category",
        "fieldValueType": "Category"
    },
    {
        "fieldName": "brand",
        "displayName": "Brand",
        "fieldValueType": "Values"
    }
]
Field Type Description
fieldName string The field identifier to use in phrase mappings
displayName string Human-readable field name
fieldValueType string Category or Values — indicates the type of values this field contains

Resolve field display names

Resolves field name and value ID pairs to their display names. Useful for showing human-readable labels in the admin UI.

1
POST /segment/{segmentId}/redirects/phrase-mappings/fields/resolve
Request body
1
2
3
4
5
6
[
    {
        "fieldName": "CategoryIds",
        "fieldValueId": "42"
    }
]
Response — 200 OK
1
2
3
4
5
6
7
8
[
    {
        "fieldName": "CategoryIds",
        "fieldValueId": "42",
        "fieldDisplayName": "Category",
        "fieldValueDisplayName": "Running Shoes"
    }
]

Search field values

Searches for available values within a specific redirect field. For category fields, this returns categories with breadcrumb-style details.

1
POST /segment/{segmentId}/redirects/phrase-mappings/fields/{fieldName}/search
Request body
1
2
3
4
5
{
    "phrase": "running",
    "offset": 0,
    "maxResults": 50
}
Response — 200 OK
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "fieldName": "CategoryIds",
    "fieldValues": [
        {
            "fieldValueId": "42",
            "name": "Running Shoes",
            "details": "Sports > Footwear > Running Shoes"
        },
        {
            "fieldValueId": "78",
            "name": "Running Apparel",
            "details": "Sports > Clothing > Running Apparel"
        }
    ],
    "totalHits": 2
}
Field Type Description
fieldValueId string The value ID to use in phrase mappings
name string Display name of the value
details string Additional context (e.g., category breadcrumb path). May be null.

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

Issue Cause Solution
Redirect not triggering Settings not published Publish the segment after changing redirect settings
Redirect not triggering Search has filters applied Redirects only fire on pristine searches (no user-applied filters)
Wrong category redirect Ambiguous category name Ensure category names are unique across category paths
No PDP redirect Multiple products match PDP redirects require exactly one unique product match
Redirect for wrong attribute Attribute not configured Verify the custom attribute is listed in redirect settings
Redirect triggers for excluded phrase Settings not published Publish the segment after adding excluded phrases
Phrase mapping not working Settings not published Publish the segment after creating phrase mappings
Phrase mapping rejected Duplicate search phrase Each search phrase can only have one mapping (case-insensitive)