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

# Metrics glossary

> Reference for every analytical metric Retailgrid computes - definitions, formulas, and when each one matters.

This page is the reference for every metric Retailgrid computes. Use it to confirm what a column means before you act on it.

Metrics are available as **Analytical metric** columns (added via **Add Column** or the **Metrics** toolbar button) and as outputs of agents like Dynamic Pricing.

## Metric grain

When store-level data is loaded, metrics are computed at the **SKU-Store** grain: each store's KPIs (margin, price index, competitor gap) use that store's own price, cost, and competitor set. In the grid's Product view, a product-level rollup of the same metrics is shown. See [Product and SKU-Store grid views](/grids/sku-store-view).

## Margin metrics

### Margin

Absolute monetary margin per unit, gross of tax.

```
Margin = price - unit_cost
```

Use it for: quick eyeballing of which SKUs make money.

### Margin %

Margin as a percentage of selling price.

```
Margin % = (price - unit_cost) / price
```

Use it for: comparing margin across SKUs at different price points.

### New Unit Margin %

Net-of-tax margin on the price calculated by Dynamic Pricing.

```
New Unit Margin % = (Rules Based Price / (1 + Tax Rate) - Unit Cost)
                  / (Rules Based Price / (1 + Tax Rate))
```

Use it for: seeing the margin you'd land at if you accepted the agent's recommended price.

### Unit Margin % change

Percentage-point change between current Margin % and New Unit Margin %.

```
Unit Margin % change = New Unit Margin % - current Margin %
```

Use it for: spotting the rules that move margin the most (positive or negative).

## Competitive metrics

### Price Index (PI)

Your price relative to a single competitor or competitor reference.

```
Price Index = price / competitor_price * 100
```

100 = parity, less than 100 = you're cheaper, greater than 100 = you're more expensive.

### CPI (Min)

Competitive price index against the cheapest competitor.

```
CPI (Min) = price / min(competitor_price) * 100
```

Use it for: tracking how aggressive the cheapest competitor is per SKU.

### CPI (Mode)

Competitive price index against the most common competitor price.

```
CPI (Mode) = price / mode(competitor_price) * 100
```

The mode often represents the "market price" better than the min, because outlier-cheap competitors don't dominate it.

### Price Gap

Absolute monetary gap to a competitor reference.

```
Price Gap = price - competitor_price
```

Use it for: understanding the literal euros / dollars between you and a competitor.

### Cheapest Flag

Boolean. `true` if your price is the cheapest among the available competitors, otherwise `false`.

```
is_cheapest = price <= min(competitor_price)
```

Use it for: filtering grids to "where am I winning on price."

### Price Range

Visual column showing the min/max of competitor prices and where the current price sits in that range.

This is a UI affordance rather than a numeric metric - use it for at-a-glance market positioning, then drill in with CPI variants for precision.

## Refresh cadence

Most metrics are computed in BigQuery and refresh in near real-time as your underlying data (Products, Transactions, Competitors) changes. Specifically:

* **Margin / Margin %** refresh whenever `price` or `unit_cost` changes on a product.
* **CPI variants and Price Index** refresh whenever the relevant Competitors dataset row updates.
* **Dynamic Pricing output columns** (Rules Based Price, New Unit Margin %, Unit Margin % change) update on demand when the Dynamic Pricing agent runs.

Static metrics like margin, unit cost, and price also keep a daily history in BigQuery alongside the time-series metrics. That history isn't surfaced as its own column today — it's the foundation for upcoming analytics that compare how every metric (not just sales) has moved over time.

If a metric column looks stale, replace the source dataset on the [Datasets page](/data-requirements/datasets) - that triggers a downstream refresh.

## Related

* [Add columns](/grids/manage-columns)
* [Dynamic Pricing](/agents/dynamic-pricing)
* [Product and SKU-Store grid views](/grids/sku-store-view)
* [Competitor Prices data spec](/data-requirements/competitors)