Recommendations

Manage recommendation widgets, strategy selection, previews, analytics, and runtime tracking.

Audience: Merchandising and personalization teams using recommendation placements across site pages.

Critical: Public storefront delivery uses /api/v1/public/sites/:siteKey/recommendations and event ingestion uses dedicated recommendation track endpoints.

Recommendation Strategies Recommendation Breakdown Modules: Search

Who This Page Is For

Use this page when you need an end-to-end operational contract for recommendation widget creation, preview, lifecycle operations, and analytics-safe event tracking.

Quick Start (2-5 Minutes)

Review supported strategies

Fetch current strategy and platform options before widget creation.

GET /api/v1/recommendations/strategies
GET /api/v1/recommendations/platforms

Create recommendation widget

Create site-scoped widget with strategy and display settings.

POST /api/v1/recommendations/site/:siteId

Preview output products

Run preview call to validate strategy output before activating.

POST /api/v1/recommendations/:id/site/:siteId/preview

Activate in site scope

Turn widget on/off without deleting the configuration.

PUT /api/v1/recommendations/:id/site/:siteId/toggle-active

Track runtime interactions

Send recommendation event and behavior signals from storefront runtime.

POST /api/v1/public/sites/:siteKey/recommendations/track/event
POST /api/v1/public/sites/:siteKey/recommendations/track/behavior

Core endpoints

GET    /api/v1/recommendations/strategies
GET    /api/v1/recommendations/platforms
GET    /api/v1/recommendations
GET    /api/v1/recommendations/site/:siteId
GET    /api/v1/recommendations/:id
GET    /api/v1/recommendations/:id/site/:siteId
POST   /api/v1/recommendations/site/:siteId
PUT    /api/v1/recommendations/:id
PUT    /api/v1/recommendations/:id/site/:siteId
PATCH  /api/v1/recommendations/:id
POST   /api/v1/recommendations/:id/site/:siteId/preview
GET    /api/v1/recommendations/:id/site/:siteId/analytics
POST   /api/v1/recommendations/:id/duplicate
POST   /api/v1/recommendations/:id/site/:siteId/duplicate
DELETE /api/v1/recommendations/:id
DELETE /api/v1/recommendations/:id/site/:siteId
PUT    /api/v1/recommendations/:id/site/:siteId/toggle-active
POST   /api/v1/recommendations/site/:siteId/track/event
POST   /api/v1/recommendations/site/:siteId/track/behavior
GET    /api/v1/public/sites/:siteKey/recommendations
POST   /api/v1/public/sites/:siteKey/recommendations/:widgetId/products
POST   /api/v1/public/sites/:siteKey/recommendations/track/event
POST   /api/v1/public/sites/:siteKey/recommendations/track/behavior

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	Create/list scope	Recommendation ownership and security boundary.
`name`	Required	`string`	Create/update	Operational widget name in dashboard and analytics.
`strategy`	Required	`RecommendationStrategy`	Ranking logic	Selects recommendation retrieval behavior (bestsellers, viewed_together, ai_personalized, etc.).
`productsToShow`	Optional	`number`	Rendering	Controls item count delivered to placement.
`pageTargetingJson`	Optional	`object`	Eligibility	Include/exclude URLs and page-type matching.
`segmentTargetingMode + segmentIds`	Conditional	`string + uuid[]`	Audience gating	Include/exclude segments for recommendation delivery.

Create recommendation widget (minimal example)

{
"name": "Product Page Similar Items",
"strategy": "similar_products",
"productsToShow": 8,
"displayType": "slider",
"pageTargetingJson": {
  "includeUrls": ["/products/*"],
  "showOnAllPages": false
}
}

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Get organization-level inventory	GET /api/v1/recommendations	Global view for operations and audits.
Operate within one site	GET /api/v1/recommendations/site/:siteId	Simplifies site-specific rollout and cleanup.
Validate recommendation output before launch	POST /api/v1/recommendations/:id/site/:siteId/preview	Prevents low-quality live placements.
Track click/impression/cart behavior from private admin flow	POST /api/v1/recommendations/site/:siteId/track/event or /track/behavior	Supports authenticated internal tools or testing utilities.
Track storefront runtime behavior	POST /api/v1/public/sites/:siteKey/recommendations/track/event and /track/behavior	Public ingestion contract used by production widget script.

Common Errors and Fixes

Preview works but storefront shows empty products

Cause: Page targeting rules or trigger settings prevent runtime placement from requesting products.

Fix: Validate pageTargetingJson, trigger config, and public products endpoint call path.

Widget not toggling in site context

Cause: Wrong siteId for the widget or mismatched legacy route usage.

Fix: Use site-scoped toggle endpoint with correct widget ID and site ID pair.

Analytics appears incomplete

Cause: Runtime events not sent consistently to track/event and track/behavior endpoints.

Fix: Ensure impression/click/add-to-cart/purchase signals are emitted from storefront layer.

Integration endpoint returns provider unsupported

Cause: Provider name mismatch in external forwarding setup.

Fix: Use canonical provider names (ga4, meta, gads/google_ads).

Production Checklist

Strategy is explicitly chosen and documented per widget.Required
Preview output is reviewed before activating each widget.Required
Site-scoped toggle flow is used for controlled rollouts.Required
Runtime tracking events are wired to public recommendation tracking endpoints.Required
Per-widget analytics is reviewed after launch for quality tuning.Required