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

# Aggregations

> Calculated profile facts derived from transaction and interaction history.

**Aggregations** are calculated facts derived from a profile's transaction history. They provide a real-time picture of customer value and behaviour without requiring custom queries against raw data.

Aggregations are updated automatically whenever new transactions are recorded against a profile. They are stored as a separate record linked to the profile and returned alongside profile data in API responses and event contexts.

## Spend

All spend values are net figures (returns and exchanges are subtracted).

| Field              | Description                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `spend_12m`        | Net spend in the rolling 12-month window, measured back from the profile's most recent transaction date |
| `spend_12m_now`    | Net spend in the rolling 12-month window, measured back from today                                      |
| `spend_all`        | Lifetime net spend                                                                                      |
| `spend_atv_12m`    | Average net transaction value in the last 12 months                                                     |
| `spend_atv_all`    | Average net transaction value lifetime                                                                  |
| `spend_first_date` | Date of the profile's first transaction                                                                 |
| `spend_last_date`  | Date of the profile's most recent transaction                                                           |

## Shop dates and timing

These fields track the timing of shopping behaviour across unique transaction dates.

| Field                | Type    | Description                                                                                                                                                                         |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_shop_date`    | Date    | Date of the first transaction                                                                                                                                                       |
| `first_shop_days`    | Integer | Days between join date and first shop date. Can be zero.                                                                                                                            |
| `second_shop_date`   | Date    | Date of the next transaction on a unique date after the first                                                                                                                       |
| `second_shop_days`   | Integer | Days between first and second shop date. Minimum 1.                                                                                                                                 |
| `average_shop_days`  | Integer | Average days between unique shopping dates: (latest minus first date) divided by count of unique transaction dates. Set on the third shop and recalculated on each subsequent shop. |
| `total_shop_days`    | Integer | Total count of unique shopping days                                                                                                                                                 |
| `previous_shop_date` | Date    | The prior value of `latest_shop_date`, set when a new latest shop date is established                                                                                               |
| `latest_shop_date`   | Date    | Date of the most recent transaction on a unique date                                                                                                                                |
| `latest_shop_days`   | Integer | Days between `previous_shop_date` and `latest_shop_date`. Minimum 1.                                                                                                                |
| `at_risk_date`       | Date    | `latest_shop_date` plus (`average_shop_days` multiplied by 3). Signals when a customer is overdue for their next visit.                                                             |

## Purchase behaviour

| Field        | Description                                                                                                                         |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `shop_count` | Total number of unique shopping days where the net of transactions is greater than zero. Pure exchange or return days are excluded. |
| `shop_days`  | Average number of days between transactions. Only calculated for profiles with three or more transactions.                          |

### Dimensions

Omneo calculates four behaviour dimensions from transaction history. Each uses a defined set of codes.

**`dimension_recency`:** how recently the profile last shopped:

| Code | Meaning                                       |
| ---- | --------------------------------------------- |
| `R0` | Never shopped                                 |
| `RR` | Retired (last shop more than 5 years ago)     |
| `RL` | Lapsed (last shop 3 to 5 years ago)           |
| `RI` | Inactive (last shop 1 to 2 years ago)         |
| `RA` | Annual active (last shop 6 to 12 months ago)  |
| `RS` | Seasonal active (last shop 3 to 6 months ago) |
| `RC` | Current active (last shop within 3 months)    |

**`dimension_frequency`:** how frequently the profile shops:

| Code | Meaning                                           |
| ---- | ------------------------------------------------- |
| `F0` | Never shopped                                     |
| `F1` | 1 transaction ever                                |
| `F2` | 2 transactions ever                               |
| `FL` | Low frequency (average shop days greater than 90) |
| `FM` | Medium frequency (average shop days 30 to 90)     |
| `FH` | High frequency (average shop days less than 30)   |

**`dimension_channel`:** the channels the profile has shopped across:

| Code | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| `CC` | Concession only                                          |
| `CF` | Branded only (store or outlet)                           |
| `CD` | Branded or concession only, not online                   |
| `CO` | Online only                                              |
| `CS` | Outlet only                                              |
| `CM` | Multichannel (branded, concession, or outlet AND online) |

**`dimension_joined`:** the profile's join lifecycle stage:

| Code | Meaning                                      |
| ---- | -------------------------------------------- |
| `JE` | Established (joined more than 12 months ago) |
| `JC` | Current (joined 3 to 12 months ago)          |
| `JN` | New (joined within 3 months)                 |

## Preferences

| Field                      | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| `most_transacted_location` | Location object for the profile's most frequently visited store   |
| `store_join`               | Location object for the store where the profile was created       |
| `likely_country`           | Inferred country based on transaction data                        |
| `purchased_brands`         | Array of brand or department names the profile has purchased from |

## Using aggregations

Aggregation fields are available in reaction filter conditions and target templates. For example, you can fire a reaction when `aggregations.spend_12m` crosses a threshold, or include `at_risk_date` in a win-back campaign payload.

```json theme={null}
{
  "aggregations": {
    "spend_12m": 2260.00,
    "spend_12m_now": 1840.00,
    "spend_all": 8450.50,
    "shop_count": 18,
    "average_shop_days": 32,
    "latest_shop_date": "2026-03-15",
    "at_risk_date": "2026-04-16",
    "dimension_recency": "RC",
    "dimension_frequency": "FM"
  }
}
```

Individual aggregation fields can be manually updated or fully recalculated via the API.

## Related

* [Profiles](/concepts/profiles/overview)
* [Transactions](/concepts/commerce/transactions)
* [Profile aggregations API](/api-reference/profile-aggregation)