> ## 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.

# Working with Aggregations

> Reading and using profile aggregation data via the Omneo API.

Aggregations are calculated facts derived from a profile's transaction history and activity. They are computed by Omneo on a regular schedule and available as read-only fields on the profile. Use them for segmentation, personalisation, and real-time display in front-end experiences.

## Available aggregations

| Category    | Aggregation                | Description                           |
| ----------- | -------------------------- | ------------------------------------- |
| Spend       | `spend_12m`                | Total spend in the last 12 months     |
| Spend       | `spend_all`                | Total lifetime spend                  |
| Spend       | `atv`                      | Average transaction value             |
| Frequency   | `shop_count`               | Total number of transactions          |
| Frequency   | `purchase_frequency`       | Average days between purchases        |
| Frequency   | `days_since_last_purchase` | Days since last transaction           |
| Preferences | `preferred_location_id`    | Most frequently visited location      |
| Preferences | `preferred_channel`        | Primary shopping channel              |
| Lifecycle   | `lifecycle_stage`          | Current stage in the customer journey |

## Reading aggregations for a profile

Aggregations are returned as part of the standard profile response:

```shell theme={null}
GET /api/v3/profiles/{profileId}
```

Look for the `aggregations` key in the response body. If aggregations have not yet been calculated for a profile (e.g., a newly created profile with no transactions), the values will be `null`.

## Browsing all aggregations

```shell theme={null}
GET /api/v3/profiles/{profileId}/aggregations
```

## Using aggregations in reactions

Aggregation values are available as variables in reaction conditions and Twig templates. For example, you can trigger a reaction when `spend_12m` crosses a threshold, or include a customer's lifetime spend in a notification payload.

```twig theme={null}
Your total lifetime spend with us is {{ profile.aggregations.spend_all | currency }}.
```

## Notes

* Aggregations are recalculated on a schedule: they are not real-time. Allow for a short delay after a transaction is recorded before aggregation values update.
* Aggregations are read-only. You cannot write to them directly via the API.
* For real-time incentive balances (points, rewards), use the dedicated incentive endpoints rather than aggregations.