Search Boost Rules

Control ranking with boost, bury, and pin rules for deterministic merchandising outcomes.

Audience: Search relevancy managers and merchandisers optimizing ranking behavior.

Critical: Rules are site-scoped and managed under /api/v1/sites/:siteId/search/analytics/boost-rules.

Search Overview Redirects Search Analytics

Who This Page Is For

Use this page when ranking quality requires explicit merchandising control beyond default relevance scoring.

Quick Start (2-5 Minutes)

List current rules

Review active/inactive boost rules and priorities.

GET /api/v1/sites/:siteId/search/analytics/boost-rules

Create first rule

Define query pattern and boost/bury/pin arrays.

POST /api/v1/sites/:siteId/search/analytics/boost-rules

Set priority

Use priority to resolve conflicts between overlapping rules.

{ "name": "Holiday", "priority": 100 }

Update for seasonal changes

Adjust rule payload without full recreation.

PUT /api/v1/sites/:siteId/search/analytics/boost-rules/:ruleId

Delete retired rule

Remove stale rules that are no longer needed.

DELETE /api/v1/sites/:siteId/search/analytics/boost-rules/:ruleId

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`name`	Required	`string`	Create/update rule	Operational name for auditability and governance.
`queryPattern`	Optional	`string`	Rule matching	Scope rule to specific query family.
`boostRules[]`	Optional	`{field,value,boost}[]`	Ranking	Increase ranking score for matched products.
`buryRules[]`	Optional	`{field,value,weight}[]`	Ranking	Demote matched products in results.
`pinRules[]`	Optional	`{productId,position}[]`	Ranking	Place specific products at deterministic positions.
`priority`	Optional	`number`	Conflict handling	Higher priority generally wins in overlap cases.

Boost rule endpoints

GET    /api/v1/sites/:siteId/search/analytics/boost-rules
POST   /api/v1/sites/:siteId/search/analytics/boost-rules
PUT    /api/v1/sites/:siteId/search/analytics/boost-rules/:ruleId
DELETE /api/v1/sites/:siteId/search/analytics/boost-rules/:ruleId

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Promote premium brand SKUs	boostRules	Adds deterministic ranking lift.
Demote out-of-season inventory	buryRules	Reduces visibility without removing catalog records.
Guarantee hero SKU position	pinRules	Hard placement for campaign-critical products.
Resolve overlapping merchandising rules	priority	Predictable precedence model.
Retire temporary campaign rule	DELETE rule	Removes stale ranking logic cleanly.

Common Errors and Fixes

Pinned products do not appear

Cause: Pinned product IDs are invalid or unavailable in current result set.

Fix: Validate product IDs and availability in indexed catalog.

Boost appears too strong

Cause: Boost magnitude too high relative to base scoring.

Fix: Reduce boost values and re-test against control query set.

Rule not applying for expected queries

Cause: queryPattern mismatch or inactive rule.

Fix: Check exact query normalization and isActive status.

Competing rules produce unstable ranking

Cause: No clear priority ordering.

Fix: Set explicit priority values and document precedence.

Production Checklist

Each rule has a clear business objective and owner.Required
Priority values are standardized across rule categories.Required
Pinned product IDs are validated against current catalog.Required
Post-change checks use top query reports and CTR movement.Required
Seasonal rules are reviewed and removed on schedule.Required