Analytics
Analytics combines first-party events, Upsurge product assistance, and optional provider-reported advertising data. The dashboard keeps referral attribution and product assistance separate so assisted value is not mistaken for attributed or 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, assisted conversions, and assisted value;
- 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_observed | Store conversions observed by Upsurge without assigning product credit. |
product_assisted | Conversions where a signed Upsurge product touch occurred inside the configured window; this carries zero referral credit. |
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 assistance, referral attribution, and provider-reported figures separate and label partial coverage. Assisted value is non-additive with attributed or provider-reported revenue.
Campaign performance
The normalized campaign table combines overlay, recommendation, chatbot, and ad rows. Product rows show Upsurge-assisted conversions and assisted value without taking referral credit; 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 assisted conversion, confirm that a signed product touch and canonical commerce conversion share the storefront journey inside the configured window.
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.