Recommendation Breakdown

Per-widget recommendation analytics for placement-level optimization and governance.

Audience: Personalization and merchandising teams optimizing recommendation widget portfolio.

Critical: Breakdown endpoint: GET /api/v1/analytics/recommendations/breakdown with optional days and siteId filters.

Modules: Recommendations Revenue Analytics Funnels

Who This Page Is For

Use this page when you need per-widget performance comparisons to decide which recommendation placements to scale, retune, or retire.

Quick Start (2-5 Minutes)

Get baseline breakdown

Load per-widget recommendation metrics across organization.

GET /api/v1/analytics/recommendations/breakdown?days=30

Filter by site

Scope analysis to one site for local optimization.

GET /api/v1/analytics/recommendations/breakdown?siteId=SITE_ID&days=30

Compare with recommendation funnel

Map widget-level metrics to overall recommendation funnel performance.

Use /analytics/funnels/:siteId?steps=widget_impression,click,add_to_cart,purchase for pipeline context.

Cross-check revenue contribution

Validate high engagement placements against attributed revenue.

Use /analytics/revenue/recommendations/:id where needed.

Apply optimization actions

Adjust strategy/config for underperforming widgets and monitor next cycle.

Use module recommendation update endpoints for tuning.

Recommendation breakdown endpoint

GET /api/v1/analytics/recommendations/breakdown

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`days`	Optional	`number`	breakdown endpoint	Lookback window for widget metrics.
`siteId`	Optional	`uuid`	breakdown endpoint	Filter to one site in multi-site organizations.
`Authorization`	Required	`Bearer token`	breakdown endpoint	Authenticated access with analytics permission.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need per-widget recommendation KPI table	/analytics/recommendations/breakdown	Widget-level visibility in one endpoint.
Need site-specific recommendation analysis	breakdown with siteId	Isolates local site behavior from org averages.
Need stage-drop context	/analytics/funnels/:siteId?steps=widget_impression,click,add_to_cart,purchase	Pipeline conversion interpretation for widget KPIs.
Need revenue context	/analytics/revenue/recommendations/:id	Links engagement with attributable value.
Need placement tuning action	/modules/recommendations endpoints	Apply strategy/display updates based on findings.

Common Errors and Fixes

Breakdown list unexpectedly empty

Cause: No active recommendation widgets or narrow date/site filters.

Fix: Verify widget inventory and broaden days/site filters.

High impressions but low conversions

Cause: Placement context mismatch or weak product relevance strategy.

Fix: Retune strategy, page targeting, and product card experience.

Metrics differ from module analytics view

Cause: Different time windows or aggregation scopes.

Fix: Align filters across views before comparison.

No revenue correlation

Cause: Recommendation events tracked but order attribution weak.

Fix: Audit recommendation purchase tracking and attribution integration.

Production Checklist

Recommendation breakdown is reviewed at fixed optimization cadence.Required
siteId filtering is used for site-specific incident triage.Required
Breakdown insights are paired with funnel and revenue checks.Required
Low-performing widgets have documented remediation actions.Required
Post-change performance is compared against previous cycle baseline.Required