Nutzungsmetriken - Fynn Docs

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:

Token-Verbrauch - Wie viele Tokens hat der Kunde verbraucht?
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.

Produkt öffnen

Gehe zu Katalog > Produkte und öffne das gewünschte Produkt.

Nutzungsbasierte Abrechnung aktivieren

Aktiviere den Schalter Nutzungsbasierte Abrechnung aktivieren.

Nutzungsbasierte Abrechnung am Produkt konfigurieren

Grunddaten konfigurieren

Event-Name: Welches Event soll erfasst werden (z.B. email_sent, ai_request)
Name: Anzeigename der Metrik (erscheint in der Abonnement-Ansicht)

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

Filter hinzufügen (optional)

Definiere Bedingungen, die Events erfüllen müssen, um in die Aggregation einbezogen zu werden.

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})

Mit Test Event pushen kannst du direkt ein Test-Event senden, um die Konfiguration zu prüfen.

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

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

Mehr zu Aggregationstypen

Feld angeben

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

{
  "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:

{
  "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:

{
  "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.

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

Gruppierung konfigurieren

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

Öffne den Bereich Gruppierung
Wähle die Event-Eigenschaft aus, nach der gruppiert werden soll
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

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

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:

{
  "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:

{
  "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.

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

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:

{
  "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

In der Abonnement-Ansicht siehst du die aktuelle, noch nicht abgerechnete Nutzung. Klicke auf das Auge-Symbol, um die Details zu sehen:

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

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

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

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

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:

Erst werden Inklusiveinheiten von der Gesamtnutzung abgezogen
Dann wird die Mindestabnahme angewendet

Beispiel:

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

Berechnung:

800 - 500 (Inklusiv) = 300 Tokens
max(300, 1.000) = 1.000 Tokens abrechenbar

Nächste Schritte

Nutzungsereignisse senden

Lerne, wie du Nutzungsereignisse an Fynn sendest.

Aggregationstypen

Verstehe die verschiedenen Aggregationstypen im Detail.

Loslegen

Kunden

Produkte

Nutzungsbasierte Abrechnung

Abonnements

Rechnungen

Zahlungen

Analysen

Listen & Filter

Einstellungen

Benachrichtigungen

Buchhaltung

Entwickler

​Beispiel: AI-Anwendung

​Nutzungsbasierte Abrechnung aktivieren

​Aggregationstypen

​Feld angeben

​Verschachtelte Felder

​Filter

​Verfügbare Operatoren

​Gruppierung (Group By)

​Gruppierung konfigurieren

​Verschachtelte Eigenschaften

​Beispiel: Token-Verbrauch pro Modell

​Mehrere Dimensionen

​Event-Anzeigeformat

​Platzhalter verwenden

​Verschachtelte Eigenschaften

​Platzhalter-Syntax

​Beispiele

​Standardformat (Fallback)

​Vorschau im Formular

​Praxisbeispiel: AI Usage Billing

​1. Produkt konfigurieren

​2. Events senden

​3. Abrechnung

​Praxisbeispiel: API-Aufrufe zählen

​Produkt konfigurieren

​In der Abonnement-Ansicht

​Inklusiveinheiten (Free Units)

​Proration bei vorzeitiger Beendigung

​Inklusiveinheiten bei Gruppierung

​Mindestabnahme (Minimum Commitment)

​Mindestabnahme bei Gruppierung

​Kombination: Inklusiveinheiten + Mindestabnahme

​Nächste Schritte

Nutzungsereignisse senden

Aggregationstypen

Beispiel: AI-Anwendung

Nutzungsbasierte Abrechnung aktivieren

Aggregationstypen

Feld angeben

Verschachtelte Felder

Filter

Verfügbare Operatoren

Gruppierung (Group By)

Gruppierung konfigurieren

Verschachtelte Eigenschaften

Beispiel: Token-Verbrauch pro Modell

Mehrere Dimensionen

Event-Anzeigeformat

Platzhalter verwenden

Verschachtelte Eigenschaften

Platzhalter-Syntax

Beispiele

Standardformat (Fallback)

Vorschau im Formular

Praxisbeispiel: AI Usage Billing

1. Produkt konfigurieren

2. Events senden

3. Abrechnung

Praxisbeispiel: API-Aufrufe zählen

Produkt konfigurieren

In der Abonnement-Ansicht

Inklusiveinheiten (Free Units)

Proration bei vorzeitiger Beendigung

Inklusiveinheiten bei Gruppierung

Mindestabnahme (Minimum Commitment)

Mindestabnahme bei Gruppierung

Kombination: Inklusiveinheiten + Mindestabnahme

Nächste Schritte