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

# Metrics & targets

> Send Omneo reactions to Klaviyo as custom events, with optional identity tokens for authenticated personalisation.

Omneo can push any profile-level activity into Klaviyo as a **custom metric** (a Klaviyo event). These metrics are perfect triggers for Flows: they can fire emails, SMS, or other automations the moment something happens in Omneo.

Metrics are delivered from Omneo using a **target**. Targets are the Omneo-side mechanism that calls into the Klaviyo extension and tell it which job to run.

## How metrics flow

```text theme={null}
Omneo Reaction  ──▶  Omneo Target  ──▶  Klaviyo Extension  ──▶  Klaviyo Event
   (any event)        (POST /targets/      (queues to outbound       (visible in
                       klaviyo/metric)      Cloud Tasks queue)        Klaviyo)
```

1. An Omneo **reaction** is configured to fire on the activity you care about (e.g. tier change, purchase, custom milestone).
2. The reaction calls an Omneo **target** that points at the extension's metric endpoint.
3. The extension queues the work on the outbound Cloud Tasks queue (see [Inbound queues](/extensions/klaviyo/queues)).
4. The job calls Klaviyo's [Create Event](https://developers.klaviyo.com/en/reference/create_event) API to create the metric against the matching Klaviyo profile.

The metric name, properties, and the profile it attaches to are all controlled by the body of your target. The extension does not invent these. The body must include `attributes.profile.data.id` (the Klaviyo profile ID) or `attributes.profile.data.attributes.email` so the metric can be attached to the correct profile.

## Target endpoint

```text theme={null}
POST https://{your-extension-url}/{tenant}/api/v1/targets/klaviyo/metric
```

Available targets on the extension:

| Target                | Purpose                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| `metric`              | Create a custom Klaviyo event                                          |
| `upsert-profile-data` | Force a profile resync to Klaviyo                                      |
| `data-source-record`  | Push a data source record (e.g. into Omneo Rewards, Omneo Dates, etc.) |

## Adding an ID token to an outbound metric

Sometimes you need Klaviyo to render content that links back into Omneo with an authenticated session (for example, a personalised wallet page, a reward redemption link, or a "manage preferences" deep link). In these cases, Omneo can attach a short-lived **ID token** to the metric.

Klaviyo can then pull this token into emails or SMS as a Liquid variable and include it on URLs back to Omneo, allowing the customer to land on their own profile without logging in again.

### How to enable it

Add the query parameter `withToken=true` to the target call. The extension will:

1. Read the Klaviyo profile ID from `attributes.profile.data.id` on the metric body.
2. Call Omneo's identity token endpoint using the configured **identity handle** (defaults to `klaviyo`).
3. Base64-encode the returned token.
4. Attach two extra properties to the metric before sending it to Klaviyo:
   * `IDToken`: the base64-encoded token
   * `IDTokenExpiry`: the token's expiry timestamp

### Example target URL

```text theme={null}
POST https://{your-extension-url}/{tenant}/api/v1/targets/klaviyo/metric?withToken=true
```

### Using the token in Klaviyo

Once the metric is delivered, `IDToken` and `IDTokenExpiry` are available as event properties inside Klaviyo. You can reference them in Flow message templates like any other event property:

```liquid theme={null}
<a href="https://your-omneo-frontend.example.com/account?token={{ event.IDToken }}">
  View your rewards
</a>
```

<Warning>
  ID tokens are short-lived by design. Use them in messages that are sent immediately (transactional or near-real-time Flow emails). They are not suitable for evergreen content or messages with long send delays. By the time the customer clicks, the token will have expired.
</Warning>

<Tip>
  If `withToken=true` is set but the metric body has no Klaviyo profile ID, the token generation is skipped silently and the metric is sent without the extra properties.
</Tip>