Search Redirects

Route high-intent queries to curated destinations when direct result lists are not ideal.

Audience: Search and merchandising teams controlling query landing behavior.

Critical: Redirect definitions are managed at /api/v1/sites/:siteId/search/analytics/redirects with matchType exact, contains, or regex.

Search Overview Boost Rules Zero Results

Who This Page Is For

Use this page when specific queries should open curated category pages, campaign pages, or brand pages instead of generic search results.

Quick Start (2-5 Minutes)

List redirects

Review existing query routing behavior.

GET /api/v1/sites/:siteId/search/analytics/redirects

Create exact redirect

Map one high-intent query to one destination.

{ "queryPattern": "black friday", "matchType": "exact", "redirectUrl": "/collections/black-friday" }

Create contains/regex rule

Handle broader phrase families carefully.

{ "queryPattern": "gift", "matchType": "contains", "redirectUrl": "/collections/gifts" }

Disable quickly

Set isActive=false to rollback without delete.

PUT /api/v1/sites/:siteId/search/analytics/redirects/:redirectId

Delete obsolete rule

Remove stale seasonal redirects.

DELETE /api/v1/sites/:siteId/search/analytics/redirects/:redirectId

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`queryPattern`	Required	`string`	Create/update redirect	Pattern compared against incoming search query.
`matchType`	Optional	`exact \| contains \| regex`	Create/update redirect	Matching strategy; default behavior should be explicit in payload.
`redirectUrl`	Required	`string`	Create/update redirect	Target route for matched query.
`isActive`	Optional	`boolean`	Update redirect	Use for safe disable before permanent deletion.

Redirect endpoints

GET    /api/v1/sites/:siteId/search/analytics/redirects
POST   /api/v1/sites/:siteId/search/analytics/redirects
PUT    /api/v1/sites/:siteId/search/analytics/redirects/:redirectId
DELETE /api/v1/sites/:siteId/search/analytics/redirects/:redirectId

Event or Endpoint Decision Matrix

Scenario	Use This	Why
One exact query should redirect	matchType=exact	Most deterministic and lowest risk.
Phrase family should redirect	matchType=contains	Captures broad intent group quickly.
Complex query patterns needed	matchType=regex	Advanced control for power users.
Need temporary rollback	PUT ... isActive=false	Disables behavior immediately without deleting definition.
Need to retire rule permanently	DELETE redirect	Removes stale logic from system.

Common Errors and Fixes

Users redirected too often

Cause: contains or regex pattern too broad.

Fix: Tighten queryPattern or switch to exact matching.

Redirect never triggers

Cause: matchType mismatch with query normalization.

Fix: Inspect normalized query and adjust pattern.

Loop-like navigation behavior

Cause: redirectUrl points to route that triggers same search term flow.

Fix: Use terminal destination pages without recursive search logic.

Invalid redirect URL errors

Cause: Malformed target URL string.

Fix: Use valid absolute or application-relative route format.

Production Checklist

Exact matching is preferred for high-impact queries.Required
Regex rules are documented and reviewed by two people.Required
Redirect performance is monitored in search analytics trends.Required
Seasonal redirect rules have an expiration plan.Required
Rollback path uses isActive toggle before delete.Required