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

# Nutzungsmetriken

> Definiere, wie Nutzungsdaten gemessen und abgerechnet werden.

Nutzungsmetriken definieren, welche Ereignisse aus deiner Anwendung erfasst und wie sie für die Abrechnung aggregiert werden. Du legst fest: Welches Ereignis? Welches Feld? Wie zählen?

## Beispiel: AI-Anwendung

Stell dir vor, du betreibst eine AI-Anwendung und willst zwei Dinge abrechnen:

1. **Token-Verbrauch** - Wie viele Tokens hat der Kunde verbraucht?
2. **API-Aufrufe** - Wie oft wurde die API aufgerufen?

Dafür erstellst du zwei Produkte mit nutzungsbasierter Abrechnung:

| Produkt         | Event-Name   | Aggregation | Feld          |
| --------------- | ------------ | ----------- | ------------- |
| Token-Verbrauch | `ai_request` | SUM         | `tokens_used` |
| API-Aufrufe     | `ai_request` | COUNT       | -             |

***

## Nutzungsbasierte Abrechnung aktivieren

Die Konfiguration erfolgt direkt am **Produkt**. Du aktivierst die nutzungsbasierte Abrechnung und definierst, welche Events wie gemessen werden.

<Steps>
  <Step title="Produkt öffnen">
    Gehe zu [Katalog > Produkte](https://app.fynn.eu/catalogue/products) und öffne das gewünschte Produkt.
  </Step>

  <Step title="Nutzungsbasierte Abrechnung aktivieren">
    Aktiviere den Schalter **Nutzungsbasierte Abrechnung aktivieren**.

    <Frame>
      <img src="https://mintcdn.com/fynnsubscriptionbilling/KK36EiBUGpRYjMlX/images/measurements/product-usage-based-config.png?fit=max&auto=format&n=KK36EiBUGpRYjMlX&q=85&s=3b970803595490abff4808743b230584" alt="Nutzungsbasierte Abrechnung am Produkt konfigurieren" width="2964" height="1996" data-path="images/measurements/product-usage-based-config.png" />
    </Frame>
  </Step>

  <Step title="Grunddaten konfigurieren">
    * **Event-Name**: Welches Event soll erfasst werden (z.B. `email_sent`, `ai_request`)
    * **Name**: Anzeigename der Metrik (erscheint in der Abonnement-Ansicht)
  </Step>

  <Step title="Aggregation wählen">
    Wähle, wie die Events zusammengefasst werden:

    * **COUNT** - Anzahl der Events zählen
    * **SUM** - Werte eines Feldes summieren
    * **UNIQUE\_COUNT** - Eindeutige Werte zählen
    * **MAX** - Höchsten Wert ermitteln
    * **LATEST** - Letzten gemeldeten Wert verwenden
    * **AVERAGE** - Durchschnitt berechnen
  </Step>

  <Step title="Filter hinzufügen (optional)">
    Definiere Bedingungen, die Events erfüllen müssen, um in die Aggregation einbezogen zu werden.
  </Step>

  <Step title="Optionale Einstellungen">
    * **Beschreibung**: Wird auf Rechnungen unter dem Produktnamen angezeigt (Markdown möglich)
    * **Event-Anzeigeformat**: Formatvorlage für die Nutzungsaufschlüsselung (z.B. `API Call to {endpoint} at {timestamp}`)
  </Step>
</Steps>

<Tip>
  Mit **Test Event pushen** kannst du direkt ein Test-Event senden, um die Konfiguration zu prüfen.
</Tip>

***

## Abrechnungszeitpunkt: immer nachgelagert

Nutzungsbasierte Produkte werden **zwingend nachgelagert abgerechnet**. Eine Vorausabrechnung ist nicht möglich und im PricePlan‑Editor automatisch gesperrt.

Der Grund ist einfach: Die abzurechnende Menge ergibt sich aus den **Nutzungsereignissen innerhalb der Periode**. Vor Periodenende ist sie schlicht nicht bekannt. Eine Rechnung zum Periodenstart würde entweder eine Phantasiemenge ansetzen (und später nachkorrigiert werden müssen) oder gar nichts berechnen (und ist damit redundant).

**In der Praxis heißt das:**

* Eine monatlich abgerechnete Nutzungsmetrik mit Vertragsstart 1. Mai → erste Rechnung läuft am 1. Juni und enthält die im Mai erfassten Ereignisse.
* `Vorausabrechnung` ist im PricePlan auf `Nachgelagert` festgeschrieben.
* Die Menge im Abonnement bleibt leer (`null`) — sie wird zur Abrechnungszeit aus den Events ermittelt.

<Note>
  Wenn du eine Mischform aus fester Grundgebühr und nutzungsbasierter Komponente benötigst (z.B. „mindestens 10.000 API‑Calls inklusive, danach pro Call"), modellierst du das als **zwei separate Abonnementpositionen**: eine feste, die im Voraus läuft, plus eine nutzungsbasierte mit Freikontingent, die nachgelagert läuft. Mehr dazu im Artikel [Vorausabrechnung vs. Nachgelagert](/guide/catalogue/pricing-and-billing-timing).
</Note>

***

## Aggregationstypen

Je nachdem, was du messen willst, wählst du einen passenden Aggregationstyp:

| Typ              | Beschreibung                | Beispiel                        |
| ---------------- | --------------------------- | ------------------------------- |
| **Anzahl**       | Zählt die Events            | 150 API-Aufrufe                 |
| **Summe**        | Addiert ein Feld            | 45.000 Tokens                   |
| **Maximum**      | Höchster Wert im Zeitraum   | Max. 50 gleichzeitige User      |
| **Durchschnitt** | Mittelwert eines Feldes     | Ø 300 Tokens pro Request        |
| **Eindeutig**    | Anzahl einzigartiger Werte  | 12 verschiedene Modelle genutzt |
| **Letzter Wert** | Aktuellster gemeldeter Wert | Aktueller Speicherverbrauch     |

<Note>
  Für **Summe**, **Maximum**, **Durchschnitt**, **Eindeutig** und **Letzter Wert** musst du ein Feld angeben.
  **Anzahl** zählt einfach die Events - kein Feld nötig.
</Note>

[Mehr zu Aggregationstypen](/guide/catalogue/measurements/aggregation-types/overview)

***

## Feld angeben

Das Feld bestimmt, welcher Wert aus dem Event aggregiert wird.

**Beispiel Event:**

```json theme={null}
{
  "eventName": "ai_request",
  "properties": {
    "tokens_used": 350,
    "model": "gpt-4",
    "endpoint": "/v1/completions"
  }
}
```

Für die Summe der Tokens gibst du als Feld `tokens_used` an.

### Verschachtelte Felder

Du kannst auch auf verschachtelte Werte zugreifen mit Punkt-Notation:

```json theme={null}
{
  "properties": {
    "usage": {
      "input_tokens": 100,
      "output_tokens": 250
    }
  }
}
```

Feld: `usage.input_tokens` → aggregiert die Input-Tokens.

***

## Filter

Mit Filtern kannst du bestimmen, welche Events in die Berechnung einfließen.

**Beispiel:** Du willst nur erfolgreiche Requests zählen:

```json theme={null}
{
  "property": "status_code",
  "operator": "equals",
  "value": 200
}
```

### Verfügbare Operatoren

| Operator     | Beschreibung           | Beispiel                             |
| ------------ | ---------------------- | ------------------------------------ |
| `equals`     | Exakte Übereinstimmung | `status_code` = 200                  |
| `not-equals` | Nicht gleich           | `status_code` ≠ 500                  |
| `gt`         | Größer als             | `tokens_used` > 100                  |
| `gte`        | Größer oder gleich     | `tokens_used` ≥ 100                  |
| `lt`         | Kleiner als            | `tokens_used` \< 1000                |
| `lte`        | Kleiner oder gleich    | `tokens_used` ≤ 1000                 |
| `in`         | In Liste enthalten     | `model` in \["gpt-4", "gpt-4-turbo"] |
| `not-in`     | Nicht in Liste         | `model` nicht in \["gpt-3.5"]        |
| `contains`   | Enthält Text           | `endpoint` enthält "/v1/"            |

**Mehrere Filter:** Alle Filter müssen zutreffen (UND-Verknüpfung).

***

## Gruppierung (Group By)

Mit Gruppierung kannst du Events nach Eigenschaften gruppieren, um für jede Gruppe **separate Abrechnungspositionen** zu erstellen. Dies ermöglicht eine detaillierte Aufschlüsselung auf der Rechnung.

<Note>
  Jede Gruppe erscheint als eigene Position auf der Rechnung. Ideal, wenn du Kunden zeigen willst, wie sich ihre Nutzung zusammensetzt.
</Note>

### Gruppierung konfigurieren

In der Produkt-Konfiguration kannst du eine oder mehrere Gruppierungseigenschaften hinzufügen:

1. Öffne den Bereich **Gruppierung**
2. Wähle die Event-Eigenschaft aus, nach der gruppiert werden soll
3. Füge bei Bedarf weitere Eigenschaften hinzu

**Beispiele für Gruppierungseigenschaften:**

* `model` - Gruppierung nach AI-Modell
* `region` - Gruppierung nach Region
* `endpoint` - Gruppierung nach API-Endpoint

### Verschachtelte Eigenschaften

Du kannst auch auf verschachtelte Felder zugreifen mit Punkt-Notation:

* `properties.region` - Feld `region` innerhalb von `properties`
* `metadata.customer.segment` - Tief verschachteltes Feld

### Beispiel: Token-Verbrauch pro Modell

**Konfiguration:**

```
groupBy: ["model"]
```

**Ergebnis auf der Rechnung:**

| Position                  | Menge  | Einzelpreis | Gesamt |
| ------------------------- | ------ | ----------- | ------ |
| AI Tokens (gpt-4)         | 25.000 | 0,03€/1k    | 7,50€  |
| AI Tokens (gpt-4-turbo)   | 15.000 | 0,02€/1k    | 3,00€  |
| AI Tokens (gpt-3.5-turbo) | 5.000  | 0,005€/1k   | 0,25€  |

### Mehrere Dimensionen

Du kannst auch nach mehreren Feldern gruppieren. Jede Kombination wird zur eigenen Position:

**Konfiguration:**

```
groupBy: ["model", "endpoint"]
```

**Ergebnis:**

| Modell      | Endpoint        | Tokens |
| ----------- | --------------- | ------ |
| gpt-4       | /v1/completions | 20.000 |
| gpt-4       | /v1/chat        | 5.000  |
| gpt-4-turbo | /v1/completions | 15.000 |

<Tip>
  Je mehr Gruppierungsdimensionen, desto mehr Positionen auf der Rechnung. Wähle nur die Dimensionen, die für deine Kunden relevant sind.
</Tip>

***

## Event-Anzeigeformat

Mit dem **Event-Anzeigeformat** kannst du festlegen, wie einzelne Events in der Nutzungsaufschlüsselung auf Rechnungen angezeigt werden. Dies verbessert die Lesbarkeit für deine Kunden.

### Platzhalter verwenden

Du kannst Platzhalter verwenden, um Event-Eigenschaften in die Anzeige einzubinden:

**Beispiel:**

```
API Call to {endpoint} at {timestamp}
```

**Event:**

```json theme={null}
{
  "eventName": "api_call",
  "properties": {
    "endpoint": "/api/users",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}
```

**Anzeige in der Nutzungsaufschlüsselung:**

```
API Call to /api/users at 2026-01-15T10:30:00Z
```

### Verschachtelte Eigenschaften

Du kannst auch auf verschachtelte Eigenschaften zugreifen:

**Format:**

```
Request to {metadata.region} using {model}
```

**Event:**

```json theme={null}
{
  "properties": {
    "metadata": {
      "region": "eu-west-1"
    },
    "model": "gpt-4"
  }
}
```

**Anzeige:**

```
Request to eu-west-1 using gpt-4
```

### Platzhalter-Syntax

* **Einfache Eigenschaften**: `{propertyName}`
* **Verschachtelte Eigenschaften**: `{nested.property.name}`
* **Platzhalter müssen geschlossen sein**: `{property}` ✅, `{property` ❌
* **Platzhalternamen**: Müssen mit Buchstabe, Zahl oder Unterstrich beginnen und können Buchstaben, Zahlen, Unterstriche und Punkte enthalten

### Beispiele

| Format                               | Event-Eigenschaften                                   | Anzeige                                 |
| ------------------------------------ | ----------------------------------------------------- | --------------------------------------- |
| `API Call to {endpoint}`             | `endpoint: "/api/users"`                              | `API Call to /api/users`                |
| `{model} request at {timestamp}`     | `model: "gpt-4"`, `timestamp: "2026-01-15T10:30:00Z"` | `gpt-4 request at 2026-01-15T10:30:00Z` |
| `Storage usage: {usage.bytes} bytes` | `usage: { bytes: 1024 }`                              | `Storage usage: 1024 bytes`             |

### Standardformat (Fallback)

Wenn kein `eventDisplayFormat` definiert ist, wird automatisch das Standardformat verwendet:

```
{eventName} at {timestamp}
```

**Beispiel:**

* Event: `eventName: "api_call"`, `timestamp: "2026-01-15T10:30:00Z"`
* Anzeige: `api_call at 2026-01-15T10:30:00Z`

### Vorschau im Formular

Beim Erstellen oder Bearbeiten einer Nutzungsmetrik kannst du eine Live-Vorschau sehen, die auf einem Beispiel-Ereignis basiert. Dies hilft dir, das Format zu testen, bevor du es speicherst. Wenn kein Format definiert ist, wird die Vorschau mit dem Standardformat angezeigt.

<Note>
  Wenn ein Platzhalter auf eine Eigenschaft verweist, die im Event nicht vorhanden ist, wird der Platzhalter als leerer String angezeigt.
</Note>

***

## Praxisbeispiel: AI Usage Billing

Du bietest eine AI-Plattform an und willst Token-Verbrauch abrechnen.

### 1. Produkt konfigurieren

Erstelle ein Produkt "AI Token Verbrauch" und aktiviere die nutzungsbasierte Abrechnung:

| Einstellung | Wert               |
| ----------- | ------------------ |
| Event-Name  | `ai_request`       |
| Name        | AI Token Verbrauch |
| Aggregation | SUM                |
| Feld        | `tokens_used`      |

### 2. Events senden

Deine Anwendung sendet bei jedem AI-Request ein Event:

```json theme={null}
{
  "transactionId": "req-abc-123",
  "eventName": "ai_request",
  "timestamp": "2026-01-15T14:30:00Z",
  "customerId": "cust-xyz",
  "properties": {
    "tokens_used": 350,
    "model": "gpt-4",
    "endpoint": "/v1/completions",
    "status_code": 200
  }
}
```

### 3. Abrechnung

Am Monatsende erhält der Kunde eine Rechnung mit Aufschlüsselung:

| Position                  | Menge  | Preis             |
| ------------------------- | ------ | ----------------- |
| AI Tokens (gpt-4)         | 25.000 | 0,03€/1k = 7,50€  |
| AI Tokens (gpt-4-turbo)   | 15.000 | 0,02€/1k = 3,00€  |
| AI Tokens (gpt-3.5-turbo) | 5.000  | 0,005€/1k = 0,25€ |
| **Gesamt**                |        | **10,75€**        |

***

## Praxisbeispiel: API-Aufrufe zählen

Du willst zusätzlich die Anzahl der API-Aufrufe abrechnen - unabhängig vom Token-Verbrauch.

### Produkt konfigurieren

Erstelle ein Produkt "API Aufrufe" und aktiviere die nutzungsbasierte Abrechnung:

| Einstellung | Wert                              |
| ----------- | --------------------------------- |
| Event-Name  | `ai_request`                      |
| Name        | API Aufrufe                       |
| Aggregation | COUNT                             |
| Filter      | `status_code` in \[200, 201, 204] |

Diese Konfiguration zählt nur erfolgreiche Requests. Fehlgeschlagene Requests (500er) werden nicht berechnet.

***

## In der Abonnement-Ansicht

<Frame>
  <img src="https://mintcdn.com/fynnsubscriptionbilling/KK36EiBUGpRYjMlX/images/measurements/usage-metrics-subscription.png?fit=max&auto=format&n=KK36EiBUGpRYjMlX&q=85&s=ffd7b1d8fd96e95a2de1fb448454e95a" alt="Nutzungsmetriken im Abonnement" width="1708" height="842" data-path="images/measurements/usage-metrics-subscription.png" />
</Frame>

In der Abonnement-Ansicht siehst du die aktuelle, noch nicht abgerechnete Nutzung.

Klicke auf das Auge-Symbol, um die Details zu sehen:

<Frame>
  <img src="https://mintcdn.com/fynnsubscriptionbilling/KK36EiBUGpRYjMlX/images/measurements/metric-details.png?fit=max&auto=format&n=KK36EiBUGpRYjMlX&q=85&s=a1100322686261fc840f88e571a2bfcf" alt="Metrik Details" width="1362" height="1456" data-path="images/measurements/metric-details.png" />
</Frame>

Hier siehst du:

* Den Event Name und die Aggregation
* Den aggregierten Wert und die Anzahl der Events
* Den Zeitraum der noch nicht abgerechneten Events
* Die einzelnen Events mit Zeitstempel

***

## Inklusiveinheiten (Free Units)

Inklusiveinheiten ermöglichen es, eine bestimmte Menge kostenlos anzubieten. Erst wenn die Nutzung die Inklusiveinheiten überschreitet, wird abgerechnet.

**Beispiel:** 1.000 kostenlose API-Calls pro Monat, danach 0,01€ pro Call.

### Proration bei vorzeitiger Beendigung

Wenn ein Abonnement-Item mitten im Abrechnungszeitraum endet (z.B. durch Kündigung oder Produktwechsel), werden die Inklusiveinheiten für die letzte Abrechnungsperiode anteilig berechnet.

**Beispiel:**

* Inklusiveinheiten: 1.000 API-Calls/Monat
* Abonnement-Item endet am 15. Januar (halber Monat)
* Proratierte Inklusiveinheiten für die letzte Periode: 500 API-Calls

<Note>
  Die Proration erfolgt nur bei der **letzten Abrechnungsperiode** eines Items. Bei regulären Perioden gelten die vollen Inklusiveinheiten.
</Note>

### Inklusiveinheiten bei Gruppierung

Bei gruppierten Metriken (groupBy) werden Inklusiveinheiten **global** angewendet - nicht pro Gruppe.

**Beispiel:**

* Inklusiveinheiten: 1.000 Tokens
* Nutzung: 600 Tokens (gpt-4) + 800 Tokens (gpt-3.5) = 1.400 Tokens gesamt
* Abzüglich Inklusiveinheiten: 1.400 - 1.000 = **400 Tokens abrechenbar**

Die 400 abrechenbaren Tokens werden **proportional** auf die Gruppen verteilt:

* gpt-4: 600/1.400 × 400 = **171 Tokens**
* gpt-3.5: 800/1.400 × 400 = **229 Tokens**

<Tip>
  Die proportionale Verteilung stellt sicher, dass Inklusiveinheiten nicht für jede Gruppe einzeln abgezogen werden, was zu einer unbeabsichtigten Vervielfachung führen würde.
</Tip>

***

## Mindestabnahme (Minimum Commitment)

Die Mindestabnahme garantiert einen Mindestumsatz pro Abrechnungsperiode. Liegt die tatsächliche Nutzung unter dem Minimum, wird trotzdem das Minimum berechnet.

**Beispiel:** Mindestabnahme von 500 API-Calls/Monat:

* Nutzung: 300 Calls → Berechnet: **500 Calls** (Minimum)
* Nutzung: 800 Calls → Berechnet: **800 Calls** (tatsächlich)

### Mindestabnahme bei Gruppierung

Bei gruppierten Metriken wird die Mindestabnahme **global** auf die Gesamtnutzung angewendet.

**Beispiel:**

* Mindestabnahme: 1.000 Tokens
* Nutzung: 300 Tokens (gpt-4) + 200 Tokens (gpt-3.5) = 500 Tokens gesamt
* Da 500 \< 1.000, wird auf **1.000 Tokens** aufgerundet

Die Differenz wird **proportional** auf die Gruppen verteilt:

* gpt-4: 300/500 × 1.000 = **600 Tokens**
* gpt-3.5: 200/500 × 1.000 = **400 Tokens**

### Kombination: Inklusiveinheiten + Mindestabnahme

Werden beide Optionen verwendet, gelten folgende Regeln:

1. **Erst** werden Inklusiveinheiten von der Gesamtnutzung abgezogen
2. **Dann** wird die Mindestabnahme angewendet

**Beispiel:**

* Inklusiveinheiten: 500 Tokens
* Mindestabnahme: 1.000 Tokens
* Nutzung: 800 Tokens

Berechnung:

1. 800 - 500 (Inklusiv) = 300 Tokens
2. max(300, 1.000) = **1.000 Tokens abrechenbar**

***

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Nutzungsereignisse senden" icon="paper-plane" href="/guide/catalogue/usage-events-import">
    Lerne, wie du Nutzungsereignisse an Fynn sendest.
  </Card>

  <Card title="Aggregationstypen" icon="calculator" href="/guide/catalogue/measurements/aggregation-types/overview">
    Verstehe die verschiedenen Aggregationstypen im Detail.
  </Card>
</CardGroup>