Analytics
Analytics combines first-party events, product-campaign outcomes, and optional provider-reported advertising data. The dashboard keeps attribution scope visible so product-attributed revenue is not mistaken for complete store revenue.
Start with scope and filters
- Choose a date range. Merchant analytics ranges support up to 366 days where the route permits it.
- Select all sites or one site.
- Choose a data source: first-party events, product campaigns, or available advertising data.
- Filter campaign type, provider, account, or campaign when needed.
- Refresh and note the last-updated time.
Dates are normalized to avoid local/UTC off-by-one errors. When comparing an external report, use the same timezone, inclusive boundaries, currency, and conversion definition.
Core metrics
- events and sessions;
- conversions and conversion rate;
- revenue, revenue conversions, and average order value when revenue data exists;
- campaign impressions, clicks, CTR, conversions, and attributed revenue;
- ad spend, provider conversions/value, and ROAS when connected provider data exists.
Top and timeseries views can break down events, revenue, or conversions by hour, day, week, or month and surface pages, referrers, devices, and event types.
Attribution scopes
| Scope | Meaning |
|---|---|
product_attributed | Conversions and revenue observed from Upsurge product surfaces. |
provider_reported | Conversion counts or value reported by an advertising provider. |
full_site_imported | A trusted merchant integration imports complete site/order conversions. |
mixed_partial | Multiple incomplete sources are present. |
Ad spend without a full-site conversion import is not enough to claim global ROI. Keep product-attributed and provider-reported figures separate and label partial coverage.
Campaign performance
The normalized campaign table combines overlay, recommendation, chatbot, and ad rows. Product rows preserve Upsurge-attributed conversions and revenue; ad rows preserve provider conversions, conversion value, spend, and ROAS.
Use campaign IDs and site filters when comparing against SDK lifecycle events. If a campaign has activity but no attributed conversion, confirm that the configured conversion event and business identifiers match the storefront journey.
Saved reports and export
Saved reports persist a name, selected data sources, metrics, dimensions, filters, and visualization. Use them for repeatable dashboard analysis. Scheduled report delivery is not currently available.
The dashboard can export the current analytics view. Preserve filter and attribution context alongside exported rows so downstream readers do not infer broader coverage.
Data freshness and health
Event ingestion acknowledges accepted data before every dashboard aggregate is necessarily visible. A short delay can occur through publishing and Pinot-backed query paths.
If data is missing:
- confirm the event ingestion response and per-item batch results;
- check today’s date range, site, data source, and campaign filters;
- verify stable event and campaign IDs;
- refresh after the expected processing delay;
- compare health and source status before concluding the event was lost.
API relationships
Dashboard reads use /api/v1/analytics/metrics, /timeseries, /top, /campaign-performance, /overlays, /recommendations, and /ads. Saved definitions use /analytics/reports. These routes require merchant authentication and derive workspace scope from the verified user token.
See the API endpoint catalog and event ingestion reference.