> ## Documentation Index
> Fetch the complete documentation index at: https://topten.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Measurement & definitions

> The exact definition behind every metric in Live Product Insights — active viewers, product views, cart activity, attribution, conversion, revenue, and trending rules.

Every number in Live Product Insights is computed from the definitions on this
page. When a metric and a marketing description ever disagree, this page wins.
Merchants can rely on these definitions; developers and support teams can use
them to interpret any value the app shows.

## Live activity metrics

| Metric | Definition |
| - | - |
| Active viewers | Distinct sessions that sent a valid heartbeat within the **active window**. Default 60 seconds, configurable from 10 to 600 seconds. Sessions drop out as soon as heartbeats stop. |
| Product views | Count of valid product-view events. Refreshes and repeat visits are deduplicated per session and product within the **view dedupe window** — default 30 minutes, configurable from 5 to 1,440 minutes. |
| Currently viewed | Products with at least one active viewer right now. |

> [!WARNING]
>
> Active viewers and views are never mixed. A shopper who keeps a product page
> open for ten minutes is one active viewer and — thanks to dedupe — one view.

## Cart metrics

| Metric | Definition |
| - | - |
| Add-to-cart events | Count of cart-add events. A distinct-session variant shows how many different sessions added the product. |
| View-to-cart event rate | Add-to-cart events ÷ product-view events in the same window. This is an **event rate**, not a visitor conversion rate. |
| Cart removals | Counted only where the storefront reliably exposes the event; removals that happen after checkout begins are not observable. |
| Net additions | Additions minus removals in the window. |

## Purchase metrics

### Orders

Orders come from Shopify webhooks. Test orders are excluded unless the store
opts in, and cancelled orders are always excluded from every order, revenue,
and conversion metric.

### Attribution

An order is **attributed** to a product only when all of these hold:

1. The order arrived with a cart token.
2. The cart token matches a session that added products to its cart.
3. Those cart additions fall inside the **attribution window** before the
   order was created — default 7 days, configurable from 1 to 30 days.

Orders with no matching token are still counted as orders, but they are
labelled **not attributable**. Orders ingested by the background catalog sync
carry no cart token, so they are never attributed — attribution is always
webhook-driven.

### Derived purchase metrics

| Metric | Formula |
| - | - |
| Product conversion | Attributed orders ÷ distinct view sessions. Shown only when attribution is supported in the window. |
| Cart-to-order rate | Attributed orders ÷ distinct sessions that added to cart. |
| Revenue | Line price × quantity − line discounts, excluding tax and shipping, minus refunds prorated per unit. Cancelled orders reversed. |
| Average order value | Revenue ÷ qualifying orders, store-wide. |

## Trending and comparison rules

* Comparisons always use **equal-length periods**: this week against the
  previous seven days, never a partial period.
* A percentage change is only reported when the baseline is above zero;
  otherwise the value is shown as new rather than as an infinite percentage.
* **Trending** requires at least 10 views in the previous period and growth of
  30% or more.
* **Declining** requires at least 10 views in the previous period and a drop of
  30% or more.
* **Rising interest** requires growth of 30% or more in views *or* cart
  additions.

## Internal thresholds reference

| Threshold | Value | Where it applies |
| - | - | - |
| Trend minimum baseline | 10 prior-period views | Trending, declining, rising |
| Trend bands | ±30% | Trending up, declining, rising interest |
| Product pair co-view minimum | 5 shared sessions | Frequently viewed together |
| High views, low cart | ≥50 views and add rate ≤50% of store rate | Insights and opportunity detection |
| High cart, low purchase | ≥10 cart sessions and ≤50% of store cart-to-order rate | Insights and opportunity detection |
| Low stock | Merchant threshold (default 10 units) | Low-stock and restock insights |
| Restock lead time | Merchant-set supplier days | Restock urgency insights |
| Sales velocity window | Rolling 7 days | Products page velocity column |
| New product | Created within the last 30 days | New product performance |
| Hourly heatmap minimum | 24 hour-buckets of data | Best time to promote |

## Why the app never guesses

Live Product Insights never shows a causation claim, a projected number, or a
placeholder count. Three rules follow from the definitions above:

* The storefront counter **hides instead of showing zero**. A "0 people
  viewing" badge would imply the page is being watched and found wanting — so
  nothing renders until a real viewer is present.
* Cart activity is never presented as orders. The two numbers measure
  different things and are never swapped.
* Metrics that depend on attribution are hidden or labelled when the tracking
  method cannot support them, rather than filled in with an estimate.

See [Settings](https://topten.mintlify.site/settings.md) for the configurable windows, and
[Privacy](https://topten.mintlify.site/privacy.md) for how events are collected and consented.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.