Category Analytics

Evaluate category performance, conversion funnel, trends, navigation, and filters with resilient tab states.

Audience: Catalog operations and merchandising teams.

Critical: Category conversion responses expose monetary metrics as currency breakdown rows (`revenueByCurrency[]`).

Product Analytics Analytics Migration v2

Quick Start (2-5 Minutes)

Load top categories

Get ranked category list for selected range.

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

Load category overview

Fetch category KPI snapshot.

GET /api/v1/analytics/category/:siteId/overview?categoryPath=/men/shoes&days=30

Load conversion funnel

Read funnel + revenue by currency rows.

GET /api/v1/analytics/category/:siteId/conversion?categoryPath=/men/shoes&days=30

Load navigation and filters

Analyze path and filter behavior.

GET /api/v1/analytics/category/:siteId/paths?categoryPath=/men/shoes
GET /api/v1/analytics/category/:siteId/filters?categoryPath=/men/shoes

Category analytics endpoints

GET /api/v1/analytics/category/:siteId/overview
GET /api/v1/analytics/category/:siteId/top
GET /api/v1/analytics/category/:siteId/conversion
GET /api/v1/analytics/category/:siteId/products
GET /api/v1/analytics/category/:siteId/paths
GET /api/v1/analytics/category/:siteId/trends
GET /api/v1/analytics/category/:siteId/filters
GET /api/v1/analytics/category/:siteId/all

Required Fields / Response Guarantees

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	All category endpoints	Site data scope.
`categoryPath`	Required (except top/all)	`string`	overview/conversion/products/paths/trends/filters	Tracked category path value.
`revenueByCurrency`	Required (conversion response metrics)	`Array<{ currency, revenue, orders, avgOrderValue }>`	conversion.metrics.revenueByCurrency	Monetary metrics are returned per currency. Mixed totals must not be merged.

UI Behavior (v2)

Category analytics pages now enforce tab-based resilience:

Each tab has explicit loading state.
Each tab has explicit error state.
Each tab has explicit empty state (no blank screen).

Information Modals (UI)

Category overview includes info modals for:

Summary metrics section
Top categories table

Category detail includes info modals for:

Conversion Funnel
Navigation
Filters
Trends

Each modal includes definition, calculation, data scope, and latency note.

Decision Matrix

Scenario	Use This	Why
Need ranked category list	/analytics/category/:siteId/top	High-level prioritization by views.
Need one category KPI snapshot	/analytics/category/:siteId/overview	Category engagement baseline.
Need conversion + revenue metrics	/analytics/category/:siteId/conversion	Funnel with currency-aligned revenue fields.
Need browsing transition behavior	/analytics/category/:siteId/paths	Previous and next category movement.
Need filter/sort diagnostics	/analytics/category/:siteId/filters	Facet and sort behavior visibility.

Common Errors and Fixes

Category detail tab appears empty

Cause: No events available for selected categoryPath and date window.

Fix: Validate category path from /all endpoint and expand days range.

Revenue shown in wrong symbol

Cause: Client ignores conversion.metrics.revenueByCurrency rows.

Fix: Render each row with its own currency and avoid cross-currency scalar totals.

Top categories fluctuate heavily

Cause: Short lookback period with sparse traffic.

Fix: Use longer windows for strategic decisions.

Production Checklist

Category detail tabs always render loading/error/empty states.Required
Conversion revenue uses response revenueByCurrency rows.Required
Overview and detail modal coverage is complete.Required
Category path values are validated using /all endpoint data.Required