Breaking Migration: Analytics v2

Mandatory cutover guide for Product + Category Analytics v2.

Audience: Frontend, backend, and data teams migrating analytics consumers.

Critical: This migration is fully breaking. Legacy routes, legacy fields, and compatibility adapters were removed on February 16, 2026.

Analytics Overview Product Analytics Category Analytics

Scope

This migration applies to:

Product analytics API consumers
Category analytics UI/API consumers
Dashboard analytics pages using product/category revenue fields

Out of scope:

Legacy client compatibility and dual-run strategy
Route aliases for removed v1 product analytics endpoints

Removed vs Replacement Endpoints

Removed Endpoint	Replacement Endpoint	Notes
GET /api/v1/analytics/product/sites/:siteId/top-revenue	GET /api/v1/analytics/product/:siteId/top	Top response now includes mandatory currency.
GET /api/v1/analytics/product/:siteId/bought-together	GET /api/v1/analytics/product/:siteId/associations?source=purchase	Merged associations contract.
GET /api/v1/analytics/product/:siteId/added-to-cart-together	GET /api/v1/analytics/product/:siteId/associations?source=cart	mode supports all\|session\|cart.
GET /api/v1/sites/:siteId/products (analytics usage)	GET /api/v1/analytics/product/:siteId/catalog	Picker data moved under analytics permission scope.

New Product Analytics Endpoint Set (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

Contract Changes

Field	Required	Type	Used by events	Description
`productItemCode`	Removed (query contracts)	`string`	product overview / associations / dwell-time queries	Do not send this query field in v2.
`productId`	Required	`uuid`	product overview / associations / dwell-time queries	Canonical product identity in all product analytics drilldowns.
`source`	Required (associations)	`purchase\|cart`	product associations	Select association stream in merged endpoint.
`mode`	Optional	`all\|session\|cart`	product associations	Narrow cart association aggregation strategy.
`currency`	Required (response)	`string`	product top rows	Frontend must format top-product money fields with response row currency.
`revenueByCurrency`	Required (response)	`Array<{ currency, revenue, orders, avgOrderValue }>`	category conversion response	Category conversion monetary fields are now split by currency. Mixed scalar totals are removed.

Mandatory Migration Steps

Drop legacy routes from clients

Delete old product analytics endpoint usage and old hook imports.

Remove bought-together, added-to-cart-together, and top-revenue route calls.

Switch all drilldowns to productId

Update query builders and typed contracts.

Send productId UUID to overview/associations/dwell-time.

Use analytics catalog endpoint

Load product picker data from analytics scope.

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

Adopt merged associations endpoint

Replace split purchase/cart routes.

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

Normalize currency usage

Remove hardcoded EUR/USD for analytics revenue rendering and adopt per-currency rows.

Use product row currency and category conversion revenueByCurrency[] entries.

Verify UI information modals

Ensure fixed metric explanation modals are present in required sections.

Product: KPI, Bought Together, Added to Cart Together, Dwell Time. Category: Summary, Top table, Conversion, Navigation, Filters, Trends.

UI/UX Behavior Changes

Category overview/detail tabs now expose explicit loading, error, and empty states.
Product selection state is selectedProductId based and remains stable across catalog pagination.
Product catalog uses infinite append behavior (page-based accumulation).
Export flow is independent from dropdown visibility and catalog fetch timing.
Information modals are keyboard accessible (open/close, ESC close, focus trap, aria labeling).

Common Migration Failures

400 validation error on product analytics query

Cause: productItemCode is still being sent.

Fix: Switch query identity to productId (UUID).

Frontend cannot load product picker

Cause: UI still calls /api/v1/sites/:siteId/products.

Fix: Use /api/v1/analytics/product/:siteId/catalog with ANALYTICS_VIEW permission.

Currency displayed incorrectly

Cause: Client-side hardcoded currency formatter.

Fix: Format revenue with response currency only.

Associations data mismatch

Cause: Client is still splitting purchase/cart on removed routes.

Fix: Use merged associations endpoint with source and mode.

Release Checklist

No consumer calls removed product analytics v1 endpoints.Required
All product analytics drilldowns send productId UUID.Required
Merged associations endpoint is used for both purchase and cart analysis.Required
Category conversion revenue uses response revenueByCurrency[] rows.Required
Product top revenue uses response row currency field.Required
Required information modals are present and keyboard accessible.Required
Product analytics + category analytics Playwright flows pass in CI.Required