Product Analytics

Analyze product performance with mandatory productId and unified association contracts.

Audience: Merchandising, conversion, and growth analytics teams.

Critical: Breaking change: productItemCode query parameters are removed. Use productId (UUID) for all product drilldowns.

Category Analytics Analytics Migration v2

Quick Start (2-5 Minutes)

Fetch product catalog

Load analytics-scoped selectable products (ANALYTICS_VIEW permission).

GET /api/v1/analytics/product/:siteId/catalog?search=shoe&page=1&limit=50

Fetch product overview

Retrieve KPI metrics using productId.

GET /api/v1/analytics/product/:siteId/overview?productId=<uuid>&days=30

Fetch associations (purchase)

Get products purchased with selected product.

GET /api/v1/analytics/product/:siteId/associations?productId=<uuid>&source=purchase&mode=all&limit=10

Fetch associations (cart)

Get cart/session co-add associations from one endpoint.

GET /api/v1/analytics/product/:siteId/associations?productId=<uuid>&source=cart&mode=session&limit=10

Fetch top revenue products

Read site-isolated top list with mandatory currency field.

GET /api/v1/analytics/product/:siteId/top?days=30&limit=20

Product analytics endpoints (v2)

GET /api/v1/analytics/product/:siteId/catalog
GET /api/v1/analytics/product/:siteId/overview
GET /api/v1/analytics/product/:siteId/associations
GET /api/v1/analytics/product/:siteId/dwell-time
GET /api/v1/analytics/product/:siteId/tracking-status
GET /api/v1/analytics/product/:siteId/top

Required Query Fields

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	All endpoints	Site scope for all analytics calculations.
`productId`	Required (overview/associations/dwell-time)	`uuid`	overview/associations/dwell-time	Canonical product identity for analytics lookup.
`source`	Required (associations)	`purchase\|cart`	associations	Select purchase or cart association stream.
`mode`	Optional	`all\|session\|cart`	associations	Filter cart association mode.
`currency`	Required (response)	`string`	top response revenue fields + catalog price rows	Client must format money values only with response currency.

Currency Rules

Product catalog rows include currency for price rendering.
Top products are returned with explicit currency per row.
If multiple currencies exist, treat rows independently and do not aggregate into one converted total.

Information Modals (UI)

The Product Analytics page includes fixed information modals for:

KPI Snapshot
Bought Together
Added to Cart Together
Dwell Time

Each modal documents: metric definition, calculation logic, data scope, and latency/freshness note.

Endpoint Decision Matrix

Scenario	Use This	Why
Need product picker data for analytics users	/analytics/product/:siteId/catalog	Analytics permission scoped product catalog.
Need KPI summary for one product	/analytics/product/:siteId/overview	Core product engagement and conversion metrics.
Need purchase affinity pairs	/analytics/product/:siteId/associations?source=purchase	Order-level co-occurrence signal.
Need cart/session affinity pairs	/analytics/product/:siteId/associations?source=cart	Cart intent co-occurrence signal.
Need top revenue ranking	/analytics/product/:siteId/top	Site-isolated revenue ranking with currency field.

Common Errors and Fixes

Validation error for productItemCode query

Cause: v1 query field removed.

Fix: Send productId UUID instead.

Revenue displays with wrong currency

Cause: Client-side hardcoded currency format.

Fix: Format only with response currency field.

Cart association results look empty in session mode

Cause: Low session-level co-add volume.

Fix: Switch mode to all or increase days window.

Production Checklist

All product analytics queries use productId UUID.Required
Legacy /sites/:siteId/products dependency removed from analytics UI.Required
Top revenue display uses response currency field.Required
Information modals are available at required product analytics sections.Required
No compatibility layer is used for removed v1 product routes.Required