# DATEV Export
Source: https://docs.fynn.eu/guide/accounting/datev-export

Exportiere Buchungen im DATEV-Format und importiere sie in dein Buchhaltungsprogramm

## Buchungen exportieren

<Steps>
  <Step title="Öffne die Buchungen">
    Gehe hierzu zu [Buchungen > Exporte](https://app.fynn.eu/accounting/export).

    <Frame>
      <img alt="Buchungs-Exporte" />
    </Frame>
  </Step>

  <Step title="Export einrichten">
    Klicke auf den Button "Buchungen exportieren". Es öffnet sich ein Fenster, in dem du den Export einstellen kannst.

    * **Berater**, **Mandant**: Die Berater- und Mandantennummer findest du in DATEV. Alternativ kannst du fiktive Nummern verwenden.
    * **Sachkontenlänge**: Die Sachkontenlänge muss mit der Länge der Sachkonten in deinem Buchhaltungsprogramm übereinstimmen.
    * **Wirtschaftsjahresbeginn**: Das Datum, an dem das Wirtschaftsjahr beginnt.
    * **Exportzeitraum**: Wähle den Zeitraum aus, für den du die Buchungen exportieren möchtest.
    * **Offene Rechnungen und Belege hinzufügen**: Exportiert ebenfalls Buchungen von offenen Rechnungen und Belegen.
    * **Festgeschriebene Daten hinzufügen**: Exportiert ebenfalls festgeschriebene Buchungen inkl. der Rechnungen und dazugehörigen Belege.

    <Frame>
      <img alt="Buchungen exportieren" />
    </Frame>
  </Step>

  <Step title="Dokumente festschreiben (optional)">
    Wähle die Option "Dokumente festschreiben", um die Buchungen festzuschreiben. Anschließend sind die Buchungen nicht mehr änderbar und es entstehen Korrekturbuchungen bei Änderungen.
  </Step>

  <Step title="Export starten">
    Klicke auf den Button "Export starten". Die Buchungen werden nun exportiert und können nach wenigen Sekunden heruntergeladen werden.
    Bitte schließe in der Zwischenzeit das Fenster nicht.

    <Tip>
      Der Export kann einige Sekunden dauern, abhängig von der Anzahl der Buchungen und der Größe der Dateien.
    </Tip>
  </Step>

  <Step title="Abgeschlossen">
    Der Export ist abgeschlossen. Du kannst die heruntergeladenen Dateien in dein Buchhaltungsprogramm importieren.
  </Step>
</Steps>

Beim manuellen Export hast du die Möglichkeit, Buchungsdaten (Buchungsstapel und Stammdaten), Belegbilder sowie Informationen im DATEV-kompatiblen Format herunterzuladen und diese dann in die Kanzleisoftware zu übernehmen.

## Buchungen in DATEV importieren

Um den Buchungsstapel in **DATEV Unternehmen-Online** zu importieren, befolge folgende Schritte: [https://apps.datev.de/help-center/documents/1005516](https://apps.datev.de/help-center/documents/1005516)

Um den Buchungsstapel in **DATEV Kanzlei-Rechnungswesen** zu importieren, befolge folgende Schritte: [https://apps.datev.de/help-center/documents/1034038](https://apps.datev.de/help-center/documents/1034038)

## Buchungsschlüssel

Bei Verwendung von DATEV ist es je nach DATEV-Einstellung notwendig, Buchungsschlüssel zu hinterlegen.
Diese Buchungsschlüssel werden bei der Erstellung von Buchungen automatisch verwendet.

Um ein Buchungsschlüssel für ein Konto zu hinterlegen, füge den Buchungsschlüssel wie folgt zur Konto-Nummer hinzu: `<Buchungsschlüssel>.<Konto-Nummer>`.

**Beispiel**

* Konto-Nummer: 8400
* Buchungsschlüssel: 40
* Ergebnis: 40.8400

### Steuer-Automatik

Für die korrekte Buchung innerhalb von DATEV ist es notwendig, dass Automatikkonten für die Erlöskonten hinterlegt sind.
Andernfalls werden die entsprechenden Umsatzsteuer nicht korrekt gebucht.

## DATEVconnect online

Für eine automatisierte Übertragung der Buchungen nach DATEV kannst du die DATEVconnect online Integration nutzen.

<Card title="DATEVconnect online einrichten" icon="link" href="/integrations/accounting/datev-online">
  Richte die automatische Synchronisierung mit DATEV Kanzlei-Rechnungswesen ein.
</Card>


# Übersicht
Source: https://docs.fynn.eu/guide/accounting/introduction

Buchhaltungseinstellungen und Integrationen konfigurieren.

## Buchhaltungseinstellungen

Die Einstellungen findest du unter "Einstellungen" > ["Buchhaltung"](https://app.fynn.eu/settings/accounting/cost-centres).

### Buchungskonten

In den Buchungskonten kannst du die Konten für deine Buchhaltung konfigurieren. Hier kannst du die Konten für deine Erlöse, Kosten und Umsatzsteuer festlegen.

<Frame>
  <img alt="Buchungskonten konfigurieren" />
</Frame>

### Buchungen

In den Buchungen kannst du die Einstellungen für die Buchhaltung konfigurieren. Hier kannst du die Einstellungen für die Buchungspositionen, die passive Rechnungsabgrenzungsposten und Weiteres festlegen.

<Frame>
  <img alt="Buchhaltung konfigurieren" />
</Frame>

## Integrationen

Aktuell unterstützt Fynn die Integration mit folgenden Buchhaltungsprogrammen:

<CardGroup>
  <Card title="DATEV" href="/integrations/accounting/datev">
    Die DATEV-Integration ermöglicht es dir, Kundenstämme, Buchungen und Rechnungen aus Fynn in dein DATEV-System zu übertragen.
  </Card>
</CardGroup>

Um eine Integration einzurichten, klicke auf die entsprechende Integration und folge den weiteren Schritten.

## Weitere Funktionen

<CardGroup>
  <Card title="Monatsabschlüsse" icon="lock" href="/guide/accounting/period-close">
    Abrechnungsperioden abschließen und nachträgliche Buchungen verhindern.
  </Card>

  <Card title="DATEV Export" icon="file-export" href="/guide/accounting/datev-export">
    Exportiere Buchungen im DATEV-Format.
  </Card>

  <Card title="PRAP" icon="calendar-days" href="/guide/accounting/prap">
    Passive Rechnungsabgrenzungsposten automatisch bilden.
  </Card>
</CardGroup>

## Zusätzliche Rechnungs-Empfänger

In den Einstellungen kannst du zusätzliche Rechnungs-Empfänger hinzufügen. Diese erhalten eine Kopie der Rechnung per E-Mail.

Die Einstellung findest du unter "Einstellungen" > "Benachrichtigungen" > "Zusätzliche Rechnungs-Empfänger".

<Frame>
  <img alt="Zusätzliche Rechnungs-Empfänger" />
</Frame>


# Monatsabschlüsse
Source: https://docs.fynn.eu/guide/accounting/period-close

Abrechnungsperioden abschließen und nachträgliche Buchungen in abgeschlossenen Monaten verhindern

## Übersicht

Mit Monatsabschlüssen kannst du vergangene Abrechnungsperioden sperren, sodass keine nachträglichen Buchungen mehr in abgeschlossenen Monaten erfolgen. Das ist besonders wichtig für die periodengerechte Abgrenzung und eine saubere Buchhaltung.

<Info>
  Diese Funktion erfordert die Berechtigung **Monatsabschluss** unter **Einstellungen > Benutzer & Berechtigungen > Rollen**.
</Info>

## Wie funktioniert der Monatsabschluss?

Wenn ein Monat abgeschlossen wird, verhindert Fynn, dass Erlöse nachträglich in diesen Monat gebucht werden.

### Periodengerechte Verbuchung auf Monatsebene

<Info>
  Diese Funktion muss für deinen Tenant aktiviert werden. Kontaktiere den Support, um sie freizuschalten.
</Info>

Fynn kann Erlöse automatisch in den **richtigen Monat** verbuchen — auch wenn die Rechnung erst im Folgemonat finalisiert wird. Voraussetzung: Der Vormonat ist noch **offen** (nicht abgeschlossen).

Das entspricht dem Grundsatz der Periodenabgrenzung nach §252 Abs. 1 Nr. 5 HGB: Erträge werden der Periode zugeordnet, in der sie wirtschaftlich entstanden sind — unabhängig vom Rechnungsdatum.

```
Beispiel 1 – Leistung komplett im Vormonat:
- Leistungszeitraum: 01.03.2026 – 31.03.2026
- Rechnung finalisiert am: 05.04.2026
- März ist offen
- Ergebnis: Der Erlös wird im März verbucht (nicht im April)

Beispiel 2 – Leistung über Monatsgrenze:
- Leistungszeitraum: 15.03.2026 – 15.04.2026
- Rechnung finalisiert am: 15.04.2026
- März ist offen
- Ergebnis: Der März-Anteil wird im März verbucht,
  der April-Anteil im April (anteilig nach 30/360-Konvention)

Beispiel 3 – Vormonat abgeschlossen:
- Leistungszeitraum: 01.03.2026 – 31.03.2026
- Rechnung finalisiert am: 05.04.2026
- März ist abgeschlossen
- Ergebnis: Der Erlös wird im April verbucht
  (abgeschlossene Perioden werden nicht mehr verändert)
```

Das gilt für alle Belegtypen: Rechnungen, Gutschriften und Stornorechnungen.

### Erlösaufteilung bei Geschäftsjahreswechsel

Die monatliche Periodenverbuchung deckt auch den Geschäftsjahreswechsel ab. Wenn ein Leistungszeitraum über das Geschäftsjahresende hinausgeht, teilt Fynn die Buchungen automatisch an der Monatsgrenze auf:

```
Beispiel:
- Leistungszeitraum: 01.12.2025 – 31.01.2026
- Rechnung finalisiert am: 20.01.2026
- Dezember 2025 ist offen
- Ergebnis: Der Dezember-Anteil wird im Dezember 2025 verbucht,
  der Januar-Anteil im Januar 2026
```

Ist der Zielmonat (hier: Dezember 2025) bereits abgeschlossen, wird die Aufteilung übersprungen — der gesamte Erlös wird im Finalisierungsmonat verbucht.

## Monat abschließen

<Steps>
  <Step title="Buchungsposten öffnen">
    Gehe zu **Buchhaltung > Buchungsposten**. In der linken Seitenleiste siehst du den Bereich **Monate** mit einer Übersicht aller verfügbaren Monate.
  </Step>

  <Step title="Monat auswählen">
    Klicke auf **Monat abschließen**. Es öffnet sich ein Dialog, in dem du den gewünschten Monat auswählen kannst. Monate, die nicht abgeschlossen werden können, sind ausgegraut und zeigen den Grund an.
  </Step>

  <Step title="Abschluss bestätigen">
    Wähle den Monat aus und bestätige mit **Monat abschließen**. Der Monat wird als abgeschlossen markiert und kann nicht mehr geöffnet werden.
  </Step>
</Steps>

## Regeln für Monatsabschlüsse

Beim Abschließen von Monaten gelten folgende Regeln:

| Regel                       | Beschreibung                                                                                                    |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Nur vergangene Monate**   | Der aktuelle und zukünftige Monate können nicht abgeschlossen werden                                            |
| **Sequenzieller Abschluss** | Monate müssen der Reihe nach abgeschlossen werden — März kann nicht vor Januar und Februar abgeschlossen werden |
| **Nicht rückgängig**        | Ein abgeschlossener Monat kann nicht wieder geöffnet werden                                                     |

## Monatsübersicht

In der Seitenleiste unter **Monate** siehst du alle Monate gruppiert nach Jahr:

* **Abgeschlossen** — Monat ist gesperrt, mit Zeitstempel des Abschlusses
* **Offen** — Monat kann noch abgeschlossen werden

## Auswirkungen auf Buchungen

Ein Monatsabschluss hat folgende Auswirkungen:

### Was wird verhindert?

* **Erlösbuchungen** in abgeschlossene Monate — weder durch periodengerechte Zuordnung noch durch Geschäftsjahreswechsel-Aufteilung
* Bei Stornierungen werden zuvor aufgeteilte Buchungen nicht rückwirkend in den abgeschlossenen Monat gebucht

### Was bleibt möglich?

* Rechnungen können weiterhin erstellt und finalisiert werden
* Zahlungen können weiterhin erfasst werden
* Neue Buchungen werden automatisch im nächsten offenen Monat verbucht
* Gutschriften und Stornierungen für abgeschlossene Monate werden im aktuellen Monat verbucht (GoBD-konform)

<Warning>
  Stelle sicher, dass alle Buchungen eines Monats vollständig und korrekt sind, bevor du den Monat abschließt. Der Abschluss kann nicht rückgängig gemacht werden.
</Warning>

## Berechtigung

Um Monate abschließen zu können, benötigst du die Berechtigung **Monatsabschluss** (`accounting:close-month`). Diese kann unter **Einstellungen > Benutzer & Berechtigungen > Rollen** zugewiesen werden.

Ohne diese Berechtigung ist der Button **Monat abschließen** nicht sichtbar.

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Warum kann ich einen Monat nicht abschließen?">
    Mögliche Gründe:

    * **Aktueller Monat**: Der aktuelle Monat kann erst nach Ablauf abgeschlossen werden
    * **Vorherige Monate offen**: Alle vorherigen Monate im selben Jahr müssen zuerst abgeschlossen werden
    * **Bereits abgeschlossen**: Der Monat wurde bereits abgeschlossen
    * **Fehlende Berechtigung**: Du benötigst die Berechtigung `accounting:close-month`
  </Accordion>

  <Accordion title="Was passiert mit Rechnungen, die einen abgeschlossenen Monat betreffen?">
    Rechnungen können weiterhin erstellt werden. Ist die periodengerechte Verbuchung aktiv, wird der Erlös automatisch dem nächsten offenen Monat zugeordnet. Ist der Vormonat abgeschlossen, wird der gesamte Erlös im Finalisierungsmonat verbucht — keine Buchung landet in einem abgeschlossenen Monat.
  </Accordion>

  <Accordion title="Kann ich einen Monatsabschluss rückgängig machen?">
    Nein, ein Monatsabschluss ist endgültig. Stelle sicher, dass alle Buchungen korrekt sind, bevor du einen Monat abschließt.
  </Accordion>

  <Accordion title="Muss ich jeden Monat einzeln abschließen?">
    Ja, Monate müssen sequenziell abgeschlossen werden. Du kannst nicht direkt zu einem späteren Monat springen, ohne die vorherigen Monate abgeschlossen zu haben.
  </Accordion>
</AccordionGroup>


# Rechnungsabgrenzung (PRAP)
Source: https://docs.fynn.eu/guide/accounting/prap

Passive Rechnungsabgrenzungsposten automatisch bilden und auflösen

## Übersicht

Mit Fynn kannst du ganz einfach passive Rechnungsabgrenzungsposten (PRAP) für deine Forderungen anlegen und diese über die Zeit automatisch wieder auflösen.

Dies kannst du in dein Einstellungen unter "Buchhaltung" > "Buchungen" > "PRAP Buchungen" aktivieren.

## Wie werden PRAP gebildet?

In Fynn erstellen wir passive Rechnungsabgrenzungsposten auf Grundlage des Nettobetrags der Forderungen. Da die Mehrwertsteuer sofort zu zahlen ist, berücksichtigen wir sie nicht im Rahmen der Abgrenzung.

Für jede Rechnungsposition, sofern eine Buchung je Rechnungsposition aktiviert ist, erfolgt eine gleichmäßige Verteilung des Nettobetrags über den zugrundeliegenden Leistungszeitraum.
Beträge, die sich auf den Monat der Rechnungsstellung beziehen, unterliegen dabei keiner Abgrenzung.

## Wie werden PRAP aufgelöst?

Die Auflösung der passiven Rechnungsabgrenzungsposten erfolgt ebenfalls gleichmäßig über den Leistungszeitraum. Dabei wird der Betrag des PRAPs monatlich um den entsprechenden Betrag reduziert.
Die Buchungen werden automatisch erstellt und in die Zukunft datiert. Diese können in der Buchungsübersicht eingesehen werden.

## Was passiert bei der Stornierung einer Rechnung?

Bei Stornierung einer Rechnung werden die passiven Rechnungsabgrenzungsposten, sowie die Rechnungsbuchung automatisch mit einer Gegenbuchung aufgelöst.

## PRAP Buchungsschlüssel

Sofern die passive Rechnungsabgrenzungsposten aktiviert sind, wird für die Buchungen der passive Rechnungsabgrenzungsposten der Buchungsschlüssel `40` verwendet.
Somit wird sichergestellt, dass der Vorsteuerabzug korrekt erfolgt.

Ist ein abweichender Buchungsschlüssel gewünscht, so ist für das Buchungskonto "Passive Rechnungsabgrenzung" entsprechend mit `<Buchungsschlüssel>.<Buchungskontonummer>` zu definieren.

<Tip>
  Weitere Informationen zu Buchungsschlüsseln findest du unter [DATEV Export](/guide/accounting/datev-export#buchungsschluessel).
</Tip>

## PRAP aktivieren

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe zu [Einstellungen > Buchhaltung > Buchungen](https://app.fynn.eu/settings/accounting/postings)
  </Step>

  <Step title="PRAP aktivieren">
    Aktiviere die Option "PRAP Buchungen". Die Buchungen werden nun automatisch erstellt.
  </Step>
</Steps>

<Warning>
  Stelle sicher, dass die entsprechenden Buchungskonten für die passive Rechnungsabgrenzung konfiguriert sind, bevor du PRAP aktivierst.
</Warning>


# Kleinstbetragsdifferenzen automatisch ausbuchen
Source: https://docs.fynn.eu/guide/accounting/small-difference-write-off

Restbeträge aus Unterzahlungen per Überweisung automatisch ausbuchen, wenn die Differenz einen konfigurierbaren Schwellenwert unterschreitet.

## Übersicht

Wenn ein Kunde eine Rechnung per Überweisung leicht unterbezahlt, bleibt häufig ein kleiner offener Restbetrag stehen, der manuell nachbearbeitet werden muss. Mit dieser Einstellung bucht Fynn solche Differenzen automatisch aus, sobald der verbleibende offene Betrag strikt unterhalb eines von dir festgelegten Schwellenwerts liegt.

Das Ergebnis: Die Rechnung gilt als vollständig beglichen, der Restbetrag wird ausgebucht, und dein Team muss nicht für jeden Kleinstbetrag manuell eingreifen. Der Kunde wird darüber nicht benachrichtigt.

<Info>
  Die Funktion greift ausschließlich bei Zahlungen per Überweisung und nur bei Unterzahlungen. Überzahlungen werden nicht berührt.
</Info>

## Einstellung konfigurieren

<Steps>
  <Step title="Grundeinstellungen öffnen">
    Gehe zu [Einstellungen > Buchhaltung > Grundeinstellungen](https://app.fynn.eu/settings/accounting/settings).
  </Step>

  <Step title="Funktion aktivieren">
    Aktiviere den Schalter **Kleinstbetragsdifferenzen ausbuchen**.
  </Step>

  <Step title="Schwellenwert festlegen">
    Gib den Schwellenwert in Euro ein. Liegt der offene Restbetrag strikt unterhalb dieses Betrags, löst Fynn die automatische Ausbuchung aus.

    <Tip>
      Ein üblicher Wert liegt zwischen 0,50 € und 2,00 €. Wähle einen Betrag, der für dein Geschäft typische Überweisungsungenauigkeiten abdeckt, ohne echte Unterzahlungen zu verbergen.
    </Tip>
  </Step>
</Steps>

Die Einstellung gilt sofort für alle ab dann eingehenden Zahlungen. Bereits beglichene oder manuell abgeschlossene Rechnungen sind nicht betroffen.

## Buchungskonten

Je nach Steuerfall bucht Fynn die Differenz auf ein eigenes Forderungsverlust-Konto. Der Gegenposten ist jeweils das Debitorenkonto.

| Steuerfall                                   | SKR03 |
| -------------------------------------------- | ----- |
| 19 % Umsatzsteuer                            | 2406  |
| 7 % Umsatzsteuer                             | 2401  |
| Steuerfrei (z.B. EU Reverse Charge, Ausfuhr) | 2400  |

Die Konten werden in den Einstellungen angezeigt und lassen sich bei Bedarf über den Kontenrahmen anpassen.

## Was passiert bei einer Ausbuchung?

Sobald eine Überweisung eingeht und der Restbetrag die Bedingung erfüllt, läuft folgendes ab:

1. Fynn legt eine Rechnungsanpassung (Bagatelle) an, die den offenen Restbetrag auf null setzt.
2. Für jeden Steuersatz der Rechnung entsteht ein eigener Buchungssatz auf das jeweilige Forderungsverlust-Konto. Der Buchungstext lautet **Automatische Ausbuchung wg. Kleinstbetragsdifferenz**. Gemischte Steuersätze werden dabei vollständig unterstützt.
3. Bei 19 % und 7 % sind die verwendeten Konten DATEV-Automatikkonten: Die Umsatzsteuer wird automatisch berichtigt, ohne separaten Buchungsschlüssel. Für steuerfreie Positionen wird das Sammelkonto ohne Steuerschlüssel bespielt.
4. Die Rechnung ist vollständig beglichen.
5. Der Kunde erhält **keine** E-Mail-Benachrichtigung.

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Gilt die Einstellung auch für andere Zahlungsarten?">
    Nein. Kleinstbetragsdifferenzen werden nur bei Überweisungen ausgebucht. Kreditkartenzahlungen, SEPA-Lastschriften und andere Zahlungsarten bleiben unverändert.
  </Accordion>

  <Accordion title="Was passiert, wenn die Differenz genau dem Schwellenwert entspricht?">
    Genau gleich zählt nicht. Die Ausbuchung greift nur, wenn der Restbetrag **strikt kleiner** als der Schwellenwert ist. Eine Differenz in Höhe des Schwellenwerts bleibt offen.
  </Accordion>

  <Accordion title="Werden auch Rechnungen mit 7 % oder gemischten Steuersätzen ausgebucht?">
    Ja. Fynn erstellt für jeden Steuersatz der Rechnung einen eigenen Buchungssatz auf das jeweilige Forderungsverlust-Konto. Bei 19 % und 7 % erfolgt die Umsatzsteuer-Korrektur automatisch über das DATEV-Automatikkonto, bei steuerfreien Positionen ohne Steuerschlüssel. Gemischte Rechnungen werden vollständig unterstützt.
  </Accordion>

  <Accordion title="Bekommt der Kunde eine Benachrichtigung?">
    Nein. Bei einer automatischen Ausbuchung wird keine E-Mail an den Kunden gesendet.
  </Accordion>

  <Accordion title="Wie finde ich ausgebuchte Differenzen in der Buchhaltung?">
    Die Buchungen tragen den Text **Automatische Ausbuchung wg. Kleinstbetragsdifferenz** und lassen sich so jederzeit in der Buchungsübersicht und im DATEV-Export nachvollziehen.
  </Accordion>

  <Accordion title="Kann ich die Einstellung auch im Steuerberater-Portal konfigurieren?">
    Ja. Der Einrichtungs-Assistent im Steuerberater-Portal enthält im Schritt Buchungslogik dieselbe Einstellung. Änderungen dort wirken sich direkt auf deine Organisation aus.
  </Accordion>
</AccordionGroup>


# Steuerberater-Portal
Source: https://docs.fynn.eu/guide/accounting/tax-advisor-portal

Gib deiner Steuerberatung einen eigenen Zugang zu Belegen, DATEV-Auswertungen und Buchhaltungsdaten, ohne Zugriff auf dein operatives Konto.

Deine Steuerberatung arbeitet jetzt in einem eigenen Portal mit den Daten, die sie wirklich braucht: Belege, DATEV-Auswertungen und die relevanten Buchhaltungsdaten. Dein operatives Konto bleibt davon getrennt, deine Steuerberatung sieht keine Vertriebs- oder Produktdaten.

## Zugang einrichten

<Steps>
  <Step title="Einladung versenden">
    Lade deine Steuerberatung wie einen Benutzer ein und wähle als Ziel das Steuerberater-Portal. Sie erhält daraufhin eine E-Mail mit einem Anmeldelink.
  </Step>

  <Step title="Anmeldung per Link">
    Die Anmeldung läuft per Magic-Link, also über den Link aus der E-Mail und ohne eigenes Passwort. Ein neuer Link lässt sich jederzeit anfordern.
  </Step>

  <Step title="Einrichtung abschließen">
    Beim ersten Login führt ein Assistent durch die Grundeinstellungen der Buchhaltung. Danach steht das Portal bereit.
  </Step>
</Steps>

## Der Einrichtungs-Assistent

Der Assistent klärt einmalig die Grundlagen, damit der DATEV-Export von Anfang an zum Kontenrahmen deiner Steuerberatung passt:

* **Kontenrahmen**: Auswahl des passenden Kontenrahmens, zum Beispiel SKR03 oder SKR04.
* **Nummernkreise**: die Nummernkreise für Debitoren und Sachkonten.
* **Kostenstellen**: optionale Kostenstellen für die Zuordnung.
* **Wirtschaftsjahr**: Beginn des Wirtschaftsjahrs für die periodengerechte Zuordnung.

Die Einstellungen lassen sich später jederzeit anpassen.

## Was deine Steuerberatung sieht

* **Belege**: alle Ausgangsbelege mit ihren Referenzen, direkt einsehbar und filterbar.
* **DATEV-Auswertungen**: die Buchungsstapel je Zeitraum mit Anzahl, Aufschlüsselung bis auf den einzelnen Beleg und der Möglichkeit, einen Export erneut zu erzeugen.
* **Buchhaltungsdaten**: die relevanten Kennzahlen und Auswertungen an einem Ort.

<Info>
  Das Steuerberater-Portal wird pro Organisation freigeschaltet. Wenn du es nutzen möchtest, wende dich an den Fynn-Support.
</Info>

Wie der DATEV-Export selbst aufgebaut ist, liest du unter [DATEV-Export](/guide/accounting/datev-export).


# Steuerberechnung
Source: https://docs.fynn.eu/guide/accounting/tax-calculation

Lege fest, ob die Umsatzsteuer auf neuen Belegen horizontal pro Position oder vertikal auf Belegebene berechnet wird

## Übersicht

Auf Belegen mit mehreren Positionen entscheidet die Steuerberechnung, an welcher Stelle die Umsatzsteuer kaufmännisch gerundet wird. Das Ergebnis kann sich dadurch um wenige Cent unterscheiden. Du wählst die Methode in den Einstellungen und sie gilt für alle Belege, die du ab dann ausstellst.

<Info>
  Die Einstellung findest du unter [Einstellungen > Buchhaltung > Grundeinstellungen](https://app.fynn.eu/settings/accounting/settings).
</Info>

## Horizontal oder vertikal?

Beide Verfahren runden kaufmännisch, nur an unterschiedlicher Stelle:

| Methode                       | So wird gerundet                                                                                                                                |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Horizontal** (pro Position) | Jede Position rundet ihre Steuer einzeln, anschließend werden die gerundeten Beträge summiert.                                                  |
| **Vertikal** (auf Belegebene) | Die Positionen werden je Steuersatz zusammengefasst, die Steuer wird einmal auf der Summe gerundet und exakt auf die Positionen zurückverteilt. |

Das folgende Beispiel zeigt den Unterschied an zehn gleichen Positionen:

```
10 Positionen zu je 9,99 € mit 19 % Umsatzsteuer

Horizontal: 10 × runden(9,99 € × 19 %) = 10 × 1,90 € = 19,00 €
Vertikal:   runden(99,90 € × 19 %)      = runden(18,981 €) = 18,98 €
```

Die zwei Cent Differenz entstehen, weil beim horizontalen Verfahren jede Position für sich aufrundet und sich diese Rundungen aufsummieren.

<Tip>
  Vertikal ist konform zur E-Rechnung (EN 16931). Der ausgewiesene Steuerbetrag entspricht exakt der Summe der Buchungen, was die Übergabe an die Buchhaltung und an DATEV sauber hält.
</Tip>

## Was die Umstellung bedeutet

Die Methode wird beim Erstellen eines Belegs fest hinterlegt und ändert sich danach nicht mehr. Eine Umstellung wirkt deshalb nur in eine Richtung: nach vorne.

* Belege, die du **ab der Umstellung** ausstellst, nutzen die neue Methode.
* Bereits erstellte Belege, **auch Entwürfe**, behalten ihre bisherige Berechnung.
* Gutschriften und Stornorechnungen übernehmen die Methode des ursprünglichen Belegs, damit der Bezug exakt aufgeht.

<Warning>
  Eine Umstellung verändert keine bestehenden Belege. So bleibt jeder Beleg dauerhaft nachvollziehbar, auch wenn du die Methode später wechselst.
</Warning>

## Steuerberechnung umstellen

<Steps>
  <Step title="Öffne die Grundeinstellungen">
    Gehe zu [Einstellungen > Buchhaltung > Grundeinstellungen](https://app.fynn.eu/settings/accounting/settings).
  </Step>

  <Step title="Methode wählen">
    Wähle im Abschnitt **Steuerberechnung** zwischen vertikal und horizontal.
  </Step>

  <Step title="Umstellung bestätigen">
    Bestätige im Dialog, dass die neue Methode nur für ab dann ausgestellte Belege gilt. Die Umstellung wird sofort übernommen.
  </Step>
</Steps>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Welche Methode nutzt meine Organisation standardmäßig?">
    Neue Organisationen starten mit der vertikalen Berechnung. Bestehende Organisationen behalten ihre bisherige (horizontale) Methode, bis du sie umstellst.
  </Accordion>

  <Accordion title="Ändert die Umstellung bereits ausgestellte Rechnungen?">
    Nein. Jeder Beleg behält die Methode, mit der er erstellt wurde, auch Entwürfe. Nur ab dann neu ausgestellte Belege nutzen die gewählte Methode.
  </Accordion>

  <Accordion title="Welche Methode soll ich wählen?">
    Vertikal, wenn du E-Rechnungen nach EN 16931 ausstellst oder den Steuerausweis exakt zu den Buchungen passend halten möchtest. Horizontal bildet das frühere Verhalten ab.
  </Accordion>
</AccordionGroup>


# Kundeneinstellungen
Source: https://docs.fynn.eu/guide/ai-assistant/customer-settings

Kundeneinstellungen per KI-Assistent abfragen und ändern – Mahnwesen, Abrechnung, Rechnungsfreigabe und Zahlungsziel.

Der KI-Assistent kann **Kundeneinstellungen anzeigen** und **per Bulk-Aktion ändern** – direkt im Chat, ohne die Einstellungsseite jedes Kunden einzeln aufrufen zu müssen. Unterstützt werden:

* **Mahnwesen** (Dunning) – deaktivieren / aktivieren
* **Abrechnung** (Billing) – deaktivieren / aktivieren
* **Manuelle Rechnungsfreigabe** – aktivieren / deaktivieren
* **Zahlungsziel** – auf einen neuen Wert setzen

***

## Einstellungen abfragen

Frage den Assistenten nach dem aktuellen Status der Kundeneinstellungen. Er ruft die Daten automatisch ab und fasst sie zusammen.

### Beispiel-Anfragen

| Anfrage                                                    | Was passiert                                                                                             |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| "Ist das Mahnwesen für Kunde Müller aktiv?"                | Ruft die Einstellungen von Kunde Müller ab und zeigt den Dunning-Status                                  |
| "Welche Einstellungen hat Kunde D26-00100043?"             | Zeigt alle Einstellungen des Kunden (Mahnwesen, Abrechnung, Rechnungsfreigabe, Zahlungsziel, E-Rechnung) |
| "Ist die Abrechnung für diesen Kunden aktiv?"              | Auf der Kundendetailseite – nutzt den Seitenkontext                                                      |
| "Hat Kunde ACME die manuelle Rechnungsfreigabe aktiviert?" | Prüft den Status der manuellen Freigabe                                                                  |

### Ablauf

<Steps>
  <Step title="Kunde ermitteln">
    Der Assistent sucht den Kunden per Name, Kundennummer oder nutzt den Seitenkontext. Bei mehreren Treffern wird eine **Auswahlkarte** angezeigt.
  </Step>

  <Step title="Einstellungen abrufen">
    Alle Kundeneinstellungen werden auf einen Blick abgerufen: Mahnwesen, Abrechnung, Rechnungsfreigabe, Zahlungsziel und E-Rechnungsformat.
  </Step>

  <Step title="Ergebnis und Vorschlag">
    Der Assistent beantwortet deine Frage und bietet proaktiv an, die Einstellung zu ändern – z.B. *"Das Mahnwesen ist aktiv. Soll ich es deaktivieren?"*
  </Step>
</Steps>

<Info>
  Die Einstellungsabfrage funktioniert auch im Seitenkontext. Auf einer **Kundendetailseite** reicht "Welche Einstellungen hat dieser Kunde?" – der Assistent weiß, welcher Kunde gemeint ist.
</Info>

***

## Einstellungen ändern

Alle Änderungen an Kundeneinstellungen folgen dem gleichen **Bestätigungs-Workflow**: Der Assistent zeigt eine Bestätigungskarte an, und du bestätigst oder brichst ab. Bei mehreren Kunden wird die Änderung **sequenziell** für jeden Kunden einzeln durchgeführt.

<Warning>
  Einstellungsänderungen werden **nur nach expliziter Bestätigung** über den Button ausgeführt. Ein einfaches "Ja" im Chat reicht nicht aus.
</Warning>

***

### Mahnwesen deaktivieren / aktivieren

Deaktiviere oder aktiviere das Mahnwesen (Dunning) für einen oder mehrere Kunden gleichzeitig. Wenn das Mahnwesen deaktiviert ist, werden keine automatischen Mahnungen mehr für den Kunden erstellt.

#### Beispiel-Anfragen

| Anfrage                                           | Was passiert                                              |
| ------------------------------------------------- | --------------------------------------------------------- |
| "Deaktiviere das Mahnwesen für Kunde Müller"      | Deaktiviert das Mahnwesen für einen Kunden                |
| "Pausiere die Mahnung für Kunden A und B"         | Deaktiviert das Mahnwesen für mehrere Kunden gleichzeitig |
| "Aktiviere das Mahnwesen für Kunde Müller wieder" | Reaktiviert das Mahnwesen                                 |

#### Ablauf

<Steps>
  <Step title="Kunden ermitteln">
    Der Assistent sucht die genannten Kunden. Bei mehreren Treffern pro Name wird eine Auswahlkarte angezeigt.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und die geplante Aktion (z.B. "Mahnwesen für 2 Kunden deaktivieren"). Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird die Einstellung für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

***

### Abrechnung deaktivieren / aktivieren

Deaktiviere oder aktiviere die automatische Abrechnung (Billing) für einen oder mehrere Kunden. Wenn die Abrechnung deaktiviert ist, werden keine neuen Rechnungen für den Kunden generiert.

#### Beispiel-Anfragen

| Anfrage                                             | Was passiert                                  |
| --------------------------------------------------- | --------------------------------------------- |
| "Deaktiviere die Abrechnung für Kunde ACME GmbH"    | Deaktiviert die Abrechnung für einen Kunden   |
| "Stoppe die Rechnungserstellung für Kunden A und B" | Deaktiviert die Abrechnung für mehrere Kunden |
| "Aktiviere die Abrechnung für Kunde ACME wieder"    | Reaktiviert die Abrechnung                    |

#### Ablauf

<Steps>
  <Step title="Kunden ermitteln">
    Der Assistent sucht die genannten Kunden. Bei mehreren Treffern pro Name wird eine Auswahlkarte angezeigt.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und die geplante Aktion (z.B. "Abrechnung für 1 Kunden deaktivieren"). Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird die Einstellung für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

***

### Manuelle Rechnungsfreigabe aktivieren / deaktivieren

Aktiviere oder deaktiviere die manuelle Rechnungsfreigabe für einen oder mehrere Kunden. Wenn die manuelle Freigabe aktiviert ist, müssen Rechnungen für diesen Kunden vor dem Versand manuell geprüft und freigegeben werden.

#### Beispiel-Anfragen

| Anfrage                                                     | Was passiert                              |
| ----------------------------------------------------------- | ----------------------------------------- |
| "Aktiviere die manuelle Rechnungsfreigabe für Kunde Müller" | Schaltet die manuelle Freigabe ein        |
| "Schalte die manuelle Freigabe für Kunden A und B ein"      | Aktiviert die Freigabe für mehrere Kunden |
| "Deaktiviere die Rechnungsfreigabe für Kunde Müller"        | Schaltet zurück auf automatische Freigabe |

#### Ablauf

<Steps>
  <Step title="Kunden ermitteln">
    Der Assistent sucht die genannten Kunden. Bei mehreren Treffern pro Name wird eine Auswahlkarte angezeigt.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und die geplante Aktion (z.B. "Manuelle Rechnungsfreigabe für 2 Kunden aktivieren"). Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird die Einstellung für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

***

### Zahlungsziel ändern

Ändere das Zahlungsziel (payableInDays) für einen oder mehrere Kunden gleichzeitig. Der Wert bestimmt, wie viele Tage nach Rechnungsstellung die Zahlung fällig ist.

#### Beispiel-Anfragen

| Anfrage                                                    | Was passiert                                            |
| ---------------------------------------------------------- | ------------------------------------------------------- |
| "Setze das Zahlungsziel für Kunde Müller auf 30 Tage"      | Ändert das Zahlungsziel auf 30 Tage                     |
| "Passe das Zahlungsziel von Kunden A und B auf 14 Tage an" | Ändert das Zahlungsziel für mehrere Kunden gleichzeitig |
| "Zahlungsfrist für alle Kunden auf 60 Tage"                | Der Assistent sucht die Kunden und ändert die Frist     |

#### Ablauf

<Steps>
  <Step title="Kunden und Wert ermitteln">
    Der Assistent sucht die genannten Kunden und ermittelt die gewünschte Zahlungsfrist. Falls der Wert nicht angegeben wurde, fragt er gezielt nach.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und das neue Zahlungsziel. Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird das Zahlungsziel für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

<Tip>
  Gültiger Bereich für das Zahlungsziel: **1 bis 365 Tage**.
</Tip>

***

## Bestätigungskarte

Alle Einstellungsänderungen zeigen eine Bestätigungskarte im Chat an:

<AccordionGroup>
  <Accordion title="Bestätigen" icon="circle-check">
    Klicke auf **Bestätigen**, um die Änderung auszuführen. Die Buttons werden nach dem Klick deaktiviert. Bei mehreren Kunden siehst du einen Fortschritt, bis alle Änderungen abgeschlossen sind.
  </Accordion>

  <Accordion title="Abbrechen" icon="circle-xmark">
    Klicke auf **Abbrechen**, um den Vorgang abzubrechen. Der Assistent bestätigt die Stornierung und du kannst eine neue Anfrage stellen.
  </Accordion>

  <Accordion title="Zeitlimit" icon="clock">
    Die Bestätigung hat ein Zeitfenster von **5 Minuten**. Danach wird sie ungültig und der Assistent bittet dich, den Vorgang erneut zu starten.
  </Accordion>
</AccordionGroup>

<Info>
  Während die Bestätigungskarte angezeigt wird, ist das Chat-Eingabefeld deaktiviert. Du musst zuerst bestätigen oder abbrechen, bevor du eine neue Nachricht senden kannst.
</Info>

***

## Beispiel-Szenarien

### Einstellung abfragen und ändern

> **Du:** Ist das Mahnwesen für Kunde Müller aktiv?
>
> **Assistent:** Das Mahnwesen für Müller GmbH ist aktuell **aktiv**. Die Mahngebühren sind ebenfalls aktiviert und das Zahlungsziel beträgt 14 Tage. Soll ich das Mahnwesen deaktivieren?
>
> **Du:** Ja, deaktiviere es
>
> *(Bestätigungskarte: "Mahnwesen für 1 Kunden deaktivieren" – Müller GmbH)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Das Mahnwesen für Müller GmbH wurde deaktiviert.

### Bulk-Änderung für mehrere Kunden

> **Du:** Deaktiviere die Abrechnung für Kunden Müller und Schmidt
>
> **Assistent:** *(sucht Kunden, findet eindeutige Treffer)*
>
> *(Bestätigungskarte: "Abrechnung für 2 Kunden deaktivieren" – Müller GmbH, Schmidt AG)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** ✓ Abrechnung für Müller GmbH deaktiviert.
> ✓ Abrechnung für Schmidt AG deaktiviert.
> Beide Einstellungen wurden erfolgreich aktualisiert.

### Abbruch einer Änderung

> **Du:** Aktiviere die manuelle Rechnungsfreigabe für Kunde ACME
>
> *(Bestätigungskarte: "Manuelle Rechnungsfreigabe für 1 Kunden aktivieren" – ACME GmbH)*
>
> **Du:** *(klickt "Abbrechen")*
>
> **Assistent:** Der Vorgang wurde abgebrochen. Die Einstellungen wurden nicht geändert.

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Welche Einstellungen kann ich per Assistent ändern?">
    Aktuell: Mahnwesen (aktivieren/deaktivieren), Abrechnung (aktivieren/deaktivieren), manuelle Rechnungsfreigabe (aktivieren/deaktivieren) und Zahlungsziel (Anzahl Tage). Weitere Einstellungen werden nach und nach ergänzt.
  </Accordion>

  <Accordion title="Kann ich Einstellungen für viele Kunden gleichzeitig ändern?">
    Ja – nenne einfach mehrere Kundennamen oder -nummern in deiner Anfrage. Der Assistent verarbeitet sie sequenziell und zeigt eine Zusammenfassung.
  </Accordion>

  <Accordion title="Was passiert bei einem Fehler während der Bulk-Änderung?">
    Der Assistent verarbeitet jeden Kunden einzeln. Wenn bei einem Kunden ein Fehler auftritt, werden die anderen trotzdem aktualisiert. Am Ende siehst du eine Zusammenfassung mit Erfolgs- und Fehlerstatus pro Kunde.
  </Accordion>

  <Accordion title="Kann ich sehen, was die aktuelle Einstellung ist, bevor ich sie ändere?">
    Ja – frage einfach "Welche Einstellungen hat Kunde X?" oder "Ist das Mahnwesen für Kunde X aktiv?". Der Assistent zeigt dir den aktuellen Status an und bietet an, ihn zu ändern.
  </Accordion>
</AccordionGroup>


# KI-Assistent
Source: https://docs.fynn.eu/guide/ai-assistant/introduction

Nutze den integrierten KI-Assistenten, um schnell Informationen zu finden, Daten abzufragen und durch die Plattform zu navigieren.

Der KI-Assistent in Fynn hilft dir, schnell Antworten auf Fragen zu deinen Kunden, Belegen, Zahlungen und Abonnements zu finden – direkt in der App, ohne manuelles Suchen und Filtern.

## Assistent öffnen

Klicke auf das **Chat-Symbol** unten rechts in der App oder nutze den Tastaturkürzel, um den Assistenten zu öffnen.

<Tip>
  Der Assistent erkennt automatisch, auf welcher Seite du dich befindest. Wenn du z.B. auf einer Kundendetailseite bist, bezieht er Fragen direkt auf diesen Kunden.
</Tip>

## Was kann der Assistent?

<CardGroup>
  <Card title="Daten abfragen" icon="magnifying-glass">
    Suche nach Kunden, Belegen, Abonnements, Zahlungen und mehr – in natürlicher Sprache.
  </Card>

  <Card title="Kundeneinstellungen" icon="sliders">
    Kundeneinstellungen abfragen und ändern – Mahnwesen, Abrechnung, Rechnungsfreigabe und Zahlungsziel.
  </Card>

  <Card title="Navigation" icon="compass">
    Öffne Seiten, Detailansichten oder Erstellungsdialoge per Sprachbefehl.
  </Card>

  <Card title="Berichte erstellen" icon="chart-bar">
    Lass dir Berichte generieren und per E-Mail zusenden.
  </Card>

  <Card title="Dokumentation" icon="book">
    Stelle Fragen zur Plattform und erhalte Antworten aus der Dokumentation.
  </Card>
</CardGroup>

***

## Beispiel-Anfragen

Hier findest du typische Fragen, die du dem Assistenten stellen kannst, gruppiert nach Anwendungsfall.

### Kunden finden

| Anfrage                                       | Was passiert                                      |
| --------------------------------------------- | ------------------------------------------------- |
| "Suche Kunde Müller"                          | Findet alle Kunden mit dem Namen Müller           |
| "Zeige mir die E-Mail von Kunde D26-00100043" | Ruft die Kundendetails anhand der Kundennummer ab |
| "Wie viele aktive Kunden haben wir?"          | Zählt aktive Kunden über das Gesamtergebnis       |

### Belege & Rechnungen

| Anfrage                                     | Was passiert                                    |
| ------------------------------------------- | ----------------------------------------------- |
| "Offene Rechnungen"                         | Listet unbezahlte Belege                        |
| "Überfällige Belege von Kunde Müller"       | Zeigt Mahnübersicht für einen bestimmten Kunden |
| "Zeige Belege aus dem letzten Monat"        | Filtert Belege nach Finalisierungsdatum         |
| "Was ist der Status von Beleg RE-2024-001?" | Ruft Belegdetails ab                            |

### Zahlungen & Transaktionen

| Anfrage                                        | Was passiert                                                                                                                                                                                                                                            |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Wann hat der Kunde zuletzt bezahlt?"          | **Letzte-Zahlung-Workflow**: Sucht die letzte Zahlungstransaktion des Kunden und zeigt Status, Zahlungsmethode, Gateway, Betrag, Datum und verknüpften Beleg. Bei fehlgeschlagenen Zahlungen wird zusätzlich die letzte erfolgreiche Zahlung angezeigt. |
| "Was ist die letzte Zahlung von D26-00100030?" | Wie oben – der Kunde wird zuerst per Kundennummer aufgelöst                                                                                                                                                                                             |
| "Wie wurde Beleg RE-2024-001 bezahlt?"         | **Belegzahlungen-Workflow**: Listet alle Transaktionen zu einem Beleg                                                                                                                                                                                   |
| "Welche Zahlungen gibt es zu diesem Beleg?"    | Zeigt Transaktionen zum aktuellen Beleg (auf der Belegdetailseite)                                                                                                                                                                                      |
| "Zeige fehlgeschlagene Zahlungen"              | Filtert Transaktionen nach Status                                                                                                                                                                                                                       |

<Info>
  **Transaktions-Karten** zeigen dir auf einen Blick: Zahlungsanbieter (z.B. Stripe, GoCardless), Status (Erfasst, Ausstehend, Fehlgeschlagen), Betrag, Datum und verknüpften Beleg. Du kannst auf eine Transaktion klicken, um direkt zum Beleg zu springen.
</Info>

<Tip>
  Mehr Details zu den Zahlungs-Workflows findest du unter [Workflows](/guide/ai-assistant/workflows).
</Tip>

### Kundeneinstellungen

| Anfrage                                                       | Was passiert                                                                      |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| "Ist das Mahnwesen für Kunde Müller aktiv?"                   | Ruft die Einstellungen ab und zeigt den Dunning-Status                            |
| "Welche Einstellungen hat Kunde D26-00100043?"                | Zeigt alle Einstellungen (Mahnwesen, Abrechnung, Rechnungsfreigabe, Zahlungsziel) |
| "Deaktiviere das Mahnwesen für Kunde Müller"                  | Zeigt eine Bestätigungskarte und deaktiviert nach Bestätigung                     |
| "Aktiviere die manuelle Rechnungsfreigabe für Kunden A und B" | Ändert die Einstellung für mehrere Kunden gleichzeitig                            |
| "Setze das Zahlungsziel für Kunde Müller auf 30 Tage"         | Ändert das Zahlungsziel nach Bestätigung                                          |

<Tip>
  Details zu allen unterstützten Einstellungsänderungen findest du unter [Kundeneinstellungen](/guide/ai-assistant/customer-settings).
</Tip>

### Abonnements

| Anfrage                                    | Was passiert                         |
| ------------------------------------------ | ------------------------------------ |
| "Aktive Abonnements von Kunde Müller"      | Filtert Abos nach Kunde und Status   |
| "Welche Testphasen laufen diese Woche ab?" | Nutzt den Filter `trialEndsBefore`   |
| "Abos die in 30 Tagen enden"               | Nutzt den Filter `contractEndBefore` |

### Navigation

| Anfrage                       | Was passiert                                                          |
| ----------------------------- | --------------------------------------------------------------------- |
| "Öffne Kunde Müller"          | Navigiert zur Kundendetailseite (bei Mehrdeutigkeit wird nachgefragt) |
| "Neuen Kunden anlegen"        | Öffnet den Erstellungsdialog                                          |
| "Gehe zu Einstellungen"       | Navigiert zur Einstellungsseite                                       |
| "Öffne Transaktionsübersicht" | Navigiert zu `/finance/transactions`                                  |

### Berichte

| Anfrage                                  | Was passiert                                                                                  |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| "Erstelle einen Umsatz-Bericht für 2025" | Schlägt den Bericht vor, erfasst Parameter automatisch und zeigt eine Bestätigungskarte       |
| "Ich brauche eine Offene-Posten-Liste"   | Generiert den OPOS-Bericht (keine Parameter nötig – direkte Bestätigung)                      |
| "Zahlungsbericht für Januar 2026"        | Erstellt einen Zahlungsbericht, fragt gezielt nach fehlenden Parametern (z.B. Zahlungsstatus) |
| "PRAP-Bericht bis Ende 2025"             | Erstellt den PRAP-Bericht mit Stichtag 31.12.2025                                             |
| "Exportiere die re:cap-Berichte"         | Generiert die re:cap-Berichte (keine Parameter nötig)                                         |

<Warning>
  Berichte werden erst nach deiner expliziten Bestätigung über den **Bestätigen-Button** generiert. Ein einfaches "Ja" im Chat reicht nicht aus.
</Warning>

<Tip>
  Details zum vollständigen Ablauf mit Parametererfassung, Validierung und Bestätigung findest du unter [Berichterstellung](/guide/ai-assistant/reports).
</Tip>

### Dokumentation & Hilfe

| Anfrage                              | Was passiert                                                         |
| ------------------------------------ | -------------------------------------------------------------------- |
| "Wie erstelle ich eine Rechnung?"    | Sucht in der Dokumentation und gibt eine Schritt-für-Schritt-Antwort |
| "Was bedeutet Mahnstufe?"            | Erklärt den Begriff aus der Dokumentation                            |
| "Wie funktioniert SEPA-Lastschrift?" | Liefert eine Erklärung zur Zahlungsmethode                           |

***

## Seitenkontext

Der Assistent erkennt, auf welcher Seite du dich befindest, und bezieht seine Antworten darauf:

| Seite                             | Verhalten                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Kundendetail**                  | Fragen beziehen sich automatisch auf diesen Kunden. "Offene Belege" → zeigt nur Belege dieses Kunden. |
| **Belegdetail**                   | "Wie wurde dieser Beleg bezahlt?" → zeigt Transaktionen zu genau diesem Beleg.                        |
| **Abo-Detail**                    | Fragen beziehen sich auf dieses Abonnement und den zugehörigen Kunden.                                |
| **Listen** (Kunden, Belege, Abos) | Fragen beziehen sich auf die jeweilige Entität allgemein.                                             |
| **Dashboard**                     | Kein spezieller Kontext – der Assistent fragt bei Bedarf nach.                                        |

<Tip>
  Du kannst den Seitenkontext jederzeit übersteuern. Auch auf einer Kundendetailseite kannst du fragen: "Zeige mir alle überfälligen Belege" – der Assistent erkennt, dass du eine allgemeine Abfrage meinst.
</Tip>

***

## Mehrdeutige Ergebnisse

Wenn der Assistent bei einer Suche mehrere passende Ergebnisse findet (z.B. mehrere Kunden mit dem Namen "Müller"), zeigt er dir **klickbare Auswahloptionen** an, anstatt einfach eines auszuwählen.

<Steps>
  <Step title="Frage stellen">
    Du fragst z.B. "Wann hat Kunde Müller zuletzt bezahlt?"
  </Step>

  <Step title="Auswahl angezeigt">
    Der Assistent findet 3 Kunden mit dem Namen Müller und zeigt dir Karten mit Name, Kundennummer und E-Mail.
  </Step>

  <Step title="Auswahl treffen">
    Du klickst auf den richtigen Kunden – der Assistent setzt den Workflow automatisch fort.
  </Step>
</Steps>

***

## Tipps für bessere Ergebnisse

<AccordionGroup>
  <Accordion title="Sei spezifisch">
    Je genauer deine Frage, desto besser das Ergebnis. "Offene Belege von Kunde D26-00100043" ist besser als "Offene Rechnungen".
  </Accordion>

  <Accordion title="Nutze den Seitenkontext">
    Auf einer Kundendetailseite reicht "Letzte Zahlung?" – der Assistent weiß, welcher Kunde gemeint ist.
  </Accordion>

  <Accordion title="Kundennummern verwenden">
    Bei häufigen Namen (z.B. "Müller") ist die Kundennummer eindeutiger und vermeidet Rückfragen.
  </Accordion>

  <Accordion title="Berichte für komplexe Auswertungen">
    Für Dinge wie "Umsatzentwicklung der Top-10-Kunden" ist ein Bericht besser geeignet als eine Chat-Antwort. Der Assistent schlägt das automatisch vor.
  </Accordion>
</AccordionGroup>


# Berichterstellung
Source: https://docs.fynn.eu/guide/ai-assistant/reports

So generierst du mit dem KI-Assistenten Berichte – inklusive automatischer Parametererfassung und Bestätigung.

Der KI-Assistent kann Berichte generieren und dir per E-Mail zusenden. Der gesamte Ablauf – vom Vorschlag über die Parametererfassung bis zur Bestätigung – läuft direkt im Chat ab.

***

## Verfügbare Berichte

| Bericht                              | Beschreibung                                                | Parameter                                        |
| ------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------ |
| **Umsatz-Bericht**                   | Monatliche Umsatzentwicklung nach Kunden                    | Jahr (z.B. 2025)                                 |
| **Umsatz-Bericht (periodengerecht)** | Umsätze nach Leistungszeitraum, Beleg und kundenbasiert     | Jahr (z.B. 2025)                                 |
| **Zahlungsbericht**                  | Übersicht aller Zahlungen inkl. Kunden und Belege           | Startdatum, Enddatum, Zahlungsstatus             |
| **Debitoren-Saldenliste**            | Aktuelles Saldo des Debitoren-Kontos                        | Keine                                            |
| **Offene Posten (OPOS)**             | Alle unbezahlten Rechnungen inkl. Fälligkeit und Mahnstatus | Keine                                            |
| **Belegbericht**                     | Übersicht aller Belege (filterbar nach Typ)                 | Belegart (optional), Nur finalisierte (optional) |
| **Accounted-MRR-Bericht**            | Entwicklung des monatlich wiederkehrenden Umsatzes          | Stichtag (optional)                              |
| **Rechnungsprognose**                | Zukünftige Rechnungen basierend auf bestehenden Abos        | Prognosejahr                                     |
| **PRAP-Bericht**                     | Periodengerechte Abgrenzung aller Umsätze auf Monatsbasis   | Stichtag (ISO-Datum)                             |
| **re:cap-Berichte**                  | Verträge und Rechnungen als CSV-Export für re:cap           | Keine                                            |

***

## Ablauf

Der Assistent führt dich in mehreren Schritten durch die Berichterstellung:

<Steps>
  <Step title="Bericht vorschlagen">
    Du stellst eine Frage oder bittest um einen Bericht. Der Assistent erkennt, welcher Bericht zu deiner Anfrage passt, und erklärt dir, was der Bericht enthält.

    **Beispiele:**

    * "Erstelle einen Umsatz-Bericht"
    * "Ich brauche eine Offene-Posten-Liste"
    * "Wie ist die Umsatzentwicklung unserer besten Kunden?"
  </Step>

  <Step title="Parameter erfassen">
    Wenn der Bericht Parameter benötigt (z.B. ein Jahr oder ein Datumsbereich), erfragt der Assistent diese gezielt. Die Parameter werden **automatisch aus deinen Antworten extrahiert** und **serverseitig validiert** – du musst kein bestimmtes Format einhalten.

    **Beispiel-Dialog:**

    > **Du:** Erstelle einen Umsatz-Bericht
    >
    > **Assistent:** Für welches Jahr soll der Umsatz-Bericht erstellt werden?
    >
    > **Du:** 2025
    >
    > **Assistent:** *(Parameter erkannt und validiert – weiter zur Bestätigung)*

    <Info>
      Berichte ohne Parameter (z.B. Debitoren-Saldenliste, OPOS) überspringen diesen Schritt und gehen direkt zur Bestätigung.
    </Info>
  </Step>

  <Step title="Bestätigung">
    Sobald alle Parameter vorliegen, zeigt der Assistent eine **Bestätigungskarte** im Chat an. Diese enthält:

    * Den Berichtsnamen
    * Die erfassten Parameter als Übersicht
    * Zwei Buttons: **Bestätigen** und **Abbrechen**

    Du kannst die Parameter prüfen, bevor du den Bericht tatsächlich auslöst.

    <Warning>
      Berichte werden **nur nach expliziter Bestätigung** über den Button generiert. Ein einfaches "Ja" im Chat löst keine Generierung aus.
    </Warning>
  </Step>

  <Step title="Bericht generieren">
    Nach dem Klick auf **Bestätigen** wird der Bericht im Hintergrund erstellt und dir per E-Mail zugestellt. Der Assistent bestätigt dies im Chat.
  </Step>
</Steps>

***

## Parametervalidierung

Die Parameter werden **automatisch** vom System geprüft – nicht vom KI-Modell. Das stellt sicher, dass:

* Alle Pflichtparameter vorhanden sind, bevor ein Bericht generiert wird
* Werte im richtigen Format vorliegen (z.B. 4-stelliges Jahr, gültiges ISO-Datum)
* Bei fehlenden oder ungültigen Parametern eine **gezielte Rückfrage** gestellt wird

| Parameter           | Validierung                                                 |
| ------------------- | ----------------------------------------------------------- |
| **Jahr**            | Muss 4-stellige Zahl sein (z.B. 2025), nicht in der Zukunft |
| **Datum**           | Muss gültiges ISO-8601-Format sein (YYYY-MM-DD)             |
| **Zahlungsstatus**  | Muss `paid`, `pending`, `failed` oder `all` sein            |
| **Prognosejahr**    | Muss 4-stellige Zahl sein, mindestens aktuelles Jahr        |
| **Stichtag (PRAP)** | Muss gültiges ISO-8601-Format sein (YYYY-MM-DD)             |

<Tip>
  Du kannst Parameter in natürlicher Sprache angeben. Sag einfach "letztes Jahr" oder "Januar 2026" – der Assistent rechnet das automatisch um.
</Tip>

***

## Bestätigungskarte

Die Bestätigungskarte erscheint direkt im Chat und verhindert versehentliche Berichterstellung:

<AccordionGroup>
  <Accordion title="Bestätigen" icon="circle-check">
    Klicke auf **Bestätigen**, um den Bericht zu generieren. Die Buttons werden nach dem Klick deaktiviert – ein doppeltes Absenden ist nicht möglich.

    Nach der Bestätigung zeigt der Assistent eine Ladeansicht mit dem Berichtsnamen. Der Bericht wird per E-Mail zugestellt.
  </Accordion>

  <Accordion title="Abbrechen" icon="circle-xmark">
    Klicke auf **Abbrechen**, um den Vorgang abzubrechen. Der Assistent bestätigt die Stornierung und du kannst eine neue Anfrage stellen oder Parameter ändern.
  </Accordion>

  <Accordion title="Zeitlimit" icon="clock">
    Die Bestätigung hat ein Zeitfenster von **5 Minuten**. Wenn du nicht innerhalb dieser Zeit reagierst, wird die Bestätigung ungültig und der Assistent bittet dich, den Vorgang erneut zu starten.
  </Accordion>
</AccordionGroup>

<Info>
  Während die Bestätigungskarte angezeigt wird, ist das Chat-Eingabefeld deaktiviert. Du musst zuerst bestätigen oder abbrechen, bevor du eine neue Nachricht senden kannst.
</Info>

***

## Beispiel-Szenarien

### Bericht ohne Parameter (OPOS)

> **Du:** Erstelle mir einen OPOS-Bericht
>
> **Assistent:** Ich kann dir einen OPOS-Bericht (Offene Posten) erstellen. Dieser enthält alle unbezahlten Rechnungen mit Fälligkeitsdaten und Mahnstatus.
>
> *(Bestätigungskarte mit "OPOS-Bericht (Offene Posten)" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der OPOS-Bericht wird erstellt und dir per E-Mail zugesendet.

### Bericht mit Parametern (Umsatz)

> **Du:** Wie ist die Umsatzentwicklung unserer besten Kunden?
>
> **Assistent:** Für eine detaillierte Auswertung kann ich dir einen Umsatz-Bericht generieren. Dieser zeigt die monatliche Umsatzentwicklung nach Kunden. Für welches Jahr soll der Bericht erstellt werden?
>
> **Du:** 2025
>
> *(Bestätigungskarte mit "Umsatz-Bericht", Parameter "Jahr: 2025" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der Umsatz-Bericht für 2025 wird erstellt und dir per E-Mail zugesendet.

### Bericht mit mehreren Parametern (Zahlungen)

> **Du:** Ich brauche einen Zahlungsbericht für Q1 2026
>
> **Assistent:** Für den Zahlungsbericht brauche ich noch den Zahlungsstatus. Soll der Bericht alle Zahlungen (paid, pending, failed) enthalten, oder nur einen bestimmten Status?
>
> **Du:** Alle
>
> *(Bestätigungskarte mit "Zahlungsbericht", Parameter "01.01.2026 – 31.03.2026, Status: all" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der Zahlungsbericht wird erstellt und dir per E-Mail zugesendet.

### PRAP-Bericht mit Stichtag

> **Du:** Erstelle einen PRAP-Bericht
>
> **Assistent:** Ich kann dir einen PRAP-Bericht erstellen. Dieser zeigt die periodengerechte Abgrenzung aller Umsätze auf Monatsbasis. Bis zu welchem Stichtag sollen die Belege berücksichtigt werden?
>
> **Du:** Bis Ende 2025
>
> *(Bestätigungskarte mit "PRAP-Bericht", Parameter "Stichtag: 2025-12-31" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der PRAP-Bericht wird erstellt und dir per E-Mail zugesendet.

### re:cap-Berichte (ohne Parameter)

> **Du:** Exportiere die re:cap-Berichte
>
> **Assistent:** Ich erstelle dir die re:cap-Berichte. Diese enthalten Verträge und Rechnungen als CSV-Export.
>
> *(Bestätigungskarte mit "re:cap-Berichte" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Die re:cap-Berichte werden erstellt und dir per E-Mail zugesendet.

### Ungültige Parameter

> **Du:** Erstelle einen Umsatz-Bericht für 999
>
> **Assistent:** Das Jahr muss eine 4-stellige Zahl sein (z.B. 2025) und darf nicht in der Zukunft liegen. Für welches Jahr soll der Bericht erstellt werden?
>
> **Du:** 2025
>
> *(Bestätigungskarte wird angezeigt)*

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Wo finde ich den generierten Bericht?">
    Berichte werden per E-Mail an deine hinterlegte Adresse gesendet. Zusätzlich findest du sie unter **Reportings → Generierte Berichte** in der App.
  </Accordion>

  <Accordion title="Kann ich einen laufenden Bericht abbrechen?">
    Nein – sobald du bestätigt hast, wird der Bericht im Hintergrund erstellt. Du kannst aber jederzeit einen neuen Bericht mit anderen Parametern anfordern.
  </Accordion>

  <Accordion title="Warum fragt der Assistent nach Parametern, obwohl ich sie schon genannt habe?">
    Der Assistent extrahiert Parameter automatisch aus dem gesamten Gesprächsverlauf. Wenn ein Parameter nicht erkannt wurde, war er möglicherweise mehrdeutig. Formuliere ihn etwas spezifischer (z.B. "Jahr 2025" statt nur "letztes Jahr").
  </Accordion>

  <Accordion title="Warum kann ich nicht einfach 'Ja' schreiben, um zu bestätigen?">
    Berichte erfordern eine explizite Bestätigung über den **Bestätigen-Button** in der Karte. Das verhindert Missverständnisse und versehentliche Berichtserstellung. Ein einfaches "Ja" im Chat wird als neue Nachricht interpretiert.
  </Accordion>
</AccordionGroup>


# Workflows
Source: https://docs.fynn.eu/guide/ai-assistant/workflows

So verarbeitet der KI-Assistent komplexe Anfragen Schritt für Schritt – am Beispiel von Zahlungen, Transaktionen und Belegen.

Der KI-Assistent nutzt für bestimmte Fragestellungen fest definierte **Workflows** – mehrstufige Abläufe, die im Code verankert sind und automatisch die richtigen Daten in der richtigen Reihenfolge abrufen. Du stellst eine Frage, und der Assistent liefert ein vollständiges Ergebnis.

***

## Letzte Zahlung eines Kunden

Wenn du fragst, wann ein Kunde zuletzt bezahlt hat, nutzt der Assistent den **Letzte-Zahlung-Workflow**. Dieser sucht direkt nach der letzten Zahlungstransaktion – nicht nach Belegen.

<Info>
  Der Workflow sucht immer zuerst die **Transaktion** (die tatsächliche Zahlung), nicht den Beleg. Die Beleginformationen werden automatisch aus der Transaktion abgeleitet.
</Info>

### Beispiel-Anfragen

| Anfrage                                        | Kontext                                                |
| ---------------------------------------------- | ------------------------------------------------------ |
| "Was ist die letzte Zahlung von D26-00100030?" | Von jeder Seite aus                                    |
| "Wann hat der Kunde zuletzt bezahlt?"          | Auf der Kundendetailseite                              |
| "Letzte Zahlung?"                              | Auf der Kundendetailseite (Seitenkontext wird genutzt) |
| "Wann hat Kunde Müller zuletzt bezahlt?"       | Von jeder Seite aus (Kunde wird per Name gesucht)      |

### Ablauf

<Steps>
  <Step title="Kunde ermitteln">
    Der Assistent ermittelt den Kunden. Auf einer **Kundendetailseite** wird der Seitenkontext verwendet – keine zusätzliche Suche nötig. Von anderen Seiten aus sucht er per Kundennummer oder Name. Bei mehreren Treffern zeigt er eine **Auswahlkarte** an.
  </Step>

  <Step title="Letzte Transaktion abrufen">
    Der Assistent ruft die **letzte Zahlungstransaktion** des Kunden ab. Das Ergebnis enthält: Status, Zahlungsmethode, Gateway (z.B. Stripe, SEPA), Betrag, Datum und den verknüpften Beleg.
  </Step>

  <Step title="Ergebnis anzeigen">
    Das Ergebnis wird als Transaktionskarte angezeigt – mit direkten Links zum Beleg und zur Transaktionsübersicht.
  </Step>
</Steps>

### Szenarien

<AccordionGroup>
  <Accordion title="Erfolgreiche Zahlung" icon="circle-check">
    Die letzte Transaktion hat den Status **Erfasst** (captured) oder **Gebucht** (booked).

    Der Assistent zeigt:

    * Zahlungsdatum und Betrag
    * Zahlungsmethode und Gateway (z.B. "SEPA-Lastschrift via GoCardless")
    * Verknüpfter Beleg (z.B. "RE-2025-0042")

    **Beispiel-Antwort:**

    > "Die letzte Zahlung von Kevin Szymura war am 03.02.2026 über 149,90 € per SEPA-Lastschrift (GoCardless). Der verknüpfte Beleg ist RE-2026-0015."
  </Accordion>

  <Accordion title="Fehlgeschlagene oder ausstehende Zahlung" icon="triangle-exclamation">
    Die letzte Transaktion hat einen **nicht-erfolgreichen Status** (z.B. `failed`, `pending`, `cancelled`).

    Der Assistent zeigt dann **zwei Informationen**:

    1. **Die letzte Transaktion** mit ihrem Status (z.B. "Fehlgeschlagen"), Datum, Betrag und verknüpftem Beleg
    2. **Die letzte erfolgreiche Zahlung** als Zusatzinfo – damit du weißt, wann die letzte *tatsächliche* Zahlung stattfand

    **Beispiel-Antwort:**

    > "Der letzte Zahlungsversuch von Kevin Szymura am 10.02.2026 über 149,90 € ist fehlgeschlagen (Beleg RE-2026-0018). Die letzte erfolgreiche Zahlung war am 03.01.2026 über 149,90 € per SEPA-Lastschrift."

    <Warning>
      Wenn es **keine einzige erfolgreiche Zahlung** gibt, meldet der Assistent das ebenfalls – z.B. "Es gibt keine erfolgreichen Zahlungen für diesen Kunden."
    </Warning>
  </Accordion>

  <Accordion title="Keine Transaktionen vorhanden" icon="circle-xmark">
    Der Kunde hat **keine Zahlungstransaktionen** (z.B. ein neuer Kunde ohne Belege).

    **Beispiel-Antwort:**

    > "Für Kevin Szymura wurden keine Zahlungstransaktionen gefunden."
  </Accordion>
</AccordionGroup>

***

## Belegzahlungen

Wenn du wissen möchtest, wie ein bestimmter Beleg bezahlt wurde, nutzt der Assistent den **Belegzahlungen-Workflow**.

### Beispiel-Anfragen

| Anfrage                                     | Kontext                  |
| ------------------------------------------- | ------------------------ |
| "Wie wurde dieser Beleg bezahlt?"           | Auf der Belegdetailseite |
| "Welche Zahlungen gibt es zu diesem Beleg?" | Auf der Belegdetailseite |
| "Wie wurde Beleg RE-2025-0042 bezahlt?"     | Von jeder Seite aus      |

### Ablauf

<Steps>
  <Step title="Beleg ermitteln">
    Auf einer **Belegdetailseite** wird der Seitenkontext verwendet. Von anderen Seiten aus sucht der Assistent den Beleg per Nummer. Bei mehreren Treffern zeigt er eine **Auswahlkarte** an.
  </Step>

  <Step title="Transaktionen abrufen">
    Der Assistent sucht alle Zahlungstransaktionen, die mit diesem Beleg verknüpft sind.
  </Step>

  <Step title="Ergebnis anzeigen">
    Alle Transaktionen werden als Liste angezeigt – jeweils mit Zahlungsmethode, Gateway, Datum, Betrag und Status.
  </Step>
</Steps>

### Szenarien

<AccordionGroup>
  <Accordion title="Beleg mit Zahlungen" icon="circle-check">
    **Beispiel-Antwort:**

    > "Beleg RE-2025-0042 wurde am 15.01.2025 über 299,00 € per Kreditkarte (Stripe) bezahlt."

    Bei mehreren Teilzahlungen werden alle aufgelistet.
  </Accordion>

  <Accordion title="Beleg ohne Transaktionen" icon="circle-xmark">
    Der Beleg hat keine verknüpften Zahlungstransaktionen (z.B. ein noch unbezahlter Beleg).

    **Beispiel-Antwort:**

    > "Zu Beleg RE-2025-0042 wurden keine Zahlungstransaktionen gefunden."
  </Accordion>
</AccordionGroup>

***

## Unterschied: Letzte Zahlung vs. Zahlungen eines Belegs

|                               | Letzte Zahlung                                               | Belegzahlungen                                              |
| ----------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| **Frage**                     | "Wann hat der Kunde zuletzt bezahlt?"                        | "Wie wurde dieser Beleg bezahlt?"                           |
| **Ausgangspunkt**             | Kunde                                                        | Beleg                                                       |
| **Sucht nach**                | Letzter Transaktion des Kunden                               | Allen Transaktionen eines Belegs                            |
| **Fehlgeschlagene Zahlungen** | Werden mit Hinweis auf letzte erfolgreiche Zahlung angezeigt | Alle Transaktionen werden angezeigt (inkl. fehlgeschlagene) |


# Dashboard
Source: https://docs.fynn.eu/guide/analytics/dashboard



Das Dashboard ist dein Startpunkt von Fynn und bietet einen umfassenden Überblick über wichtige Kennzahlen und Statistiken, die für das erfolgreiche Management deines Unternehmens unerlässlich sind.

## Kennzahlen

### Offene Forderungen

Das Dashboard zeigt eine detaillierte Übersicht über offene Forderungen nach Alterskategorien, von "Nicht fällig" bis "Über 90 Tage".
Diese Informationen helfen, den Überblick über die offenen Forderungen zu behalten und rechtzeitig Maßnahmen zu ergreifen, um Zahlungsausfälle zu vermeiden.

Bei Klick auf die jeweilige Kategorie gelangst du zur Liste der offenen Forderungen.

<Frame>
  <img alt="Offene Forderungen" />
</Frame>

<Tip>
  Die offenen Forderungen berücksichtigen alle Rechnungen, unabhängig vom Rechnungsdatum.
</Tip>

### Umsatz

Die Umsatzübersicht zeigt den **Netto**-Umsatz des aktuellen Monats im Vergleich zum Vormonat an, um Trends zu erkennen und den Geschäftserfolg zu messen.
Diese Kennzahl ist entscheidend, um das finanzielle Wachstum des Unternehmens zu verfolgen und Umsatzziele zu setzen.

<Frame>
  <img alt="Umsatz" />
</Frame>

<Tip>
  Der Umsatz wird auf Basis der Rechnungsstellung berechnet und nicht auf Basis der Zahlungseingänge.
  Hierbei werden alle Rechnungen berücksichtigt, dessen Rechnungsdatum im aktuellen Monat liegt und deren Status auf `bezahlt` oder `unbezahlt` gesetzt ist. Somit verfälschen stornierte Rechnungen nicht den Umsatz.
</Tip>

### Kunden

Die Anzahl der aktiven Kunden wird angezeigt und mit dem Vormonat verglichen.
Dies ermöglicht es, die Kundenbasis zu überwachen und das Kundenwachstum im Auge zu behalten.
Ein steigender Kundenbestand kann auf erfolgreiche Marketing- und Vertriebsaktivitäten hinweisen.

<Tip>
  Die Anzahl der aktiven Kunden entspricht allen Kunden, die nicht archiviert sind.
</Tip>

### Aktive Abonnements

Die Anzahl der aktiven Abonnements wird angezeigt und mit dem Vormonat verglichen.
Die Einsicht zur Entwicklung im zeitlichen Verlauf ermöglicht es, saisonale Schwankungen oder langfristige Trends zu erkennen und entsprechend zu reagieren.

<Tip>
  Die Anzahl der aktiven Abonnements entspricht allen Abonnements, die aktiviert und dessen Kündigungsdatum noch nicht erreicht ist.
</Tip>

### Akzeptierte Angebote

Die Anzahl der akzeptierten Angebote wird angezeigt und mit dem Vormonat verglichen. Zudem ist in der
Detailansicht ersichtlich, wie viele Angebote in dem aktuellen Monat erstellt wurden.

Diese Kennzahl ist entscheidend, um den Erfolg des Vertriebsteams zu messen und die Effektivität der Angebotsstrategie zu überprüfen.

<Tip>
  Die Anzahl der akzeptierten Angebote umfasst alle Angebote des aktuellen Monats, die den Status `angenommen` haben.
</Tip>

### MRR

Der MRR ist die Gesamtsumme der Einnahmen, die ein Unternehmen in einem bestimmten Monat aus wiederkehrenden Abonnementgebühren generiert. Dies ist eine wichtige Kennzahl, um die Stabilität und das Wachstum der Umsätze im Zeitverlauf zu verfolgen und zu prognostizieren.

<Frame>
  <img alt="MRR" />
</Frame>

<Tip>
  Der MRR wird auf Basis der aktiven Abonnement-Produkte berechnet. Hierbei werden Einmal-Zahlungen nicht berücksichtigt.
  Pausierte und gekündigte Abonnements werden ebenfalls nicht in die Berechnung des MRR einbezogen.
</Tip>

<Tip>
  Lebenslange Gutscheine werden von der Berechnung des MRR abgezogen, bei Gutscheinen die nur für eine bestimmte Anzahl von Abrechnungszyklen oder einmalig gültig sind, wird in der MRR Berechnung nicht berücksichtigt.
</Tip>

### Neuer MRR

Der Neuer MRR ist der zusätzliche monatliche Umsatz, der durch neue Kunden oder durch Erweiterungen von bestehenden Kunden generiert wird.

<Tip>
  Der Neuer MRR wird auf Basis der neu hinzugefügten Abonnements berechnet, die im aktuellen Monat erstellt wurden.
</Tip>

### MRR durch Erweiterung

Der MRR durch Erweiterung sind die zusätzlichen Einnahmen aus bestehenden Kunden durch Upgrades oder Erweiterungen ihrer Abonnements.
Diese Metrik verdeutlicht die Wichtigkeit der Kundenbindung und des Cross-Selling für das Umsatzwachstum.

<Tip>
  Der MRR durch Erweiterung wird auf Basis von hinzugefügter Produkte zum bestehenden Abonnement berechnet.
</Tip>

### Churn MRR

Der Churn MRR ist der monatliche Umsatzverlust durch gekündigte Abonnements.

<Tip>
  Der Churn MRR wird auf Basis der gekündigten Abonnements berechnet, dessen Kündigungsdatum (Beendigungsdatum) im aktuellen Monat liegt.
</Tip>


# Reporting
Source: https://docs.fynn.eu/guide/analytics/reporting



Fynn stellt ein umfangreiches Set an Reporting-Berichten bereit und ermöglicht es, wichtige Kennzahlen einzusehen,
um fundierte Entscheidungen für das Wachstum Ihres Business zu treffen.

Die Berichte sind nach Anfrage über den Menüpunkt `Reporting` erreichbar.

## Berichte

Die verfügbaren Berichte sind als CSV Datei exportierbar und können somit einfach innerhalb Ihres Unternehmens geteilt werden
oder in anderen Tools weiterverarbeitet werden.

### re:cap-Berichte

Die re:cap-Berichte bieten eine umfassende Übersicht über Verträge und Belege, die zum Upload für das Finanzierungs- und Liquditätsmanagement in re:cap verwendet werden können. Der Export enthält zwei CSV-Dateien in einer ZIP-Datei:

* **Verträge (Contracts)**: Enthält alle Abonnements mit Details wie Kundeninformationen, Vertragsstatus, Abrechnungsperioden und nächstem Abrechnungsdatum
* **Belege (Invoices)**: Enthält alle Belege mit Details wie Nummer, Kunde, Leistungszeitraum, Rechnungsdatum, Fälligkeitsdatum und Status

Beide Dateien werden als ZIP-Archiv bereitgestellt und können direkt heruntergeladen werden. Der Export wird im Hintergrund vorbereitet und du erhältst eine E-Mail, sobald der Download bereit ist.

## API

Alle wichtigen Kennzahlen des [Dashboards](/guide/analytics/dashboard) sind auch über die API abrufbar und können somit in andere Tools integriert werden.

Verwende hierfür den [Analytics](/api-reference/analytics/get-series-data) Endpunkt oder alternativ
den [Subscription Revenue](/api-reference/analytics/get-series-data-for-subscription) für MRR, Churn, etc.

```bash theme={null}
GET /analytics/series/{type}
GET /analytics/subscription-revenue
```

## Tableau / PowerBI

Für eine tiefergehende Analyse können umfangreichere Daten in Tools wie Tableau oder PowerBI integriert werden.
Hier werden umfangreichere Daten in Echtzeit bereitgestellt und sind somit flexibel und individuell anpassbar.

Spreche uns hierfür gerne an, um die Integration zu besprechen.


# Add-Ons
Source: https://docs.fynn.eu/guide/catalogue/addons

Erstelle und verwalte Add-Ons.

In Fynn können Produkte sowohl als Hauptprodukte als auch als Add-Ons verwendet werden,
wodurch eine effiziente Produktverwaltung und flexible Angebote ermöglicht werden.

## Vorteile

### Effiziente Produktverwaltung

Durch die Verwendung von Add-Ons in Fynn kann die Produktliste effizienter verwaltet werden. Es entstehen keine Dopplungen, da Produkte sowohl als Hauptprodukte als auch als Add-Ons definiert werden können.
Hierdurch wird die Übersichtlichkeit der Produktliste verbessert und die Verwaltung der Produkte vereinfacht.

### Flexibilität bei der Angebotserstellung

Mit Add-Ons kannst Du flexiblere Angebote für Deine Kunden erstellen. Du kannst verschiedene Kombinationen von Hauptprodukten und Add-Ons anbieten, um den unterschiedlichen Anforderungen und Budgets Deiner Kunden gerecht zu werden.

## Add-On erstellen

Um ein Produkt als Add-On zu definieren, hast du mehrere Möglichkeiten:

* **Abonnements**: Bei der Abonnement-Anlage kannst Du ein Produkt als Add-On definieren, indem Du es als "Unterprodukt" hinzufügst. Hiermit werden Laufzeiten und Kündigungsfristen vererbt.
  <Frame>
    <img alt="Abonnement Add-On" />
  </Frame>
  <Tip>Weitere Informationen findest Du unter [Abonnements verwalten](/guide/subscriptions/introduction).</Tip>
* **Pläne**: Bei der Verwaltung deiner Pläne kannst Du ein Produkt als Add-On definieren, indem du dieses im Bereich "Add-On" hinzufügst. Anschließend kannst du einen Preis für das Add-On festlegen oder einen bestehenden Preis verwenden.
  <Frame>
    <img alt="Plan Add-On" />
  </Frame>
  <Warning>Um Pläne für deine Organisation freizuschalten, nehme bitte [Kontakt mit uns auf](mailto:hi@fynn.eu).</Warning>
  Um ein Produkt zu erstellen, siehe dir [Produkte verwalten](/guide/catalogue/products) an.


# Aggregationstypen
Source: https://docs.fynn.eu/guide/catalogue/measurements/aggregation-types/overview

Wie Nutzungsdaten zusammengefasst werden - Summe, Anzahl, Maximum und mehr.

Der Aggregationstyp bestimmt, wie die eingehenden Events zu einem Abrechnungswert zusammengefasst werden.

## Übersicht

| Typ              | Braucht Feld? | Beschreibung                      |
| ---------------- | ------------- | --------------------------------- |
| **Anzahl**       | Nein          | Zählt die Anzahl der Events       |
| **Summe**        | Ja            | Addiert die Werte eines Feldes    |
| **Maximum**      | Ja            | Nimmt den höchsten Wert           |
| **Minimum**      | Ja            | Nimmt den niedrigsten Wert        |
| **Durchschnitt** | Ja            | Berechnet den Mittelwert          |
| **Eindeutig**    | Ja            | Zählt einzigartige Werte          |
| **Letzter Wert** | Ja            | Nimmt den zuletzt gemeldeten Wert |

***

## Anzahl (Count)

Zählt, wie oft ein Event aufgetreten ist. Kein Feld nötig.

**Beispiel:** API-Aufrufe zählen

| Event        | Aggregation   |
| ------------ | ------------- |
| `api_call`   | +1            |
| `api_call`   | +1            |
| `api_call`   | +1            |
| **Ergebnis** | **3 Aufrufe** |

**Wann nutzen:**

* API-Aufrufe
* Logins
* Transaktionen
* Nachrichten gesendet

***

## Summe (Sum)

Addiert die Werte eines bestimmten Feldes.

**Beispiel:** Token-Verbrauch summieren (Feld: `tokens`)

| Event        | tokens | Aggregation    |
| ------------ | ------ | -------------- |
| `ai_request` | 150    | +150           |
| `ai_request` | 300    | +300           |
| `ai_request` | 50     | +50            |
| **Ergebnis** |        | **500 Tokens** |

**Wann nutzen:**

* Token-/Credit-Verbrauch
* Datenvolumen (GB)
* Transaktionsbeträge
* E-Mails versendet

***

## Maximum (Max)

Nimmt den höchsten Wert im Abrechnungszeitraum.

**Beispiel:** Maximale gleichzeitige Nutzer (Feld: `active_users`)

| Event        | active\_users | Aggregation   |
| ------------ | ------------- | ------------- |
| `user_count` | 10            | max = 10      |
| `user_count` | 25            | max = 25      |
| `user_count` | 18            | max = 25      |
| **Ergebnis** |               | **25 Nutzer** |

**Wann nutzen:**

* Gleichzeitige Nutzer (Seats)
* Peak-Speicherverbrauch
* Maximale Bandbreite
* Höchste CPU-Auslastung

***

## Minimum (Min)

Nimmt den niedrigsten Wert im Abrechnungszeitraum.

**Beispiel:** Minimaler Kontostand (Feld: `balance`)

| Event           | balance | Aggregation |
| --------------- | ------- | ----------- |
| `balance_check` | 1000    | min = 1000  |
| `balance_check` | 500     | min = 500   |
| `balance_check` | 750     | min = 500   |
| **Ergebnis**    |         | **500**     |

**Wann nutzen:**

* Mindestguthaben
* Niedrigste Verfügbarkeit
* Minimale Ressourcennutzung

***

## Durchschnitt (Average)

Berechnet den Mittelwert aller gemeldeten Werte.

**Beispiel:** Durchschnittliche Response Time (Feld: `response_ms`)

| Event        | response\_ms | Aggregation |
| ------------ | ------------ | ----------- |
| `api_call`   | 100          |             |
| `api_call`   | 150          |             |
| `api_call`   | 200          |             |
| **Ergebnis** |              | **150 ms**  |

**Wann nutzen:**

* Durchschnittliche Verarbeitungszeit
* Mittlere Dateigröße
* Durchschnittlicher Verbrauch pro Request

***

## Eindeutig (Unique Count)

Zählt, wie viele unterschiedliche Werte ein Feld hatte.

**Beispiel:** Aktive Nutzer im Monat (Feld: `user_id`)

| Event        | user\_id | Aggregation                   |
| ------------ | -------- | ----------------------------- |
| `login`      | user-A   | 1 eindeutig                   |
| `login`      | user-B   | 2 eindeutig                   |
| `login`      | user-A   | 2 eindeutig (bereits gezählt) |
| `login`      | user-C   | 3 eindeutig                   |
| **Ergebnis** |          | **3 aktive Nutzer**           |

**Wann nutzen:**

* Monthly Active Users (MAU)
* Eindeutige Kunden
* Verschiedene verwendete Features
* Anzahl verschiedener Produkte

***

## Letzter Wert (Latest)

Nimmt den zuletzt gemeldeten Wert. Setzt sich nicht zurück nach Abrechnung.

**Beispiel:** Aktueller Speicherverbrauch (Feld: `storage_gb`)

| Event           | storage\_gb | Aggregation  |
| --------------- | ----------- | ------------ |
| `storage_check` | 50          | letzter = 50 |
| `storage_check` | 55          | letzter = 55 |
| `storage_check` | 52          | letzter = 52 |
| **Ergebnis**    |             | **52 GB**    |

**Wann nutzen:**

* Aktueller Speicherverbrauch
* Aktuelle Seat-Anzahl
* Lizenzstand
* Persistente Werte, die nicht summiert werden

<Note>
  **Wichtig:** Bei "Letzter Wert" wird der Wert **nicht** nach jeder Abrechnung auf 0 zurückgesetzt. Der letzte gemeldete Wert bleibt bestehen.
</Note>

***

## Vergleich: Wann welchen Typ?

| Use Case             | Aggregation  | Feld           |
| -------------------- | ------------ | -------------- |
| API-Calls zählen     | Anzahl       | -              |
| Token summieren      | Summe        | `tokens`       |
| Speicher (aktuell)   | Letzter Wert | `storage_gb`   |
| Speicher (Peak)      | Maximum      | `storage_gb`   |
| Aktive User (unique) | Eindeutig    | `user_id`      |
| Seats (Peak)         | Maximum      | `active_seats` |
| Response Time (Ø)    | Durchschnitt | `response_ms`  |


# Nutzungsmetriken
Source: https://docs.fynn.eu/guide/catalogue/measurements/billable-metrics

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 alt="Nutzungsbasierte Abrechnung am Produkt konfigurieren" />
    </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 alt="Nutzungsmetriken im Abonnement" />
</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 alt="Metrik Details" />
</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>
  <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>


# Nutzungsbasierte Abrechnung
Source: https://docs.fynn.eu/guide/catalogue/measurements/introduction

Rechne nach tatsächlichem Verbrauch ab - fair und transparent.

Mit nutzungsbasierter Abrechnung zahlst du nur, was du wirklich nutzt. Ideal für APIs, SaaS-Produkte, AI-Services oder Cloud-Dienste.

## Wie funktioniert's?

<Steps>
  <Step title="Nutzungsmetrik definieren">
    Du legst fest, was gemessen wird: Welches Ereignis? Wie aggregieren?

    Beispiel: "Zähle alle `ai_request` Ereignisse und summiere das Feld `tokens_used`"
  </Step>

  <Step title="Nutzungsereignisse senden">
    Deine Anwendung sendet Nutzungsereignisse an Fynn - per API oder CSV-Import.

    ```json theme={null}
    {
      "eventName": "ai_request",
      "properties": { "tokens_used": 350, "model": "gpt-4" }
    }
    ```
  </Step>

  <Step title="Automatische Abrechnung">
    Am Ende des Abrechnungszeitraums erstellt Fynn automatisch eine Rechnung basierend auf der tatsächlichen Nutzung.
  </Step>
</Steps>

***

## Beispiele

<CardGroup>
  <Card title="AI / LLM" icon="microchip-ai">
    Token-Verbrauch pro Modell, API-Aufrufe, Bildgenerierungen
  </Card>

  <Card title="API Services" icon="code">
    API-Calls, Datentransfer, Webhook-Zustellungen
  </Card>

  <Card title="Cloud / Hosting" icon="cloud">
    Speicherplatz, Bandbreite, Compute-Zeit
  </Card>

  <Card title="Kommunikation" icon="envelope">
    E-Mails, SMS, Push-Notifications
  </Card>
</CardGroup>

***

## Die Bausteine

| Baustein             | Beschreibung                                                    |
| -------------------- | --------------------------------------------------------------- |
| **Nutzungsmetrik**   | Definiert, was und wie gemessen wird                            |
| **Nutzungsereignis** | Einzelnes Ereignis aus deiner App                               |
| **Aggregation**      | Wie Ereignisse zusammengefasst werden (Summe, Anzahl, Max, ...) |
| **Filter**           | Welche Ereignisse berücksichtigt werden                         |
| **Gruppierung**      | Aufschlüsselung nach Dimensionen (z.B. pro Modell)              |

***

## Dokumentation

<CardGroup>
  <Card title="Nutzungsmetriken" icon="chart-line" href="/guide/catalogue/measurements/billable-metrics">
    Erstelle und konfiguriere Nutzungsmetriken mit Filtern und Gruppierung.
  </Card>

  <Card title="Nutzungsereignisse senden" icon="paper-plane" href="/guide/catalogue/usage-events-import">
    Sende Nutzungsereignisse per API oder importiere sie per CSV.
  </Card>

  <Card title="Aggregationstypen" icon="calculator" href="/guide/catalogue/measurements/aggregation-types/overview">
    Verstehe Summe, Anzahl, Maximum und andere Aggregationstypen.
  </Card>

  <Card title="API Referenz" icon="code" href="/api-reference/guides/collect-usage-data">
    Technische Details zur Nutzungsereignisse-API.
  </Card>
</CardGroup>


# Nutzungsbasierte Abrechnung verstehen
Source: https://docs.fynn.eu/guide/catalogue/measurements/usage-based-billing

Erfahre, wie die nutzungsbasierte Abrechnung funktioniert und wie du die Nutzungsdaten interpretierst

<Frame>
  <img alt="Nutzungsbasierte Abrechnung" />
</Frame>

Die nutzungsbasierte Abrechnung ermöglicht es dir, Kunden basierend auf ihrer tatsächlichen Nutzung abzurechnen. Anstatt eines festen monatlichen Preises werden Kunden nur für das berechnet, was sie tatsächlich verwenden.

## Wie funktioniert die nutzungsbasierte Abrechnung?

### Grundprinzip

1. **Nutzungsereignisse werden erfasst**: Deine Anwendung sendet Nutzungsereignisse (z.B. API-Aufrufe, gesendete E-Mails, Speicherplatz) an Fynn
2. **Ereignisse werden aggregiert**: Fynn sammelt alle Ereignisse und berechnet die Gesamtnutzung basierend auf dem Aggregationstyp
3. **Abrechnung erfolgt nachträglich**: Am Ende des Abrechnungszeitraums wird die tatsächliche Nutzung abgerechnet

### Abrechnungsmodus: Nachträglich (Arrears)

Im Gegensatz zu festen Abonnements, die im Voraus (Advance) abgerechnet werden, erfolgt die nutzungsbasierte Abrechnung **nachträglich (Arrears)**:

* **Feste Abonnements**: Du zahlst am 1. Januar für den gesamten Januar im Voraus
* **Nutzungsbasierte Abrechnung**: Du zahlst am 1. Februar für die Nutzung im Januar

## Was zeigen die Metriken?

Die angezeigten Metriken zeigen die **aggregierten Nutzungswerte für noch nicht abgerechnete Ereignisse**. Das bedeutet:

* ✅ **Enthalten**: Alle Nutzungsereignisse, die noch nicht auf einer Rechnung stehen
* ❌ **Nicht enthalten**: Bereits abgerechnete Ereignisse (die bereits auf einer Rechnung erscheinen)

### Beispiel

Angenommen, du hast ein Produkt "API-Aufrufe" mit nutzungsbasierter Abrechnung:

```
01.01.2026: 100 API-Aufrufe → noch nicht abgerechnet
15.01.2026: 200 API-Aufrufe → noch nicht abgerechnet
01.02.2026: Rechnung wird erstellt für Januar → 300 API-Aufrufe werden abgerechnet
02.02.2026: 50 API-Aufrufe → noch nicht abgerechnet
```

**Angezeigte Metrik am 02.02.2026:**

* **Menge**: 50 API-Aufrufe (nur die noch nicht abgerechneten)
* **Zeitraum**: 01.02.2026 bis 02.02.2026

## Den Zeitraum verstehen

Jede Metrik zeigt einen **Zeitraum** an, z.B. "01.01.2026 bis 01.02.2026". Dieser Zeitraum hat eine klare Bedeutung:

### Startdatum

Das **Startdatum** ist das Datum, ab dem noch nicht abgerechnete Ereignisse erfasst werden:

* **Wenn bereits abgerechnet wurde**: Das Datum der letzten Abrechnung (z.B. 01.01.2026)
* **Wenn noch nie abgerechnet wurde**: Das Startdatum des Abonnements

**Wichtig**: Wenn eine Schwellenwert-Abrechnung (Threshold Billing) stattfindet, ändert sich das Startdatum entsprechend, da dann ein neuer Abrechnungszeitraum beginnt.

### Enddatum

Das **Enddatum** ist immer das aktuelle Datum und die aktuelle Uhrzeit. Es zeigt, bis wann die Nutzung erfasst wurde.

### Beispiel: Zeitraum-Interpretation

```
Zeitraum: 01.01.2026 bis 01.02.2026
```

**Bedeutung:**

* **01.01.2026**: Letztes Abrechnungsdatum (oder Start des Abonnements)
* **01.02.2026**: Heutiges Datum

**Was wird angezeigt:**

* Alle Nutzungsereignisse vom 01.01.2026 00:00:00 bis zum 01.02.2026 (aktueller Zeitpunkt)
* Die aggregierte Gesamtnutzung in diesem Zeitraum
* **Nur** noch nicht abgerechnete Ereignisse

## Wann wird abgerechnet?

### Reguläre Abrechnung (Period Billing)

Die nutzungsbasierte Abrechnung erfolgt **am Ende des Abrechnungszeitraums**:

* **Monatliche Abrechnung**: Am 1. des Monats wird die Nutzung des Vormonats abgerechnet
* **Quartalsweise Abrechnung**: Am 1. des Quartals wird die Nutzung des Vorquartals abgerechnet

**Beispiel:**

```
Abrechnungsintervall: Monatlich
Abrechnungsdatum: 01.02.2026
Abrechnungszeitraum: 01.01.2026 - 31.01.2026
```

### Schwellenwert-Abrechnung (Threshold Billing)

Zusätzlich zur regulären Abrechnung kannst du **Schwellenwerte** definieren, die eine Abrechnung auslösen, wenn ein bestimmter Nutzungswert oder Betrag erreicht wird:

* **Beispiel**: Wenn 1000 API-Aufrufe erreicht werden, wird sofort eine Rechnung erstellt
* **Vorteil**: Du erhältst früher Zahlungen und reduzierst das Ausfallrisiko

**Wichtig**: Nach einer Schwellenwert-Abrechnung beginnt ein neuer Abrechnungszeitraum. Das Startdatum der Metriken wird entsprechend aktualisiert.

## Wie werden die Werte aggregiert?

Die Art der Aggregation hängt vom **Aggregationstyp** deiner Messung ab:

| Aggregationstyp       | Beschreibung              | Beispiel                         |
| --------------------- | ------------------------- | -------------------------------- |
| **Summe**             | Alle Werte werden addiert | 100 + 200 + 50 = 350 API-Aufrufe |
| **Anzahl**            | Anzahl der Ereignisse     | 3 Ereignisse                     |
| **Durchschnitt**      | Durchschnittswert         | (100 + 200 + 50) / 3 = 116,67    |
| **Maximum**           | Höchster Wert             | max(100, 200, 50) = 200          |
| **Zuletzt**           | Letzter gemeldeter Wert   | 50 (letzter Wert)                |
| **Eindeutige Anzahl** | Anzahl eindeutiger Werte  | 3 eindeutige Kunden              |

## Praktisches Beispiel

### Szenario: E-Mail-Versand-Service

Du bietest einen E-Mail-Versand-Service an, der pro gesendeter E-Mail abgerechnet wird.

**Setup:**

* Produkt: "E-Mail-Versand"
* Messung: "Gesendete E-Mails" (Aggregation: Summe)
* Preis: 0,01 € pro E-Mail

**Ablauf:**

1. **01.01.2026**: Abonnement startet
   * Angezeigte Nutzung: 0 E-Mails
   * Zeitraum: 01.01.2026 bis 01.01.2026

2. **15.01.2026**: Kunde sendet 1.000 E-Mails
   * Angezeigte Nutzung: 1.000 E-Mails
   * Zeitraum: 01.01.2026 bis 15.01.2026
   * **Noch nicht abgerechnet**

3. **25.01.2026**: Kunde sendet weitere 500 E-Mails
   * Angezeigte Nutzung: 1.500 E-Mails
   * Zeitraum: 01.01.2026 bis 25.01.2026
   * **Noch nicht abgerechnet**

4. **01.02.2026**: Reguläre Abrechnung
   * Rechnung wird erstellt für 1.500 E-Mails × 0,01 € = 15,00 €
   * Zeitraum der Rechnung: 01.01.2026 - 31.01.2026

5. **02.02.2026**: Kunde sendet 200 weitere E-Mails
   * Angezeigte Nutzung: 200 E-Mails
   * Zeitraum: 01.02.2026 bis 02.02.2026
   * **Neuer Abrechnungszeitraum beginnt**

## Häufige Fragen

### Warum zeigt die Metrik einen anderen Wert als erwartet?

**Mögliche Gründe:**

1. **Ereignisse wurden bereits abgerechnet**: Die Metrik zeigt nur noch nicht abgerechnete Ereignisse
2. **Falscher Zeitraum**: Prüfe, ob der Zeitraum korrekt ist (Startdatum = letztes Abrechnungsdatum)
3. **Ereignisse wurden noch nicht erfasst**: Prüfe, ob die Nutzungsereignisse korrekt an Fynn gesendet wurden

### Warum ändert sich das Startdatum?

Das Startdatum ändert sich, wenn:

* Eine reguläre Abrechnung stattgefunden hat
* Eine Schwellenwert-Abrechnung ausgelöst wurde
* Das Abonnement neu gestartet wurde

### Was passiert, wenn Ereignisse verspätet eintreffen?

Fynn berücksichtigt auch verspätet eintreffende Ereignisse korrekt:

* Ereignisse werden basierend auf ihrem **Zeitstempel** (timestamp) dem richtigen Abrechnungszeitraum zugeordnet
* Auch wenn ein Ereignis erst später erfasst wird, wird es dem korrekten Zeitraum zugeordnet

### Wie kann ich die Details einer Metrik einsehen?

Du kannst die Details einer Metrik einsehen, um:

* Alle einzelnen Nutzungsereignisse zu sehen
* Den Zeitraum im Detail zu verstehen
* Die Aggregation nachzuvollziehen

Nutze hierfür die Detailansicht der Metrik in der Abonnementübersicht.

## Zusammenfassung

* ✅ **Metriken zeigen**: Aggregierte Nutzungswerte für noch nicht abgerechnete Ereignisse
* ✅ **Startdatum**: Letztes Abrechnungsdatum (oder Abonnementstart)
* ✅ **Enddatum**: Aktuelles Datum und Uhrzeit
* ✅ **Abrechnung**: Nachträglich am Ende des Abrechnungszeitraums
* ✅ **Schwellenwerte**: Können eine frühere Abrechnung auslösen

Die nutzungsbasierte Abrechnung gibt dir vollständige Transparenz über die Nutzung deiner Kunden und ermöglicht eine faire, verbrauchsabhängige Abrechnung.


# Preis-Assistent
Source: https://docs.fynn.eu/guide/catalogue/price-assistant

Erstelle und bearbeite Preispläne in natürlicher Sprache mit dem KI-Preis-Assistenten.

Der KI-Preis-Assistent ermöglicht es, Preise in natürlicher Sprache zu beschreiben und automatisch strukturierte Preispläne generieren zu lassen. Statt Preistypen, Intervalle und Staffeln manuell zu konfigurieren, beschreibst du einfach, wie dein Produkt abgerechnet werden soll.

<Info>
  Der Preis-Assistent ist über die Preiskonfiguration im Produktkatalog verfügbar. Du findest den Button **Mit KI erstellen** beim Anlegen neuer Preise.
</Info>

***

## Einzelnen Preis erstellen

Erstelle einen einzelnen Preisplan per Beschreibung.

<Steps>
  <Step title="Preis-Assistent öffnen">
    Klicke beim Erstellen eines neuen Preises auf **Mit KI erstellen**.
  </Step>

  <Step title="Preis beschreiben">
    Beschreibe den Preis in natürlicher Sprache, z.B.:

    * "99 € monatlich"
    * "10 € pro Nutzer pro Monat"
    * "Die ersten 10 Einheiten kosten 5 €, danach 3 € pro Stück"
    * "2 % vom gemeldeten Umsatz"
  </Step>

  <Step title="Vorschau prüfen">
    Der Assistent zeigt den erkannten Preisplan mit einer Abrechnungsvorschau an. Du siehst Preistyp, Intervall, Beträge und ggf. Staffeln auf einen Blick.
  </Step>

  <Step title="Übernehmen oder anpassen">
    Klicke auf **Übernehmen**, um den Preis zu erstellen. Alternativ kannst du mit **Neu generieren** eine neue Interpretation anfordern.
  </Step>
</Steps>

### Beispiele

| Beschreibung                                                       | Erkannter Preistyp                |
| ------------------------------------------------------------------ | --------------------------------- |
| "49 € pro Monat"                                                   | Pauschale (Flat Fee), monatlich   |
| "299 € einmalige Setup-Gebühr"                                     | Pauschale, einmalig               |
| "9 € pro Nutzer pro Monat"                                         | Pro Einheit (Per Unit), monatlich |
| "1-10 Stück: 5 € je Stück, 11+: 3 € je Stück"                      | Staffel (Tiered)                  |
| "Bis 100: 10 €/Stück, ab 101: 7 €/Stück (alle zum gleichen Preis)" | Volumen (Volume)                  |
| "1-10 Nutzer: 49 €, 11-50 Nutzer: 99 €"                            | Stufen (Stair Step)               |
| "2 % von jeder Transaktion"                                        | Prozent (Percentage)              |

***

## Gesamtes Produkt mit mehreren Preisen beschreiben

Beschreibe ein komplettes Produkt mit allen Preiskomponenten in einem Schritt. Der Assistent erkennt automatisch, welche Teile getrennte Preispläne erfordern.

<Steps>
  <Step title="Produktbeschreibung eingeben">
    Beschreibe alle Preiskomponenten deines Produkts, z.B.:

    > "Unser CRM kostet 49 € Grundgebühr monatlich plus 9 € pro Nutzer. Einmalige Setup-Gebühr 299 €."
  </Step>

  <Step title="Generierte Preise prüfen">
    Der Assistent zeigt alle erkannten Preispläne als Karten an – jeweils mit Preistyp, Intervall und Abrechnungsvorschau. In diesem Beispiel:

    * Setup-Gebühr: 299 € einmalig (Pauschale)
    * Grundgebühr: 49 € monatlich (Pauschale)
    * Nutzergebühr: 9 € pro Nutzer/Monat (Pro Einheit)
  </Step>

  <Step title="Einzelne Preise entfernen oder übernehmen">
    Entferne nicht benötigte Preise per Klick auf das Papierkorb-Symbol. Klicke dann auf **Preise übernehmen**, um alle verbleibenden Preise auf einmal zu erstellen.
  </Step>
</Steps>

<Tip>
  Der Assistent trennt automatisch zwischen einmaligen und wiederkehrenden Kosten sowie zwischen verschiedenen Abrechnungseinheiten (z.B. Grundgebühr vs. pro Nutzer).
</Tip>

***

## Unterstützte Preistypen

Der Assistent erkennt alle in Fynn verfügbaren Preistypen:

| Preistyp                   | Wann erkannt                                         |
| -------------------------- | ---------------------------------------------------- |
| **Pauschale** (Flat Fee)   | Fester Betrag ohne Mengenbezug – "99 € pro Monat"    |
| **Pro Einheit** (Per Unit) | Betrag pro Stück/Nutzer/Einheit – "10 € pro Nutzer"  |
| **Staffel** (Tiered)       | Mehrere Mengenbereiche mit unterschiedlichen Preisen |
| **Volumen** (Volume)       | Gesamtmenge bestimmt den Einheitspreis für alle      |
| **Stufen** (Stair Step)    | Fester Betrag pro Mengenstufe                        |
| **Prozent** (Percentage)   | Prozentualer Anteil eines gemeldeten Werts           |

Eine detaillierte Erklärung der Berechnungslogik findest du unter [Preisberechnung](/guide/catalogue/prices/calculation).

***

## Tipps für bessere Ergebnisse

<AccordionGroup>
  <Accordion title="Intervall angeben">
    Nenne das Abrechnungsintervall explizit: "monatlich", "jährlich", "einmalig" oder "vierteljährlich".
  </Accordion>

  <Accordion title="Einheit benennen">
    Bei mengenbasierten Preisen hilft es, die Einheit zu nennen: "pro Nutzer", "pro API-Aufruf", "pro GB".
  </Accordion>

  <Accordion title="Staffeln klar beschreiben">
    Für Staffelpreise nenne die Grenzen und Preise: "1-10 Stück: 5 €, 11-50 Stück: 3 €, ab 51: 2 €".
  </Accordion>

  <Accordion title="Inklusiv-Einheiten nennen">
    Wenn Einheiten inklusive sein sollen: "Die ersten 100 API-Aufrufe sind kostenlos, danach 0,02 € pro Aufruf."
  </Accordion>
</AccordionGroup>


# Preisberechnung
Source: https://docs.fynn.eu/guide/catalogue/prices/calculation

So berechnet Fynn die verschiedenen Preistypen im Detail

Fynn unterstützt sechs verschiedene Preistypen, die jeweils einer festen Berechnungslogik folgen. Dieser Guide erklärt, wie die Berechnung für jeden Typ funktioniert und wie Zusatzfunktionen wie freie Einheiten, Mindestabnahme und Basisgebühren einbezogen werden.

## Berechnungsreihenfolge

Bevor die eigentliche Preisberechnung startet, werden zwei optionale Anpassungen auf die Menge angewendet:

<Steps>
  <Step title="Mindestabnahme anwenden">
    Ist eine Mindestabnahme konfiguriert, wird die Menge auf mindestens diesen Wert gesetzt.

    `Menge = max(Menge, Mindestabnahme)`
  </Step>

  <Step title="Freie Einheiten abziehen">
    Sind freie Einheiten konfiguriert, werden diese von der Menge abgezogen. Die Menge kann nicht negativ werden.

    `Menge = max(Menge − freie Einheiten, 0)`
  </Step>

  <Step title="Preisberechnung">
    Die bereinigte Menge wird an die Berechnungslogik des jeweiligen Preistyps übergeben.
  </Step>
</Steps>

<Note>
  Die Mindestabnahme wird **vor** den freien Einheiten angewendet. Dadurch ist sichergestellt, dass die Mindestabnahme die Basis bildet, von der anschließend die freien Einheiten abgezogen werden.
</Note>

**Beispiel:** 5 Benutzer, Mindestabnahme 10, freie Einheiten 3

1. Mindestabnahme: max(5, 10) = **10**
2. Freie Einheiten: max(10 − 3, 0) = **7**
3. Es werden 7 Einheiten berechnet.

***

## Pauschale (Flat Fee)

Ein fester Betrag pro Abrechnungsperiode, unabhängig von der Menge.

| Eingabe | Wert    |
| ------- | ------- |
| Preis   | 29,00 € |

**Berechnung:** 29,00 € (fest, keine Mengenabhängigkeit)

<Tip>
  Pauschale eignet sich für Basispakete, Grundgebühren oder einmalige Setup-Gebühren.
</Tip>

***

## Pro Einheit (Per Unit)

Der Stückpreis wird mit der bereinigten Menge multipliziert.

| Eingabe    | Wert        |
| ---------- | ----------- |
| Stückpreis | 5,00 €      |
| Menge      | 10 Benutzer |

**Berechnung:** 10 × 5,00 € = **50,00 €**

**Mit freien Einheiten:** 10 Benutzer, 3 frei → 7 × 5,00 € = **35,00 €**

***

## Staffelpreis (Tiered)

Jeder Mengenbereich hat seinen eigenen Stückpreis. Die Bereiche werden **nacheinander** abgerechnet — jede Einheit erhält den Preis der Stufe, in die sie fällt.

### Stufenkonfiguration

| Stufe | Ab Menge | Stückpreis |
| ----- | -------- | ---------- |
| 1     | 0        | 10,00 €    |
| 2     | 10       | 8,00 €     |
| 3     | 50       | 6,00 €     |

Eine Stufe deckt die Menge von ihrem `Ab Menge`-Wert bis zum `Ab Menge`-Wert der nächsten Stufe ab. Die erste Stufe beginnt immer bei 0.

### Berechnungsbeispiel

**25 Einheiten:**

| Stufe     | Einheiten | Stückpreis | Zwischensumme |
| --------- | --------- | ---------- | ------------- |
| 1 (0–9)   | 10        | 10,00 €    | 100,00 €      |
| 2 (10–24) | 15        | 8,00 €     | 120,00 €      |

**Gesamt: 220,00 €**

**60 Einheiten:**

| Stufe     | Einheiten | Stückpreis | Zwischensumme |
| --------- | --------- | ---------- | ------------- |
| 1 (0–9)   | 10        | 10,00 €    | 100,00 €      |
| 2 (10–49) | 40        | 8,00 €     | 320,00 €      |
| 3 (50–59) | 10        | 6,00 €     | 60,00 €       |

**Gesamt: 480,00 €**

<Info>
  Bei Staffelpreisen mit freien Einheiten werden die freien Einheiten **vor** der Stufenzuordnung abgezogen. Die bereinigte Menge durchläuft dann die Stufen von vorne.
</Info>

**Mit freien Einheiten:** 25 Einheiten, 5 frei → 20 bereinigte Einheiten

| Stufe     | Einheiten | Stückpreis | Zwischensumme |
| --------- | --------- | ---------- | ------------- |
| 1 (0–9)   | 10        | 10,00 €    | 100,00 €      |
| 2 (10–19) | 10        | 8,00 €     | 80,00 €       |

**Gesamt: 180,00 €**

***

## Volumenpreis (Volume)

Der Stückpreis wird anhand der **Gesamtmenge** bestimmt. Alle Einheiten erhalten dann denselben Preis.

### Stufenkonfiguration

| Stufe | Ab Menge | Stückpreis |
| ----- | -------- | ---------- |
| 1     | 0        | 10,00 €    |
| 2     | 10       | 8,00 €     |
| 3     | 50       | 6,00 €     |

### Berechnungsbeispiel

**25 Einheiten:** Stufe 2 greift (25 ≥ 10) → 25 × 8,00 € = **200,00 €**

**60 Einheiten:** Stufe 3 greift (60 ≥ 50) → 60 × 6,00 € = **360,00 €**

**8 Einheiten:** Stufe 1 greift (8 ≥ 0) → 8 × 10,00 € = **80,00 €**

<Warning>
  Beim Volumenpreis mit freien Einheiten wird die Stufe anhand der **Gesamtmenge** (vor Abzug der freien Einheiten) bestimmt. Die Preisberechnung erfolgt dann mit der **bereinigten Menge** (nach Abzug).
</Warning>

**Mit freien Einheiten:** 25 Einheiten, 5 frei

1. Stufenbestimmung: Gesamtmenge 25 → Stufe 2 (8,00 €)
2. Berechnung: (25 − 5) × 8,00 € = 20 × 8,00 € = **160,00 €**

***

## Stufenpreis (Stair Step)

Ein **fester Betrag** pro Mengenstufe. Der Preis ist unabhängig von der genauen Menge innerhalb der Stufe.

### Stufenkonfiguration

| Stufe | Ab Menge | Festpreis |
| ----- | -------- | --------- |
| 1     | 0        | 50,00 €   |
| 2     | 10       | 150,00 €  |
| 3     | 50       | 300,00 €  |

### Berechnungsbeispiel

**8 Einheiten:** Stufe 1 greift (8 ≥ 0) → **50,00 €**

**25 Einheiten:** Stufe 2 greift (25 ≥ 10) → **150,00 €**

**60 Einheiten:** Stufe 3 greift (60 ≥ 50) → **300,00 €**

<Info>
  Beim Stufenpreis bestimmt — wie beim Volumenpreis — die **Gesamtmenge** (vor Abzug der freien Einheiten) die Stufe.
</Info>

***

## Prozentual (Percentage)

Ein Prozentsatz wird auf den gemeldeten Wert angewendet.

| Eingabe         | Wert            |
| --------------- | --------------- |
| Prozentsatz     | 2,5 %           |
| Stückpreis      | 1,00 €          |
| Gemeldeter Wert | 1.000 Einheiten |

**Berechnung:** 1.000 × 2,5 % × 1,00 € = 25 × 1,00 € = **25,00 €**

Zusätzlich können beim prozentualen Preistyp eigene Freibeträge konfiguriert werden:

* **Frei pro Ereignis:** Anzahl Einheiten, die pro Nutzungsereignis abgezogen werden
* **Frei pro Gesamt:** Anzahl Einheiten, die von der Gesamtsumme abgezogen werden

***

## Basisgebühr (flatAmount)

Neben dem mengenabhängigen Preis kann auf jeder Stufe eine **Basisgebühr** konfiguriert werden. Diese wird als fester Betrag zusätzlich zum Stückpreis berechnet, sobald die jeweilige Stufe Einheiten enthält.

<Tip>
  Basisgebühren eignen sich für monatliche Grundgebühren, die zusätzlich zu einem nutzungsabhängigen Preis anfallen.
</Tip>

### Beispiel: Staffelpreis mit Basisgebühr

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 5,00 €     | 199,00 €    |

**15 Einheiten:** 15 × 5,00 € + 199,00 € = **274,00 €**

### Beispiel: Mehrere Stufen mit Basisgebühr

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 10,00 €    | 99,00 €     |
| 2     | 20       | 7,00 €     | 0,00 €      |

**30 Einheiten:**

| Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
| --------- | --------- | ---------- | ------------- | ----------- |
| 1 (0–19)  | 20        | 10,00 €    | 200,00 €      | 99,00 €     |
| 2 (20–29) | 10        | 7,00 €     | 70,00 €       | 0,00 €      |

**Gesamt: 200,00 € + 99,00 € + 70,00 € = 369,00 €**

<Note>
  Die Basisgebühr wird nur berechnet, wenn die Stufe mindestens eine Einheit enthält. Bei Stufen ohne Einheiten fällt keine Basisgebühr an.
</Note>

***

## Freie Einheiten mit Basisgebühr

Wenn ein Preis sowohl freie Einheiten als auch eine Basisgebühr hat, ist es wichtig zu verstehen, wie diese zusammenwirken. Es gibt zwei Varianten:

### Variante 1: Basisgebühr fällt immer an

Die freien Einheiten werden als eigene Stufe mit einem Stückpreis von 0 konfiguriert. Die Basisgebühr wird auf dieser Stufe hinterlegt und fällt dadurch **immer** an — auch wenn die Nutzung innerhalb der freien Einheiten liegt.

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 0,00 €     | 199,00 €    |
| 2     | 10       | 99,00 €    | 0,00 €      |

<AccordionGroup>
  <Accordion title="5 Benutzer">
    | Stufe   | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | ------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9) | 5         | 0,00 €     | 0,00 €        | 199,00 €    |

    **Gesamt: 199,00 €** (nur die Basisgebühr, alle Benutzer sind inklusive)
  </Accordion>

  <Accordion title="15 Benutzer">
    | Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | --------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9)   | 10        | 0,00 €     | 0,00 €        | 199,00 €    |
    | 2 (10–14) | 5         | 99,00 €    | 495,00 €      | 0,00 €      |

    **Gesamt: 199,00 € + 495,00 € = 694,00 €**
  </Accordion>
</AccordionGroup>

### Variante 2: Basisgebühr fällt erst nach Verbrauch der freien Einheiten an

Die freien Einheiten werden über das Feld `Freie Einheiten` konfiguriert. Die Basisgebühr wird als `flatAmount` auf der ersten Stufe hinterlegt. Da die freien Einheiten **vor** der Stufenberechnung abgezogen werden, greift die Stufe erst, wenn die Nutzung die freien Einheiten übersteigt.

**Konfiguration:** 10 freie Einheiten

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 99,00 €    | 199,00 €    |

<AccordionGroup>
  <Accordion title="5 Benutzer">
    Abzug freie Einheiten: max(5 − 10, 0) = **0 bereinigte Einheiten**

    Keine Stufe greift, da keine bereinigten Einheiten vorhanden sind.

    **Gesamt: 0,00 €** (alle Benutzer liegen innerhalb der freien Einheiten)
  </Accordion>

  <Accordion title="15 Benutzer">
    Abzug freie Einheiten: max(15 − 10, 0) = **5 bereinigte Einheiten**

    | Stufe | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | ----- | --------- | ---------- | ------------- | ----------- |
    | 1     | 5         | 99,00 €    | 495,00 €      | 199,00 €    |

    **Gesamt: 495,00 € + 199,00 € = 694,00 €**
  </Accordion>
</AccordionGroup>

<Warning>
  Verwende niemals freie Einheiten und eine Stufe mit Stückpreis 0 gleichzeitig. Das würde dazu führen, dass Einheiten doppelt als kostenlos gewertet werden.
</Warning>

***

## Komplexbeispiel

**Szenario:** 99 € pro Benutzer/Monat, 10 Benutzer inklusive, ab dem 15. Benutzer 80 € pro Benutzer, Basisgebühr 199 €.

**Konfiguration** (Basisgebühr fällt immer an):

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 0,00 €     | 199,00 €    |
| 2     | 10       | 99,00 €    | 0,00 €      |
| 3     | 15       | 80,00 €    | 0,00 €      |

<AccordionGroup>
  <Accordion title="5 Benutzer">
    | Stufe   | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | ------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9) | 5         | 0,00 €     | 0,00 €        | 199,00 €    |

    **Gesamt: 199,00 € pro Monat**
  </Accordion>

  <Accordion title="12 Benutzer">
    | Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | --------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9)   | 10        | 0,00 €     | 0,00 €        | 199,00 €    |
    | 2 (10–11) | 2         | 99,00 €    | 198,00 €      | 0,00 €      |

    **Gesamt: 199,00 € + 198,00 € = 397,00 € pro Monat**
  </Accordion>

  <Accordion title="20 Benutzer">
    | Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | --------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9)   | 10        | 0,00 €     | 0,00 €        | 199,00 €    |
    | 2 (10–14) | 5         | 99,00 €    | 495,00 €      | 0,00 €      |
    | 3 (15–19) | 5         | 80,00 €    | 400,00 €      | 0,00 €      |

    **Gesamt: 199,00 € + 495,00 € + 400,00 € = 1.094,00 € pro Monat**
  </Accordion>
</AccordionGroup>


# Preise
Source: https://docs.fynn.eu/guide/catalogue/prices/introduction

Preise für deine Produkte konfigurieren

## Preistypen

Fynn unterstützt verschiedene Preistypen, um flexible Abrechnungsmodelle zu ermöglichen. Eine detaillierte Erklärung der Berechnungslogik mit Beispielen findest du unter [Preisberechnung](/guide/catalogue/prices/calculation).

<AccordionGroup>
  <Accordion title="Pauschale (Flat Fee)">
    Ein fester Preis unabhängig von der Menge. Ideal für Basispakete oder Grundgebühren.

    **Beispiel:** 29,00 € / Monat für das Starter-Paket
  </Accordion>

  <Accordion title="Pro Einheit (Per Unit)">
    Der Preis wird pro Einheit berechnet und mit der Menge multipliziert.

    **Beispiel:** 5,00 € pro Benutzer × 10 Benutzer = 50,00 €
  </Accordion>

  <Accordion title="Staffel (Tiered)">
    Unterschiedliche Preise für verschiedene Mengenbereiche. Jede Stufe wird separat berechnet.

    **Beispiel:**

    * 1-10 Einheiten: 10,00 € pro Einheit
    * 11-50 Einheiten: 8,00 € pro Einheit
    * 51+ Einheiten: 6,00 € pro Einheit

    Bei 60 Einheiten: (10 × 10 €) + (40 × 8 €) + (10 × 6 €) = 480,00 €
  </Accordion>

  <Accordion title="Volumen (Volume)">
    Der Preis der erreichten Stufe gilt für alle Einheiten.

    **Beispiel:**

    * 1-10 Einheiten: 10,00 € pro Einheit
    * 11-50 Einheiten: 8,00 € pro Einheit
    * 51+ Einheiten: 6,00 € pro Einheit

    Bei 60 Einheiten: 60 × 6,00 € = 360,00 €
  </Accordion>

  <Accordion title="Stufen (Stair Step)">
    Ein fester Preis pro Stufe, unabhängig von der genauen Menge innerhalb der Stufe.

    **Beispiel:**

    * 1-10 Einheiten: 50,00 €
    * 11-50 Einheiten: 150,00 €
    * 51+ Einheiten: 300,00 €

    Bei 60 Einheiten: 300,00 € (Festpreis der Stufe)
  </Accordion>

  <Accordion title="Prozentual (Percentage)">
    Der Preis wird als Prozentsatz eines Basiswerts berechnet.

    **Beispiel:** 2,5% vom Umsatz
  </Accordion>
</AccordionGroup>

## Währungen

Fynn unterstützt mehrere Währungen für internationale Kunden. Du kannst Preise in verschiedenen Währungen anlegen.

Die verfügbaren Währungen kannst du unter [Einstellungen > Währungen](/guide/tenant/currencies) konfigurieren.

<Tip>
  Für jeden Preis muss eine Währung ausgewählt werden. Stelle sicher, dass die gewünschten Währungen in den Einstellungen aktiviert sind.
</Tip>

## Dezimalstellen

Die Anzahl der Dezimalstellen für Preise wird automatisch basierend auf der Währung festgelegt:

| Währung | Dezimalstellen | Beispiel  |
| ------- | -------------- | --------- |
| EUR     | 2              | 19,99 €   |
| USD     | 2              | \$19.99   |
| CHF     | 2              | CHF 19.99 |

<Note>
  Bei der Berechnung von Zwischensummen werden intern mehr Dezimalstellen verwendet, um Rundungsfehler zu minimieren. Die finale Summe wird dann gerundet.
</Note>

## Testphasen

Testphasen (Trial Periods) ermöglichen es Kunden, ein Produkt kostenlos zu testen, bevor die reguläre Abrechnung beginnt.

<Steps>
  <Step title="Testphase konfigurieren">
    Beim Erstellen eines Preises kannst du die Dauer der Testphase in Tagen angeben.
  </Step>

  <Step title="Abonnement mit Testphase">
    Wird ein Abonnement mit einem Preis erstellt, der eine Testphase hat, beginnt die Abrechnung erst nach Ablauf der Testphase.
  </Step>

  <Step title="Testphase beenden">
    Die Testphase kann jederzeit manuell beendet werden, um die reguläre Abrechnung zu starten.
  </Step>
</Steps>

<Warning>
  Während der Testphase wird keine Rechnung erstellt. Stelle sicher, dass eine gültige Zahlungsmethode hinterlegt ist, bevor die Testphase endet.
</Warning>

## Freie Einheiten

Ist ein Produkt zum Abo hinzugefügt, welches freien Einheiten im Preis definiert hat, werden diese von der Gesamtmenge dieses Produktes abgezogen.

**Beispiel: Abo Plan M**

* Produkt (Benutzer): 10 Stück (angegebene Menge), 5 inklusive (freie Einheiten) = 5 Stück werden pro Einheit berechnet
* Produkt (Speicher): 100 GB (angegebene Menge), 50 GB inklusive (freie Einheiten) = 50 GB werden pro Einheit berechnet

Ist die angegebene Menge kleiner als die freien Einheiten, wird der Preis auf 0 gesetzt.

<Tip>
  Die freien Einheiten gelten für die angegebene Abrechnungsperiode. Wird ein Produkt jährlich abgerechnet, gelten die freien Einheiten für das gesamte Jahr.
</Tip>

## Abrechnungsintervalle

Preise können in verschiedenen Intervallen abgerechnet werden:

| Intervall           | Beschreibung                           |
| ------------------- | -------------------------------------- |
| **Täglich**         | Abrechnung jeden Tag                   |
| **Wöchentlich**     | Abrechnung jede Woche                  |
| **Monatlich**       | Abrechnung jeden Monat                 |
| **Vierteljährlich** | Abrechnung alle 3 Monate               |
| **Halbjährlich**    | Abrechnung alle 6 Monate               |
| **Jährlich**        | Abrechnung einmal pro Jahr             |
| **Einmalig**        | Einmalige Abrechnung ohne Wiederholung |

<Info>
  Bei der Auswahl des Abrechnungsintervalls solltest du berücksichtigen, wie deine Kunden zahlen möchten. Monatliche Abrechnung bietet Flexibilität, jährliche Abrechnung kann Rabatte ermöglichen.
</Info>

## Vorauszahlung vs Nachzahlung

Preise können entweder im Voraus oder im Nachhinein berechnet werden:

<CardGroup>
  <Card title="Vorauszahlung (In Advance)">
    Der Kunde zahlt zu Beginn der Abrechnungsperiode für den kommenden Zeitraum.

    **Beispiel:** Am 1. Januar wird für Januar abgerechnet.

    **Vorteile:**

    * Sofortiger Zahlungseingang
    * Geringeres Risiko für Zahlungsausfälle
  </Card>

  <Card title="Nachzahlung (In Arrears)">
    Der Kunde zahlt am Ende der Abrechnungsperiode für den vergangenen Zeitraum.

    **Beispiel:** Am 1. Februar wird für Januar abgerechnet.

    **Vorteile:**

    * Genaue Abrechnung basierend auf tatsächlicher Nutzung
    * Ideal für nutzungsbasierte Preise
  </Card>
</CardGroup>

<Note>
  Nutzungsbasierte Preise (Metered) werden standardmäßig im Nachhinein abgerechnet, da die genaue Nutzung erst am Ende der Periode bekannt ist.
</Note>

## Proratierung

Proratierung bedeutet die anteilige Berechnung von Preisen bei Änderungen innerhalb einer Abrechnungsperiode.

**Wann wird proratiert?**

* Beim Hinzufügen eines Produkts mitten in der Abrechnungsperiode
* Bei Mengenänderungen (z.B. mehr Benutzer)
* Bei Upgrades oder Downgrades

**Beispiel:**
Ein Kunde fügt am 15. des Monats 5 zusätzliche Benutzer hinzu (10 €/Benutzer/Monat).

* Verbleibende Tage im Monat: 15 von 30
* Proratierter Betrag: 5 × 10 € × (15/30) = 25,00 €

<Tip>
  Die Proratierung kann in den Einstellungen unter [Abrechnung](/guide/tenant/billing) aktiviert oder deaktiviert werden.
</Tip>


# Vorausabrechnung vs. Nachgelagert
Source: https://docs.fynn.eu/guide/catalogue/pricing-and-billing-timing

Wann zahlt der Kunde im Voraus, wann erst danach? Entscheidungshilfe und saubere Modellierung von Mischformen.

Fynn unterstützt zwei Abrechnungszeitpunkte: **Vorausabrechnung** (`payInAdvance = true`) und **Nachgelagert** (`payInAdvance = false`). Welcher davon richtig ist, hängt davon ab, ob die abzurechnende Menge zum Periodenstart bereits feststeht.

Dieser Artikel richtet sich an Solution Architects und Power‑User, die Preismodelle abbilden. Wenn du nur ein einfaches Abo mit Festpreis konfigurierst, brauchst du nicht weiterzulesen — der Default ist Vorausabrechnung und das ist meistens richtig.

***

## Entscheidungsmatrix

| Konstellation                                                                   | Abrechnungszeitpunkt             | Begründung                                        |
| ------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------- |
| Festpreis pro Periode (z.B. „99 €/Monat")                                       | **Vorausabrechnung**             | Menge und Preis stehen zum Periodenstart fest     |
| Mengenpreis mit fester Anzahl Einheiten (z.B. „10 Lizenzen × 8 €/Monat")        | **Vorausabrechnung**             | Menge ist im Vertrag/Abonnement gesetzt           |
| Nutzungsbasiert (BillableMetric, z.B. „pro API‑Call")                           | **Nachgelagert** (erzwungen)     | Menge ergibt sich erst aus den Events der Periode |
| Staffelpreis ohne Nutzungsmetrik (z.B. „bis 100 Lizenzen 8 €, ab 101 dann 6 €") | **Vorausabrechnung**             | Menge bleibt im Abonnement gesetzt                |
| Einmalige Setup‑Gebühr                                                          | **Vorausabrechnung** (`OneTime`) | Wird sofort fällig                                |

<Warning>
  Nutzungsbasierte Produkte werden technisch zwingend nachgelagert abgerechnet. Der `Vorausabrechnung`‑Schalter ist im PricePlan‑Editor automatisch gesperrt, sobald das verknüpfte Produkt eine Nutzungsmetrik trägt. Wenn du eine Hybridform brauchst, modellierst du das als zwei Positionen (siehe unten).
</Warning>

***

## Warum Nutzungsbasiert immer nachgelagert ist

Eine Nutzungsmetrik wie „Tokens", „API‑Calls" oder „Storage‑GB" aggregiert Ereignisse, die **während** einer Abrechnungsperiode entstehen. Vor Periodenende kennt das System die Summe nicht.

Wäre die Vorausabrechnung erlaubt, müsste der Wert geschätzt werden. Das führt zu zwei Problemen, die in der Praxis immer auftreten:

1. **Schätzfehler**: Der Schätzwert weicht von der tatsächlichen Nutzung ab. Die erste Rechnung müsste später korrigiert werden — entweder durch eine Gutschrift oder eine Nachberechnung. Bei vielen Abonnements bedeutet das eine Welle korrigierter Rechnungen mit allem Buchhaltungs‑Overhead.
2. **Falsche Signale an den Kunden**: Eine Rechnung, deren Betrag nicht den tatsächlichen Verbrauch widerspiegelt, untergräbt das Versprechen „du zahlst nur, was du verbrauchst".

Deshalb: Nutzung wird gemessen, dann abgerechnet, nie umgekehrt.

***

## Mischformen sauber modellieren

Drei gängige Anforderungen werden oft fälschlich als „BillableMetric mit Vorausabrechnung" formuliert. Alle drei lassen sich sauber mit **zwei Abonnementpositionen** abbilden:

### Mindestabnahme + Mehrverbrauch

**Anforderung:** „Mindestens 10.000 API‑Calls im Monat sind inklusive und werden monatlich im Voraus berechnet. Was darüber hinausgeht, kostet 0,01 € pro Call und wird am Monatsende abgerechnet."

**Modellierung:**

<Steps>
  <Step title="Position 1 – Grundgebühr (Vorausabrechnung)">
    * Produkt: „API‑Zugang Standard"
    * PricePlan: `flat_fee`, **Vorausabrechnung**, 100 €/Monat
    * Keine Nutzungsmetrik
  </Step>

  <Step title="Position 2 – Verbrauch (Nachgelagert)">
    * Produkt: „API‑Calls" mit Nutzungsmetrik (`COUNT` auf Event `api_call`)
    * PricePlan: `per_unit`, **Nachgelagert**, 0,01 €/Call
    * **Freikontingent: 10.000 Calls/Monat** im PricePlan
  </Step>
</Steps>

Effekt: Der Kunde bekommt am 1. eine Rechnung über 100 € (Grundgebühr). Am Monatsende wird Position 2 abgerechnet — wenn er unter 10.000 Calls geblieben ist, beträgt der Betrag 0 €. Liegt er bei 12.000 Calls, sind das 2.000 × 0,01 € = 20 €.

### Prepaid‑Credits / Volumenpaket

**Anforderung:** „Der Kunde kauft ein Paket mit 50.000 Tokens für 200 €. Die Tokens werden verbraucht, dann muss er ein neues Paket kaufen."

**Modellierung:**

<Steps>
  <Step title="Position 1 – Token‑Paket (Vorausabrechnung, einmalig)">
    * Produkt: „Token‑Paket 50k"
    * PricePlan: `OneTime`, **Vorausabrechnung**, 200 € fix
    * Wird beim Kauf abgerechnet
  </Step>

  <Step title="Position 2 – Nutzungs‑Tracking (Nachgelagert, mit Filter)">
    * Produkt: „Token‑Nutzung" mit Nutzungsmetrik (`SUM` auf `tokens_used`)
    * PricePlan: `per_unit`, **Nachgelagert**, 0 €/Token
    * **Freikontingent entspricht dem gekauften Paket‑Volumen**
    * Wenn das Paket aufgebraucht ist, wird über einen Filter oder ein Folge‑Produkt nachgeladen
  </Step>
</Steps>

Das Verbrauchs‑Tracking erzeugt also keine eigene Rechnung (Preis ist 0 €), dient aber der Transparenz im Kundenportal („du hast 32.000 von 50.000 Tokens verbraucht"). Ist das Paket aufgebraucht, sendet dein System das nächste „Paket‑gekauft"‑Event und der Zyklus startet neu.

### Geschätzte Abrechnung mit True‑Up

**Anforderung:** „Der Kunde zahlt monatlich 500 € im Voraus auf Basis einer Schätzung. Am Quartalsende wird die tatsächliche Nutzung gegengerechnet."

**Modellierung:** Diese Variante ist in der Praxis im DACH‑B2B‑SaaS selten und wird in Fynn nicht durch ein Spezial‑Feature unterstützt. Die saubere Abbildung ist:

<Steps>
  <Step title="Position 1 – Abschlagszahlung (Vorausabrechnung, monatlich)">
    * Produkt: „Service Abschlag"
    * PricePlan: `flat_fee`, **Vorausabrechnung**, 500 €/Monat
  </Step>

  <Step title="Position 2 – Tatsächliche Nutzung (Nachgelagert, quartalsweise)">
    * Produkt: „Service Nutzung" mit Nutzungsmetrik
    * PricePlan: `per_unit`, **Nachgelagert**, quartalsweise
  </Step>

  <Step title="Periodenend‑Korrektur über Rechnungskorrektur">
    Am Quartalsende erzeugst du eine Rechnungskorrektur, die die drei Abschlagsrechnungen (Position 1) mit der Nutzungsrechnung (Position 2) gegenrechnet. Saldo positiv → Nachberechnung, Saldo negativ → Gutschrift.
  </Step>
</Steps>

<Tip>
  Wenn du diese Variante häufig brauchst, sprich mit uns. Wir haben in der Roadmap einen „Estimated Billing"‑Workflow, der die True‑Up‑Korrektur am Periodenende automatisiert.
</Tip>

***

## Was im Hintergrund passiert

Wenn ein Abonnement aktiviert wird, gibt es zwei mögliche Verläufe:

**Vorausabrechnung (`payInAdvance = true`):**

1. Subscription‑Start am 1. Mai
2. Sofort wird eine Rechnung für `[1. Mai, 1. Juni)` erzeugt
3. Nächste Abrechnung: 1. Juni für `[1. Juni, 1. Juli)`, etc.

**Nachgelagert (`payInAdvance = false`):**

1. Subscription‑Start am 1. Mai
2. **Keine** Rechnung am 1. Mai
3. Während Mai werden Nutzungsereignisse erfasst
4. Am 1. Juni: Rechnung für `[1. Mai, 1. Juni)` mit der aggregierten Mai‑Nutzung
5. Nächste Abrechnung: 1. Juli für `[1. Juni, 1. Juli)`, etc.

Beide Modelle laufen über denselben Cron‑Lauf — der Unterschied liegt nur darin, wann der erste Rechnungslauf zündet.

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich einen einzelnen Kunden auf Vorausabrechnung umstellen, auch wenn das Produkt nutzungsbasiert ist?">
    Nein. Die Regel gilt produktseitig, nicht kundenseitig. Wenn du für einen Kunden ein anderes Abrechnungsmodell brauchst, modellierst du das über eine separate Abonnementposition mit anderem Produkt.
  </Accordion>

  <Accordion title="Was passiert, wenn ein Kunde mitten in einer Periode kündigt?">
    Bei Vorausabrechnung gibt es typischerweise eine anteilige Gutschrift für den ungenutzten Rest. Bei nachgelagerter Abrechnung wird die bis zur Kündigung erfasste Nutzung wie üblich am nächsten Abrechnungstermin in Rechnung gestellt — ohne Sonderbehandlung.
  </Accordion>

  <Accordion title="Können in einem Abonnement beide Abrechnungszeitpunkte gleichzeitig vorkommen?">
    Ja. Jede Abonnementposition entscheidet selbst. Eine Position mit Grundgebühr kann im Voraus laufen, während eine zweite Position mit Nutzungsabrechnung nachgelagert läuft. Die Rechnungen erscheinen einfach zu verschiedenen Zeitpunkten.
  </Accordion>
</AccordionGroup>

***

## Verwandte Themen

<CardGroup>
  <Card title="Nutzungsmetriken" icon="chart-line" href="/guide/catalogue/measurements/billable-metrics">
    Wie du Events erfasst und aggregierst.
  </Card>

  <Card title="Verständnis nutzungsbasierter Abrechnung" icon="calculator" href="/guide/catalogue/measurements/usage-based-billing">
    Wie die Aggregation in der Abrechnung sichtbar wird.
  </Card>
</CardGroup>


# Produktkategorien
Source: https://docs.fynn.eu/guide/catalogue/product-categories

Erstelle und verwalte deine Produktkategorien

<Frame>
  <img alt="Produktkategorien" />
</Frame>

Fynn ermöglicht es dir, Produktkategorien zu erstellen und zu verwalten, um deine Produkte besser zu organisieren. Produktkategorien helfen dir, ähnliche Produkte zu gruppieren und die Übersichtlichkeit in deinem Katalog zu verbessern.

## Produktkategorien erstellen

Um eine neue Produktkategorie zu erstellen, gehe zu [Katalog > Produkte](https://preview.fynn.eu/catalogue/products). Hier kannst du eine neue Kategorie hinzufügen, indem du auf den Button "Neue Kategorie hinzufügen" klickst.

## Produkte zu Kategorien hinzufügen

<Frame>
  <img alt="Produkte zu Kategorien hinzufügen" />
</Frame>

Nachdem du eine Kategorie erstellt hast, kannst du Produkte zu dieser Kategorie hinzufügen. Dazu neben der Kategorie auf die drei Punkte klicken und "Produkte zuordnen" auswählen. Du kannst dann die gewünschten Produkte aus deinem Katalog auswählen und sie der Kategorie zuordnen.


# Up- & Downgrades
Source: https://docs.fynn.eu/guide/catalogue/product-groups

Definiere Upgrade- und Downgrade-Pfade für Self-Service Paketwechsel

Mit Produktgruppen definierst du, welche Produkte zusammengehören und wie Kunden zwischen ihnen wechseln können. So ermöglichst du Self-Service Upgrades und Downgrades im Kundenbereich.

<Note>
  Produktgruppen unterscheiden sich von Produktfamilien: Während Produktfamilien nur zur Strukturierung des Katalogs dienen, steuern Produktgruppen die Wechselmöglichkeiten zwischen Produkten.
</Note>

## Anwendungsfälle

| Szenario          | Beschreibung                              |
| ----------------- | ----------------------------------------- |
| **Tier-Wechsel**  | Kunde wechselt von Starter zu Pro Paket   |
| **Upgrade**       | Kunde bucht ein höherwertiges Paket       |
| **Downgrade**     | Kunde wechselt zu einem günstigeren Paket |
| **Mengenwechsel** | Kunde ändert die Anzahl der Lizenzen      |

***

## Konzept

Eine Produktgruppe besteht aus mehreren **Tiers** (Memberships), die jeweils ein Produkt mit seinen Preisplänen repräsentieren. Die Reihenfolge der Tiers bestimmt die Upgrade-/Downgrade-Richtung.

```
Produktgruppe: "SaaS Pakete"
├── Position 1: Starter (günstigster)
├── Position 2: Pro
└── Position 3: Enterprise (teuerster)
```

* **Upgrade**: Wechsel zu einer höheren Position (z.B. Starter → Pro)
* **Downgrade**: Wechsel zu einer niedrigeren Position (z.B. Pro → Starter)

***

## Produktgruppe erstellen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Produktgruppe anlegen">
        Navigiere zu **Produkte > Produktgruppen** und klicke auf "Produktgruppe erstellen".

        Vergib einen Namen wie "SaaS Pakete" oder "Hosting Plans".
      </Step>

      <Step title="Tiers hinzufügen">
        Füge für jedes Paket ein Tier hinzu:

        1. Wähle das **Produkt** (z.B. "Starter Plan")
        2. Wähle die **Preispläne** (z.B. "Starter Monatlich", "Starter Jährlich")
        3. Konfiguriere **Upgrade/Downgrade-Verhalten**
      </Step>

      <Step title="Reihenfolge festlegen">
        Ordne die Tiers in der gewünschten Reihenfolge an. Die Position bestimmt, was als Upgrade oder Downgrade gilt.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    ```bash theme={null}
    curl -X POST "https://coreapi.io/catalogue/product-groups" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "name": "SaaS Pakete",
        "enabled": true,
        "forceSameBillingInterval": false,
        "memberships": [
          {
            "product": "/products/starter-uuid",
            "pricePlans": ["/plans/starter-monthly-uuid"],
            "position": 1,
            "upgradeable": true,
            "downgradeable": false,
            "changeTiming": "end_of_period",
            "label": "Starter"
          },
          {
            "product": "/products/pro-uuid",
            "pricePlans": ["/plans/pro-monthly-uuid"],
            "position": 2,
            "upgradeable": true,
            "downgradeable": true,
            "changeTiming": "immediately",
            "creditType": "pro_rata",
            "label": "Pro"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

***

## Tier-Einstellungen

Jedes Tier in einer Produktgruppe hat folgende Einstellungen:

### Upgrade & Downgrade

| Einstellung       | Beschreibung                                     |
| ----------------- | ------------------------------------------------ |
| **Upgradeable**   | Kann zu höheren Positionen gewechselt werden     |
| **Downgradeable** | Kann zu niedrigeren Positionen gewechselt werden |

<Tip>
  Das günstigste Paket sollte `upgradeable: true, downgradeable: false` sein, da es kein niedrigeres Paket gibt.
</Tip>

### Wechselzeitpunkt (Change Timing)

| Option                                 | Beschreibung                                                 |
| -------------------------------------- | ------------------------------------------------------------ |
| **Sofort** (`immediately`)             | Wechsel wird sofort aktiv                                    |
| **Zum Periodenende** (`end_of_period`) | Wechsel wird zum Ende der aktuellen Abrechnungsperiode aktiv |

### Gutschrift-Typ (Credit Type)

Nur relevant wenn `changeTiming = immediately`:

| Option                                | Beschreibung                                  |
| ------------------------------------- | --------------------------------------------- |
| **Anteilig** (`pro_rata`)             | Gutschrift basierend auf verbleibenden Tagen  |
| **Vollständig** (`full`)              | Vollständige Gutschrift der aktuellen Periode |
| **Letzte Rechnung** (`last_invoiced`) | Gutschrift der letzten Rechnung               |
| **Keine** (`none`)                    | Keine Gutschrift                              |

***

## Produktgruppe zuweisen

Damit Kunden wechseln können, muss die Produktgruppe einem Abonnement-Artikel zugewiesen werden.

<Tip>
  **Automatische Zuweisung im Checkout**: Wenn ein Preisplan einer Produktgruppe zugeordnet ist, wird die Produktgruppe bei Abonnements aus dem Checkout automatisch zugewiesen. Eine manuelle Zuweisung ist nur für Abonnements erforderlich, die in der Wallet erstellt wurden.
</Tip>

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Abonnement öffnen">
        Navigiere zum Abonnement und öffne den Artikel, für den Up-/Downgrades aktiviert werden sollen.
      </Step>

      <Step title="Produktgruppe zuweisen">
        Unter "Produktgruppe" wähle die entsprechende Gruppe aus.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    ```bash theme={null}
    curl -X PUT "https://coreapi.io/subscription-items/{itemId}/product-group" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "productGroupMembership": "membership-uuid"
      }'
    ```
  </Tab>
</Tabs>

***

## Wechsel durchführen

### Im Kundenbereich

Sobald eine Produktgruppe zugewiesen ist, sehen Kunden im Kundenbereich die verfügbaren Wechseloptionen:

1. Kunde öffnet sein Abonnement
2. Klickt auf "Ändern"
3. Wählt das neue Paket und bestätigt
4. Wechsel wird je nach Konfiguration sofort oder zum Periodenende angewendet

### Per API

```bash theme={null}
# 1. Verfügbare Optionen abrufen
curl -X GET "https://coreapi.io/subscription-items/{itemId}/change-options" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Wechsel anwenden
curl -X POST "https://coreapi.io/product-group-memberships/{membershipId}/apply" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subscriptionItem": "item-uuid",
    "selectedPricePlan": "price-plan-uuid",
    "quantity": 1
  }'
```

***

## Einstellungen

### Gleiches Abrechnungsintervall erzwingen

Mit `forceSameBillingInterval: true` können Kunden nur zwischen Preisplänen mit gleichem Abrechnungsintervall wechseln. Ein Kunde mit monatlichem Plan sieht dann nur monatliche Optionen.

***

## API Übersicht

| Endpoint                                                                                     | Methode | Beschreibung                       |
| -------------------------------------------------------------------------------------------- | ------- | ---------------------------------- |
| [`/catalogue/product-groups`](/api-reference/productgroup/get-product-groups)                | GET     | Alle Produktgruppen abrufen        |
| [`/catalogue/product-groups`](/api-reference/productgroup/create-product-group)              | POST    | Neue Produktgruppe erstellen       |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/get-product-group)            | GET     | Einzelne Produktgruppe abrufen     |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/update-product-group)         | PUT     | Produktgruppe aktualisieren        |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/delete-product-group)         | DELETE  | Produktgruppe löschen              |
| [`/subscription-items/{id}/product-group`](/api-reference/productgroup/assign-product-group) | PUT     | Up- & Downgrades aktivieren        |
| [`/subscription-items/{id}/change-options`](/api-reference/productgroup/get-change-options)  | GET     | Verfügbare Wechseloptionen abrufen |
| [`/product-group-memberships/{id}/apply`](/api-reference/productgroup/apply-membership)      | POST    | Tier wechseln                      |

***

## Verwandte Dokumentation

<CardGroup>
  <Card title="Abonnement-Übergänge" icon="arrow-right-arrow-left" href="/guide/subscriptions/transitions">
    Manuelle Übergänge mit Proration
  </Card>

  <Card title="Produkte" icon="box" href="/guide/catalogue/products">
    Produkte erstellen und verwalten
  </Card>

  <Card title="Kundenbereich" icon="user" href="/guide/customers/customer-portal">
    Self-Service für Kunden
  </Card>

  <Card title="API Guide: Upgrades" icon="code" href="/api-reference/guides/implement-upgrades">
    Upgrades in eigene Apps integrieren
  </Card>
</CardGroup>


# Produkte
Source: https://docs.fynn.eu/guide/catalogue/products

Erstelle und verwalte deine Produkte

## Produkt hinzufügen

<Frame>
  <img alt="Produkt hinzufügen" />
</Frame>

Um ein neues Produkt zu erstellen, gehe zu [Katalog > Produkte](https://preview.fynn.eu/catalogue/products) und klicke auf <b>Produkt hinzufügen</b>.

Für ein neues Produkt musst du folgende Informationen angeben:

* <b>Name</b>: Der Name des Produkts, der in der Produktliste und in Rechnungen angezeigt wird.
* <b>Abrechenbare Einheit</b>: Die Einheit, in der das Produkt abgerechnet wird, z.B. "Stück", "Stunden" oder "Monat".
* <b>Steuergruppe</b>: Die Steuergruppe, die für dieses Produkt gilt. Dies ist wichtig für die korrekte Berechnung der Steuern auf Rechnungen.

Klicke auf <b>Produkt erstellen</b>, um das Produkt zu erstellen. Das Produkt wird nun in der Produktliste angezeigt und man kann nun die Preise für das Produkt festlegen.

## Produkt archivieren

Ein Produkt kann archiviert werden, wenn es nicht mehr benötigt wird oder nicht mehr verfügbar ist.
Ist ein Produkt archiviert, kann es nicht mehr für neue Abonnements oder Rechnungen verwendet werden.

<Info>
  Archivierte Produkte werden nicht mehr in der Produktliste oder der Produktauswahl angezeigt.
</Info>

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Produktdetailseite öffnen">
        Klicke in der Seitenleiste auf [Katalog > Produkte](https://preview.fynn.eu/catalogue/products) und wähle das Produkt aus, das du archivieren möchtest.
      </Step>

      <Step title="Produkt archivieren">
        Klicke auf <b>Archivieren</b> um das Produkt zu archivieren und bestätige die Aktion.
      </Step>

      <Step title="Produkt wurde erfolgreich archiviert">
        Das Produkt wurde erfolgreich archiviert und ist nicht mehr in der Produktliste oder der Produktauswahl verfügbar.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Produkt archivieren](/api-reference/product/archive-a-product) Endpunkt.

    ```bash theme={null}
    PUT /catalog/products/{productId}/archive
    ```

    Alternativ kannst du das [Produkt abrufen](/api-reference/product/get-a-product)
    oder den [Produke über die API aktualisieren](/api-reference/product/update-a-product).
  </Tab>
</Tabs>


# Einheiten
Source: https://docs.fynn.eu/guide/catalogue/units

Erstelle und verwalte deine Einheiten

Einheiten sind Maßeinheiten, die verwendet werden, um Produkte und Dienstleistungen zu quantifizieren.
Sie können verschiedene Formen annehmen, wie z.B. Stück, Kilogramm, Liter, Stunden usw.
Einheiten ermöglichen es dir, den Preis und die Menge eines Produkts oder einer Dienstleistung genau zu definieren.

## Nutzung von Einheiten

Einheiten werden in Fynn für folgende Zwecke genutzt:

* <b>Abrechenbare Einheiten</b>: Einheiten werden in abrechenbaren Einheiten referenziert, um die Menge zu quantifizieren, die für die Abrechnung verwendet wird. Zum Beispiel, wenn du eine Dienstleistung anbietest, die pro Stunde abgerechnet wird, kannst du die Einheit `Stunde` verwenden, um die Menge der Stunden zu quantifizieren, die für die Abrechnung verwendet werden.

* <b>Abrechnung und Rechnungsstellung</b>: Einheiten werden auch bei der [manuellen Rechnungsstellung](/guide/billing/invoices#manuelle-rechnung-erstellen) verwendet, um die Menge der Positionen auf der Rechnung zu quantifizieren.

## Unterschied zwischen Einheiten und abrechenbaren Einheiten

Einheiten und abrechenbare Einheiten sind zwei verschiedene Konzepte in Fynn.

Einheiten können nicht direkt für die wiederkehrende Abrechnung verwendet werden. Sie werden nur als Referenz für die Menge verwendet, die in abrechenbaren Einheiten abgerechnet wird.
D.h. ein [Preis](/guide/catalogue/prices) wird immer mit einer abrechenbaren Einheiten definiert, nicht mit Einheiten.

<Tip>
  Solltest du hier Unklarheiten haben, zögere nicht, uns zu kontaktieren: [Termin buchen](https://cal.com/team/fynn/fynn-documentation)
</Tip>

## Einheit erstellen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Einheit erstellen">
        Einheiten können dort erstellt werden, wo ein entsprechendes Dropdown verfügbar ist.

        Beispielsweise in der ["Neue abrechenbare Einheit" Maske](/guide/catalogue/measurements/introduction#neue-abrechenbare-einheit-erstellen).
        Oder in der ["Rechnung erstellen" Maske](/guide/billing/invoices#manuelle-rechnung-erstellen).

        <Frame>
          <img alt="Einheit erstellen" />
        </Frame>
      </Step>

      <Step title="Einheit eingeben">
        Klicke nun auf "Neue Einheit erstellen" und gib den Namen der Einheit ein.

        <Frame>
          <img alt="Einheit eingeben" />
        </Frame>
      </Step>

      <Step title="Einheit speichern">
        Klicke auf das "Check"-Symbol, um die Einheit zu speichern. Du kannst die Einheit nun in der Dropdown-Liste auswählen.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Einheit erstellen](/api-reference/unit/create-a-unit) Endpunkt.

    ```bash theme={null}
    POST /units
    ```

    Alternativ kannst du die [Einheit abrufen](/api-reference/unit/get-a-unit)
    oder die [Einheit über die API aktualisieren](/api-reference/unit/update-a-unit).
  </Tab>
</Tabs>

<Tip>
  <b>Mehrsprachigkeit</b><br />
  Aktuell kann hierfür nur über die API eine weitere Übersetzung in einer anderen Sprache hinzugefügt werden.
  Die korrekte Übersetzung erfolgt dann auf der Sprache des Kunden. Sollte die Übersetzung nicht in der entsprechenden Sprache
  verfügbar sein, wird standardmäßig die deutsche Übersetzung verwendet.
</Tip>

## Einheit bearbeiten

Eine Einheit kann nicht über die Web-App bearbeitet werden. Du kannst jedoch die [Einheit über die API aktualisieren](/api-reference/unit/update-a-unit).

## Einheit löschen

Eine Einheit kann aktuell nicht gelöscht werden.


# Nutzungsereignisse senden
Source: https://docs.fynn.eu/guide/catalogue/usage-events-import

Sende Nutzungsereignisse über CSV oder die API für nutzungsbasierte Abrechnung

Nutzungsereignisse sind die Grundlage für nutzungsbasierte Abrechnung. Es gibt zwei Möglichkeiten, Ereignisse zu senden: über CSV-Dateien oder direkt über die REST API.

## Übersicht

| Methode        | Verwendung                     | Limit                          |
| -------------- | ------------------------------ | ------------------------------ |
| **CSV Import** | Bulk-Import historischer Daten | Bis zu 10 MB pro Datei         |
| **API Import** | Echtzeit-Event-Erfassung       | Bis zu 1000 Events pro Request |

<Tip>
  Für einmalige Imports historischer Daten oder Backfill-Szenarien verwende CSV Import. Für kontinuierliche, Echtzeit-Event-Erfassung aus Anwendungen verwende die API.
</Tip>

## CSV Import

### CSV Format

Die CSV-Datei muss folgende Spalten enthalten:

| Spalte           | Typ      | Erforderlich | Beschreibung                                        |
| ---------------- | -------- | ------------ | --------------------------------------------------- |
| `transaction_id` | string   | Ja           | Eindeutige Transaktions-ID für Idempotenz           |
| `event_name`     | string   | Ja           | Name des Events (z.B. "api\_call", "storage\_used") |
| `timestamp`      | ISO 8601 | Ja           | Event-Zeitstempel (z.B. "2026-01-13T10:30:00Z")     |
| `customer_id`    | string   | Ja           | Kunden-Identifier (Fynn-UUID oder `externalId`)     |
| `properties`     | JSON     | Ja           | Event-Eigenschaften als JSON-Objekt                 |

<Warning>
  Die Datei muss im UTF-8 Format vorliegen. Die `properties`-Spalte muss ein gültiges JSON-Objekt enthalten. Maximale Dateigröße: 10 MB.
</Warning>

### Import über die Benutzeroberfläche

1. Navigiere zur Seite **Verbrauchsdaten**
2. Klicke auf das **Aktionen**-Dropdown im Header
3. Wähle **CSV Import**
4. Im Dialog:
   * Klicke auf den Upload-Bereich oder ziehe eine CSV-Datei hinein
   * Wähle die CSV-Datei aus
   * Klicke auf **Importieren**

<Frame>
  <img alt="CSV Import Dialog" />
</Frame>

**Nach dem Import:**

* Die Events werden asynchron verarbeitet
* Die Tabelle wird automatisch aktualisiert
* Bei Fehlern wird eine Fehlermeldung angezeigt

### Beispiel CSV

```csv theme={null}
transaction_id,event_name,timestamp,customer_id,properties
tx-12345,api_call,2026-01-13T10:30:00Z,550e8400-e29b-41d4-a716-446655440000,"{""endpoint"":""/api/v1/users"",""method"":""GET"",""response_time_ms"":145,""status_code"":200}"
tx-12346,storage_used,2026-01-13T10:31:00Z,550e8400-e29b-41d4-a716-446655440000,"{""bytes"":1048576,""storage_type"":""database""}"
tx-12347,api_call,2026-01-13T10:32:00Z,550e8400-e29b-41d4-a716-446655440000,"{""endpoint"":""/api/v1/products"",""method"":""POST"",""response_time_ms"":234,""status_code"":201}"
```

<Info>
  JSON-Objekte in der `properties`-Spalte müssen mit doppelten Anführungszeichen escaped werden (`""`).
</Info>

## API Import

Nutzungsereignisse können programmatisch über die REST API gesendet werden. Unterstützt einzelne Events oder Batch-Import (bis zu 1000 Events pro Anfrage).

### Authentifizierung

Der API-Schlüssel muss im Request-Header übergeben werden:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Einzelnes Event senden

**Endpoint:** `POST /api/usage-events`

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "events": [
      {
        "transactionId": "tx-12345",
        "eventName": "api_call",
        "timestamp": "2026-01-13T10:30:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "endpoint": "/api/v1/users",
          "method": "GET",
          "response_time_ms": 145,
          "status_code": 200
        }
      }
    ]
  }'
```

### Batch Import

Bis zu 1000 Events können in einem Request gesendet werden:

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "events": [
      {
        "transactionId": "tx-12345",
        "eventName": "api_call",
        "timestamp": "2026-01-13T10:30:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "endpoint": "/api/v1/users",
          "method": "GET",
          "response_time_ms": 145,
          "status_code": 200
        }
      },
      {
        "transactionId": "tx-12346",
        "eventName": "storage_used",
        "timestamp": "2026-01-13T10:31:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "bytes": 1048576,
          "storage_type": "database"
        }
      }
    ]
  }'
```

### Antwortformat

**Erfolgreiche Antwort (202 Accepted):**

```json theme={null}
{
  "ingested": 2,
  "failed": 0,
  "errors": []
}
```

**Antwort mit Fehlern:**

```json theme={null}
{
  "ingested": 1,
  "failed": 1,
  "errors": [
    {
      "index": 1,
      "transactionId": "tx-12346",
      "error": "Invalid customer ID"
    }
  ]
}
```

**HTTP Status Codes:**

| Code  | Bedeutung                                                  |
| ----- | ---------------------------------------------------------- |
| `202` | Events wurden akzeptiert (kann teilweise Fehler enthalten) |
| `400` | Ungültige Anfrage - Validierungsfehler                     |
| `401` | Nicht autorisiert - Ungültiger API-Schlüssel               |

## Event-Struktur

### Erforderliche Felder

Jedes Nutzungsereignis muss folgende Felder enthalten:

```typescript theme={null}
{
  transactionId: string;    // Eindeutige ID für Idempotenz
  eventName: string;         // Name des Events
  timestamp: string;         // ISO 8601 Zeitstempel
  customerId: string;        // Fynn-UUID oder externalId des Kunden
  properties: object;        // Beliebige Event-Eigenschaften
}
```

### Idempotenz

Events mit derselben `transactionId` werden nur einmal verarbeitet. Bei wiederholtem Senden wird das bereits existierende Event zurückgegeben (HTTP 200 statt 201).

<Tip>
  Verwende eindeutige, deterministische Transaction IDs. Beispiel: UUID oder `${customerId}-${timestamp}-${eventName}`
</Tip>

### Properties

Die `properties` können beliebige JSON-Objekte enthalten. Typische Beispiele:

**API Call Event:**

```json theme={null}
{
  "endpoint": "/api/v1/users",
  "method": "GET",
  "response_time_ms": 145,
  "status_code": 200
}
```

**Storage Event:**

```json theme={null}
{
  "bytes": 1048576,
  "storage_type": "database",
  "region": "eu-central-1"
}
```

**Transaction Event:**

```json theme={null}
{
  "amount": 99.99,
  "currency": "EUR",
  "transaction_type": "purchase"
}
```

## Best Practices

### Timestamps

Verwende immer UTC-Zeitstempel im ISO 8601 Format.

### Batch-Größe

Für optimale Performance:

* **Kleine Batches**: 10-100 Events für Echtzeit-Erfassung
* **Große Batches**: 500-1000 Events für Bulk-Import
* **Vermeide**: Sehr kleine Batches (\< 10) bei hohem Volumen

### Rate Limiting

Respektiere Rate Limits:

* **Empfohlen**: Maximal 10 Requests pro Sekunde
* **Burst**: Kurzzeitig bis zu 50 Requests pro Sekunde
* **Vermeide**: Längerfristige Überschreitung der Limits

## Fehlerbehebung

### CSV Import schlägt fehl

**Problem:** "Ungültiges CSV-Format"

**Lösung:**

1. Prüfe, ob alle erforderlichen Spalten vorhanden sind
2. Stelle sicher, dass die Datei UTF-8 kodiert ist
3. Validiere JSON in der `properties`-Spalte
4. Prüfe, ob Anführungszeichen korrekt escaped sind

**Problem:** "Datei zu groß"

**Lösung:**

* Teile die CSV-Datei in kleinere Dateien auf (max. 10 MB)
* Importiere die Dateien nacheinander

### API Import Fehler

**Problem:** `401 Unauthorized`

**Lösung:**

* Prüfe, ob der API-Schlüssel korrekt im Header übergeben wird
* Stelle sicher, dass der API-Schlüssel aktiv ist
* Prüfe die Berechtigungen des API-Schlüssels

**Problem:** `400 Bad Request`

**Lösung:**

* Validiere die Event-Struktur
* Prüfe, ob alle erforderlichen Felder vorhanden sind
* Stelle sicher, dass `customerId` eine gültige UUID oder `externalId` ist
* Prüfe das `timestamp`-Format (ISO 8601)

**Problem:** Events werden nicht angezeigt

**Lösung:**

1. Prüfe die Antwort auf Fehler (`errors` Array)
2. Validiere `transactionId` (möglicherweise Duplikat)
3. Prüfe Filter in der Events-Tabelle
4. Warte kurz, da Events asynchron verarbeitet werden

## Verwandte Dokumentation

* [Abrechenbare Einheiten verwalten](/guide/catalogue/measurements/introduction)
* [Nutzungsbasierte Abrechnung](/guide/subscriptions/introduction)
* [API Referenz - Nutzungsereignisse](/api-reference/usage-events)


# Checkout Link
Source: https://docs.fynn.eu/guide/checkout/checkout-links

Lerne wie du einen Checkout Link erstellst und an deine Kunden sendest.

Mit einem Checkout Link kannst du einen vorkonfigurierten Warenkorb für ein Produkt erstellen und an deine Kunden senden. Der Kunde kann dann direkt zur Kasse gehen und den Kauf abschließen.

## Checkout Link erstellen

<Steps>
  <Step title="Produkt auswählen">
    Wähle das Produkt in deinem Produkt-Katalog aus, <a href="/guide/catalogue/prices/introduction">erstelle einen Preis</a> wenn noch nicht geschehen,
    und klicke auf den Button "Checkout Link erstellen".
  </Step>

  <Step title="Nach Bestellabschluss einrichten">
    Wähle unter "Nach Abschluss" eines der Optionen aus, um festzulegen, was nach dem Kauf passieren soll.

    <Frame>
      <img alt="Nach Bestellabschluss einrichten" />
    </Frame>

    * **Standard-Bestätigungsseite**: Der Kunde wird auf die Standard-Bestätigungsseite weitergeleitet, und erhält eine Übersicht über seine Bestellung und die dazugehörige Rechnung.
    * **Benutzerdefinierte Weiterleitung**: Der Kunde wird auf eine von dir festgelegte URL weitergeleitet.
    * **Benutzerdefinierte Bestätigungsnachricht**: Der Kunde wird auf die Standard-Bestätigungsseite weitergeleitet, und erhält eine von dir festgelegte Bestätigungsnachricht angezeigt.

    <Tip>
      Bei der Verwendung einer **benutzerdefinierten Weiterleitung** kannst du die URL mit Platzhaltern versehen, die durch URL Parameter ersetzt werden. Weiteres findest du unter [Metadaten hinzufügen](#metadaten-hinzufuegen).
    </Tip>

    **Zurück zum Anbieter-Button anzeigen**: Aktiviere diese Option, wenn du möchtest, dass der Kunde nach dem Kauf auf der Standard-Bestätigungsseite einen Button sieht, um zurück zu deinem Anbieter zu gelangen.
  </Step>
</Steps>

### Rabattcodes erlauben

Unter "Weitere Optionen" kannst du festlegen, ob der Kunde einen Rabattcode eingeben kann.
Aktiviere diese Option, wenn du möchtest, dass der Kunde einen Rabattcode eingeben kann. Andernfalls wird das Feld ausgeblendet.

### Testzeitraum festlegen

Unter "Weitere Optionen" kannst du für wiederkehrende Produkte festlegen, ob ein Testzeitraum für das Produkt gelten soll.

Aktiviere diese Option, wenn du möchtest, dass der Kunde das Produkt vor dem Kauf testen kann. Der Betrag wird erst nach Ablauf des Testzeitraums fällig.

<Warning>
  Wenn im Preis der Testzeitraum über <a href="http://localhost:3000/guide/catalogue/prices/introduction#testphasen">Testphase erlauben</a> ausgeschlossen ist, wird diese Option ignoriert.
</Warning>

### Laufzeiten festlegen

Unter "Weitere Optionen" kannst du für wiederkehrende Produkte festlegen, welche Vertrags- & Kündigungszeiträume für das Produkt gelten.
Die Laufzeiten werden anschließend in das Abonnement überführt.

Für einmalige Produkte ist diese Option ohne Bedeutung.

<Info>
  Solltest du keine Laufzeiten festlegen, wird als Vertragslaufzeit die Abrechnungsperiode verwendet und als Kündigungsfrist 1 Tag.
</Info>

### Unternehmensangabe erzwingen

Unter "Weitere Optionen" kannst du festlegen, ob der Kunde verpflichtet ist, eine Unternehmensangabe zu machen.
So kannst du sicherstellen, dass du nur an Unternehmen verkaufst.

Hierfür aktiviere die Option "Unternehmensangabe erzwingen".

### Menge veränderbar machen

Unter "Weitere Optionen" kannst du festlegen, ob der Kunde die Menge des Produkts im Warenkorb nachträglich verändern kann.

Aktiviere diese Option, indem du die Checkbox "Menge veränderbar" aktivierst. Hiermit kann ein Produkt nicht aus dem Warenkorb entfernt werden, sondern nur die Menge verändert werden.

## Metadaten hinzufügen

Du kannst Metadaten an den Checkout Link anhängen, um zusätzliche Informationen zu übergeben.

Diese Metadaten werden:

* als Weiterleitungsparameter an die benutzerdefinierte Weiterleitung angehängt
* als Platzhalter in der benutzerdefinierten Weiterleitung ersetzt
* im Webhook als `metadata`-Feld übergeben

### Metadaten anhängen

Um Metadaten an den Checkout Link anzuhängen, füge sie als URL-Parameter hinzu, z.B. `https://fynn.coreapi.io/checkout-link/xxxxxxxx?metadata[key]=value&metadata[key2]=value2`.

Es ist zudem möglich ein mehrdimensionales Array zu übergeben, indem du den Schlüssel mit eckigen Klammern umschließt, z.B. `metadata[key][subkey]=value`.

### Platzhalter in der benutzerdefinierten Weiterleitung

Du kannst Platzhalter in der benutzerdefinierten Weiterleitung verwenden, die durch Metadaten ersetzt werden.
Um ein angegebenes Metadatum in der benutzerdefinierten Weiterleitung zu verwenden, füge es in geschweiften Klammern hinzu, z.B. `{{metadataKey}}`.

<Tip>
  Wenn du eine Mandanten-fähige Anwendung betreibst, und bspw. bei Weiterleitung auf eine benutzerdefinierte URL des Mandanten weiterleiten möchtest,
  kannst du die Mandanten-ID als Metadatum an den Checkout Link anhängen und als Platzhalter in der benutzerdefinierten Weiterleitung verwenden.

  Beispiel URL: `https://{{mandantId}}.example.com/checkout-success`

  Beispiel Checkout-URL: `https://fynn.coreapi.io/checkout-link/xxxxxx?metadata[mandantId]=acmegmbh`
</Tip>

### Webhooks

Die Metadaten werden im Webhook als `metadata`-Feld übergeben.

```json theme={null}
{
    "metadata": {
        "key": "value",
        "key2": "value2"
    }
}
```

## Checkout Session erstellen

Standardmäßig wird bei Verwendung des Checkout Links eine neue Checkout Session erstellt.
Es kann jedoch sinnvoll sein, dass nur eine Checkout Session erstellt wird, wenn du:

* mehrere Produkte in einem Warenkorb bündeln möchtest
* den Checkout Link mehrfach verwenden möchtest

Um eine Checkout Session zu erstellen, füge den Parameter `session=true` hinzu, z.B. `https://my-tenant.coreapi.io/checkout-link/xxxxxxxx?session=true`.

<Tip>
  Wenn eine Checkout Session erstellt wurde und ein Checkout Link ohne `session=true` aufgerufen wird, wird eine einmalige unabhängige Checkout Session erstellt.
</Tip>

<Tip>
  Die Checkout Session ist 24 Stunden gültig. Nach Ablauf dieser Zeit wird der Warenkorb geleert.
</Tip>

### Checkout Session abrufen

Um die Checkout Session abzurufen, ohne ein weiteres Produkt hinzuzufügen, rufe folgende
API-Route auf: `https://[tenant-username].coreapi.io/public/checkout/cart/current`. Ersetze `[tenant-username]` durch deinen Tenant-Namen.

Anschließend wird zur aktuellen Checkout Session weitergeleitet.


# Provisionen & Rückforderungen
Source: https://docs.fynn.eu/guide/commissions/earnings

Provisionen nachverfolgen, genehmigen und Rückforderungen bei Stornierungen verstehen.

## Übersicht

Provisionen werden automatisch berechnet, wenn eine Rechnung finalisiert oder bezahlt wird, je nach Konfiguration des [Provisionsplans](/guide/commissions/plans). Jede Provision ist einer konkreten Rechnungsposition zugeordnet und enthält den vollständigen Berechnungskontext.

<Frame>
  <img alt="Provisionsübersicht" />
</Frame>

***

## Provisions-Status

| Status               | Bedeutung                                                    | Nächste Aktion             |
| -------------------- | ------------------------------------------------------------ | -------------------------- |
| **Offen**            | Provision wurde berechnet, wartet auf Prüfung                | Genehmigen oder Stornieren |
| **Genehmigt**        | Provision wurde geprüft und freigegeben                      | In Auszahlung aufnehmen    |
| **Ausgezahlt**       | Provision wurde in einer Auszahlung berücksichtigt           | Abgeschlossen              |
| **Storniert**        | Provision wurde manuell oder durch Rückforderung storniert   | Abgeschlossen              |
| **Nicht berechtigt** | Provision konnte nicht berechnet werden (Berechtigung fehlt) | Grund prüfen               |

### Nicht berechtigt: Gründe

Wenn eine Provision den Status "Nicht berechtigt" erhält, liegt einer der folgenden Gründe vor:

| Grund                              | Beschreibung                                                                            |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| **Auslöser stimmt nicht überein**  | Die Rechnung wurde finalisiert, aber der Plan erwartet Zahlungseingang (oder umgekehrt) |
| **Kein Deal verknüpft**            | Der Plan erfordert einen HubSpot-Deal, aber die Rechnung hat keinen                     |
| **Außerhalb des Geltungsbereichs** | Die Rechnung liegt außerhalb des ersten Vertragszeitraums                               |
| **Plan inaktiv**                   | Der Provisionsplan ist deaktiviert                                                      |
| **Kunde ausgeschlossen**           | Der Kunde ist auf der Ausschlussliste                                                   |

***

## Provisionen prüfen und genehmigen

<Steps>
  <Step title="Provisionen öffnen">
    Navigiere zu **Provisionen > Provisionen**. Nutze die Filter, um nach Zeitraum, Mitarbeiter oder Status zu filtern.
  </Step>

  <Step title="Details prüfen">
    Klicke auf eine Provision, um den vollständigen Kontext zu sehen:

    <Frame>
      <img alt="Provisions-Detail" />
    </Frame>

    * Rechnungsnummer und -position
    * Kunde und Kundennummer
    * Provisionssatz und Berechnungsbasis
    * Abonnement und Vertragszeitraum
    * Verknüpfter HubSpot-Deal (falls vorhanden)
  </Step>

  <Step title="Genehmigen oder Stornieren">
    Wähle eine oder mehrere Provisionen per Mehrfach-Auswahl aus:

    * **Freigeben**: Provision wird für die Auszahlung freigegeben
    * **Stornieren**: Provision wird mit Begründung storniert
  </Step>
</Steps>

<Tip>
  Nutze die Gruppierung nach **Vertriebsmitarbeiter**, **Kunde**, **Rechnung** oder **Deal**, um Provisionen effizient zu prüfen.
</Tip>

***

## Rückforderungen (Clawbacks)

Wenn eine Rechnung storniert oder gutgeschrieben wird, erstellt Fynn automatisch eine Rückforderung. Es wird kein manueller Eingriff benötigt.

### Wie Rückforderungen funktionieren

```
Rechnung #2024-001 erstellt
  └── Provision: +150,00 € (Original)

Rechnung #2024-001 vollständig storniert
  └── Rückforderung: -150,00 € (Clawback)

═══════════════════════════════
Effektive Provision: 0,00 €
```

### Teilweise Gutschriften

Bei anteiligen Gutschriften wird die Rückforderung proportional berechnet:

```
Rechnung #2024-002 über 1.000,00 € netto
  └── Provision: 100,00 € (10 %)

Teilgutschrift über 400,00 € netto
  └── Rückforderung: -40,00 € (10 % von 400 €)

═══════════════════════════════
Effektive Provision: 60,00 €
```

### Rückforderung bei bereits ausgezahlten Provisionen

Wurde die Provision bereits ausgezahlt, wird eine negative Rückforderung erstellt. Diese wird mit der nächsten Auszahlung verrechnet.

<Info>
  Rückforderungen erscheinen als eigener Typ "Rückforderung" in der Provisionsübersicht und sind klar von regulären Provisionen unterscheidbar.
</Info>

***

## Provisions-Typen

| Typ               | Beschreibung                                             |
| ----------------- | -------------------------------------------------------- |
| **Original**      | Reguläre Provision aus einer Rechnung                    |
| **Rückforderung** | Automatische Korrektur bei Stornierung oder Gutschrift   |
| **Nachbuchung**   | Manuell erstellte Korrektur (z.B. für externe Dokumente) |


# Excel-Exporte
Source: https://docs.fynn.eu/guide/commissions/exports

Provisionen, Auszahlungen und Deal-Daten als Excel-Dateien exportieren.

## Übersicht

Fynn bietet drei verschiedene Excel-Exporte für Provisionen. Alle Exporte werden als XLSX-Datei heruntergeladen und enthalten mehrere Tabellenblätter mit strukturierten Daten.

| Export                  | Wo zu finden                                | Tabellenblätter |
| ----------------------- | ------------------------------------------- | --------------- |
| **Einzelne Auszahlung** | Auszahlungsdetail > **Excel exportieren**   | 2 Blätter       |
| **Alle Auszahlungen**   | Auszahlungsübersicht > **Alle exportieren** | 2 Blätter       |
| **Deal-Provisionen**    | Provisionen > Deals > **Excel exportieren** | 3 Blätter       |

***

## Einzelne Auszahlung exportieren

Öffne eine Auszahlung und klicke auf **Excel exportieren**. Die Datei enthält zwei Tabellenblätter:

### Blatt 1: Zusammenfassung

| Spalte             | Beschreibung                      |
| ------------------ | --------------------------------- |
| Auszahlung-ID      | Eindeutige Kennung                |
| Vertriebler        | Name des Vertriebsmitarbeiters    |
| E-Mail             | E-Mail-Adresse des Mitarbeiters   |
| Status             | Entwurf, Freigegeben oder Bezahlt |
| Betrag             | Gesamtbetrag der Auszahlung       |
| Anzahl Provisionen | Anzahl enthaltener Provisionen    |
| Notiz              | Optionale Notiz aus der Freigabe  |
| Erstellt am        | Datum der Erstellung              |
| Genehmigt am       | Datum der Freigabe                |
| Ausgezahlt am      | Datum der Zahlung                 |

### Blatt 2: Provisionen

| Spalte             | Beschreibung                             |
| ------------------ | ---------------------------------------- |
| Kunde              | Kundenname                               |
| Rechnungsnummer    | Zugehörige Rechnungsnummer               |
| Rechnungsdatum     | Datum der Rechnung                       |
| Basisbetrag        | Netto- oder Bruttobetrag (je nach Plan)  |
| Provisionssatz (%) | Angewendeter Prozentsatz                 |
| Provisionsbetrag   | Berechneter Provisionsbetrag             |
| Typ                | Original, Rückforderung oder Nachbuchung |
| Berechnet am       | Zeitpunkt der Berechnung                 |

***

## Alle Auszahlungen exportieren

In der Auszahlungsübersicht klicke auf **Alle exportieren**. Diese Datei enthält zwei Blätter mit allen Auszahlungen und deren Provisionen.

### Blatt 1: Auszahlungen

Alle Felder aus der Einzelauszahlung, erweitert um:

| Spalte                | Beschreibung               |
| --------------------- | -------------------------- |
| Währung               | Währung der Auszahlung     |
| Ziel-Auszahlungsdatum | Geplantes Auszahlungsdatum |

### Blatt 2: Provisionen

Alle Provisionen aller Auszahlungen, erweitert um:

| Spalte        | Beschreibung                        |
| ------------- | ----------------------------------- |
| Auszahlung-ID | Zuordnung zur Auszahlung            |
| Vertriebler   | Name des Vertriebsmitarbeiters      |
| Deal          | Name des verknüpften HubSpot-Deals  |
| HubSpot-Link  | Direktlink zum Deal in HubSpot      |
| Kundennummer  | Kundennummer des zugehörigen Kunden |
| Währung       | Währung der Provision               |

***

## Deal-Provisionen exportieren

Unter **Provisionen > Deals** klicke auf **Excel exportieren**. Die Datei enthält drei Blätter und verknüpft Deal-Daten mit Rechnungspositionen und Provisionen.

<Tip>
  Der Deal-Export kann nach Vertriebsmitarbeiter, Deal-Phase und Suchbegriff gefiltert werden. Die Filter werden auf den Export angewendet.
</Tip>

### Blatt 1: Deals

| Spalte                       | Beschreibung                        |
| ---------------------------- | ----------------------------------- |
| Deal-ID                      | HubSpot Deal-Kennung                |
| Deal                         | Deal-Name                           |
| Kunde                        | Zugeordneter Kundenname             |
| Kundennummer                 | Kundennummer                        |
| Phase                        | Open, Won oder Lost                 |
| Inhaber                      | Deal-Inhaber (Vertriebsmitarbeiter) |
| TCV (Netto)                  | Total Contract Value                |
| Fakturiert (Netto)           | Bereits fakturierter Nettobetrag    |
| Fakturiert (Brutto)          | Bereits fakturierter Bruttobetrag   |
| Noch zu fakturieren          | Offener Betrag                      |
| Fakturierungsfortschritt (%) | Prozentualer Fortschritt            |
| Abschlussdatum               | Datum des Deal-Abschlusses          |

### Blatt 2: Rechnungspositionen

| Spalte          | Beschreibung                |
| --------------- | --------------------------- |
| Deal            | Deal-Name                   |
| Abo-Nummer      | Zugehörige Abonnementnummer |
| Abo-Name        | Name des Abonnements        |
| Rechnungsnummer | Rechnungsnummer             |
| Rechnungsstatus | Status der Rechnung         |
| Rechnungsdatum  | Datum der Rechnung          |
| Produkt         | Produktbezeichnung          |
| Netto           | Nettobetrag der Position    |
| Brutto          | Bruttobetrag der Position   |
| Währung         | Währung                     |

### Blatt 3: Provisionen

| Spalte             | Beschreibung                             |
| ------------------ | ---------------------------------------- |
| Deal               | Deal-Name                                |
| Vertriebler        | Name des Vertriebsmitarbeiters           |
| E-Mail             | E-Mail-Adresse des Mitarbeiters          |
| Kunde              | Kundenname                               |
| Rechnungsnummer    | Zugehörige Rechnungsnummer               |
| Rechnungsdatum     | Datum der Rechnung                       |
| Basisbetrag        | Berechnungsgrundlage                     |
| Provisionssatz (%) | Angewendeter Prozentsatz                 |
| Provisionsbetrag   | Berechneter Provisionsbetrag             |
| Währung            | Währung                                  |
| Typ                | Original, Rückforderung oder Nachbuchung |
| Status             | Status der Provision                     |
| Berechnet am       | Zeitpunkt der Berechnung                 |

***

## Geplante Exporte

<Info>
  DATEV LODAS und Personio Exporte sind in Planung und werden in einem zukünftigen Update verfügbar sein.
</Info>


# Provisionen
Source: https://docs.fynn.eu/guide/commissions/introduction

Vertriebsprovisionen automatisch berechnen, nachverfolgen und auszahlen, direkt aus deinen Rechnungsdaten.

## Warum Provisionen in Fynn?

Vertriebsprovisionen werden häufig in Excel-Tabellen berechnet: manuell, fehleranfällig und ohne Verbindung zu den tatsächlichen Rechnungsdaten. Das führt zu Streitigkeiten, verspäteten Auszahlungen und einem Kontrollverlust über die Vertriebskosten.

Fynn berechnet Provisionen automatisch auf Basis deiner Rechnungen. Jede Buchung ist nachvollziehbar, Rückforderungen bei Stornierungen werden automatisch erstellt und Auszahlungen lassen sich als Excel-Datei exportieren.

<CardGroup>
  <Card title="Automatische Berechnung" icon="calculator">
    Provisionen werden bei Rechnungsstellung oder Zahlungseingang berechnet, ohne manuellen Aufwand.
  </Card>

  <Card title="Rückforderungen inklusive" icon="rotate-left">
    Bei Stornierungen oder Gutschriften werden Provisionen automatisch anteilig zurückgefordert.
  </Card>

  <Card title="Excel-Exporte" icon="file-export">
    Auszahlungen und Deal-Provisionen als detaillierte Excel-Dateien exportieren. DATEV LODAS und Personio in Planung.
  </Card>
</CardGroup>

***

## Typische Anwendungsfälle

<AccordionGroup>
  <Accordion title="Vertriebsteam mit festen Provisionsraten">
    Dein Vertriebsteam erhält eine feste Provision pro abgeschlossenem Kunden, z.B. 10 % auf den Nettoumsatz aller Rechnungen. Jeder Vertriebsmitarbeiter ist einem oder mehreren Kunden zugeordnet.

    **So setzt du es um:**

    * Erstelle einen Provisionsplan mit 10 % auf Nettobasis
    * Lege Vertriebsmitarbeiter an und weise ihnen Kunden zu
    * Provisionen werden automatisch bei jeder Rechnung berechnet
  </Accordion>

  <Accordion title="Provision nur auf den ersten Vertragszeitraum">
    Vertrieb wird nur für die initiale Kundengewinnung vergütet, nicht für Verlängerungen. Die Provision wird nur auf Rechnungen im ersten Vertragszeitraum berechnet.

    **So setzt du es um:**

    * Provisionsplan mit Scope "Nur erster Vertragszeitraum" erstellen
    * Rechnungen nach Ablauf der ersten Vertragsperiode generieren keine Provision mehr
  </Accordion>

  <Accordion title="Unterschiedliche Sätze pro Produkt">
    Nicht jedes Produkt hat die gleiche Marge. Premium-Produkte erhalten eine höhere Provision, Einstiegsprodukte eine niedrigere.

    **So setzt du es um:**

    * Provisionsplan mit Basisprozentsatz anlegen (z.B. 5 %)
    * Produktregeln hinzufügen, die den Satz pro Produkt überschreiben (z.B. 15 % für "Enterprise Plan")
  </Accordion>

  <Accordion title="Provision nur bei abgeschlossenem Deal (CRM)">
    Provisionen sollen nur gezahlt werden, wenn der Kunde über einen HubSpot-Deal gewonnen wurde, nicht für Bestandskunden oder organische Anmeldungen.

    **So setzt du es um:**

    * "Deal erforderlich" im Provisionsplan aktivieren
    * Nur Rechnungen mit verknüpftem HubSpot-Deal generieren Provisionen
  </Accordion>

  <Accordion title="Partnerprovisionen und Reseller">
    Externe Partner oder Reseller erhalten Provisionen auf vermittelte Kunden. Auszahlungen erfolgen erst ab einem Mindestbetrag je Vertriebsmitarbeiter.

    **So setzt du es um:**

    * Partner als Vertriebsmitarbeiter anlegen
    * Mindestauszahlung oder Mindestumsatz pro Monat im Plan definieren (z.B. 50 € Mindestauszahlung je Vertriebsmitarbeiter)
    * Auszahlungen monatlich prüfen und freigeben
  </Accordion>
</AccordionGroup>

***

## So funktioniert es

<Steps>
  <Step title="Provisionsplan erstellen" icon="clipboard-list">
    Definiere Prozentsatz, Berechnungsbasis (Netto/Brutto), Auslöser und Geltungsbereich. Optional: Produktregeln mit abweichenden Sätzen.
  </Step>

  <Step title="Vertriebsmitarbeiter anlegen" icon="user-plus">
    Manuell anlegen oder aus HubSpot / Xentral importieren. Jedem Mitarbeiter wird ein Standard-Provisionsplan zugewiesen.
  </Step>

  <Step title="Kunden zuweisen" icon="users">
    Kunden einzeln oder per Mehrfach-Auswahl einem Vertriebsmitarbeiter zuordnen. Optional mit abweichendem Plan pro Zuweisung.
  </Step>

  <Step title="Automatische Berechnung" icon="calculator">
    Bei Rechnungsstellung oder Zahlungseingang wird die Provision automatisch berechnet. Bei Stornierungen erfolgt die Rückforderung automatisch.
  </Step>

  <Step title="Prüfen und Freigeben" icon="check-double">
    Offene Provisionen einzeln oder per Mehrfach-Auswahl prüfen und freigeben.
  </Step>

  <Step title="Auszahlung erstellen und exportieren" icon="file-export">
    Freigegebene Provisionen nach Monat und Mitarbeiter gruppiert in eine Auszahlung bündeln. Als Excel-Datei mit Zusammenfassung und Einzelpositionen exportieren.
  </Step>
</Steps>

***

## Vorteile gegenüber manueller Berechnung

| Aspekt          | Manuell (Excel)           | Fynn Provisionen                                  |
| --------------- | ------------------------- | ------------------------------------------------- |
| Berechnung      | Manuell pro Rechnung      | Automatisch bei Rechnungsstellung                 |
| Stornierungen   | Manuelle Korrektur nötig  | Automatische Rückforderung                        |
| Transparenz     | Keine Nachvollziehbarkeit | Jede Provision mit Rechnungs- und Kundenbezug     |
| Auszahlung      | Manuelle Überweisung      | Strukturierter Excel-Export mit Freigabe-Workflow |
| Produktregeln   | Komplexe IF-Formeln       | Regelkonfiguration pro Produkt im Plan            |
| CRM-Verknüpfung | Nicht vorhanden           | Automatische HubSpot-Deal-Zuordnung               |
| Audit-Trail     | Keine Historie            | Vollständige Änderungshistorie pro Provision      |

***

## Erste Schritte

<Steps>
  <Step title="Provisionssystem aktivieren">
    Kontaktiere uns, um das Provisionssystem für deine Organisation freizuschalten.
  </Step>

  <Step title="Einrichtungsassistent starten">
    Nach der Aktivierung findest du unter **Provisionen** den Einrichtungsassistenten, der dich in 5 Schritten durch die Konfiguration führt.

    <Frame>
      <img alt="Einrichtungsassistent" />
    </Frame>
  </Step>

  <Step title="Loslegen">
    Nach der Einrichtung werden Provisionen automatisch bei jeder neuen Rechnung berechnet.
    Folge den weiteren Anleitungen für Details zu [Provisionsplänen](/guide/commissions/plans), [Vertriebsmitarbeitern](/guide/commissions/sales-reps) und [Auszahlungen](/guide/commissions/payouts).
  </Step>
</Steps>


# Auszahlungen
Source: https://docs.fynn.eu/guide/commissions/payouts

Genehmigte Provisionen in Auszahlungen bündeln, freigeben und als Excel exportieren.

## Übersicht

Auszahlungen bündeln genehmigte Provisionen pro Vertriebsmitarbeiter und Monat. Nach der Freigabe können sie als Excel-Datei exportiert werden.

<Frame>
  <img alt="Auszahlungsübersicht" />
</Frame>

***

## Auszahlung erstellen

<Steps>
  <Step title="Auszahlungen öffnen">
    Navigiere zu **Provisionen > Auszahlungen** und klicke auf **Auszahlung erstellen**.
  </Step>

  <Step title="Zeitraum und Mitarbeiter wählen">
    <Frame>
      <img alt="Auszahlung erstellen" />
    </Frame>

    Wähle die Monate und Vertriebsmitarbeiter aus, für die eine Auszahlung erstellt werden soll. Das System zeigt die Summe der genehmigten Provisionen pro Auswahl.
  </Step>

  <Step title="Auszahlung wird erstellt">
    Die Auszahlung wird als **Entwurf** erstellt. Alle enthaltenen Provisionen werden mit der Auszahlung verknüpft.
  </Step>
</Steps>

<Info>
  Nur **genehmigte** Provisionen werden in eine Auszahlung aufgenommen. Offene oder stornierte Provisionen bleiben unberücksichtigt.
</Info>

***

## Auszahlungsschwellen

Im [Provisionsplan](/guide/commissions/plans) kannst du zwei monatliche Grenzen je Vertriebsmitarbeiter setzen. Beide gelten pro Plan und Kalendermonat, immer über alle Kunden eines Vertriebsmitarbeiters zusammen.

**Mindestauszahlung pro Vertriebsmitarbeiter**

Provisionen werden erst in eine Auszahlung aufgenommen, wenn die Provisionssumme eines Vertriebsmitarbeiters im Monat diese Grenze erreicht.

* Mindestauszahlung: 50 € Provision
* Vertriebsmitarbeiter A: 75 € Provision im Monat → wird aufgenommen
* Vertriebsmitarbeiter B: 30 € Provision im Monat → bleibt zurückgehalten

**Mindestumsatz pro Monat**

Erreicht ein Vertriebsmitarbeiter den festgelegten Umsatz im Monat nicht, wird für diesen Monat keine Provision ausgezahlt. Wird die Grenze erreicht, wird der komplette Umsatz provisioniert. So belohnst du das Erreichen von Monatszielen.

* Mindestumsatz: 1.000 € Umsatz
* Vertriebsmitarbeiter A: 1.500 € Umsatz im Monat → alle Provisionen werden aufgenommen
* Vertriebsmitarbeiter B: 600 € Umsatz im Monat → keine Provision für den Monat

Sind beide Grenzen gesetzt, muss ein Monat beide erreichen, damit er ausgezahlt wird.

<Tip>
  Provisionen unterhalb einer Schwelle gehen nicht verloren. Sie bleiben im Status "Genehmigt" und werden aufgenommen, sobald die Grenze in einem zukünftigen Monat erreicht wird.
</Tip>

***

## Auszahlungs-Workflow

<Frame>
  <img alt="Auszahlung Detail" />
</Frame>

| Status          | Beschreibung                                          | Aktionen               |
| --------------- | ----------------------------------------------------- | ---------------------- |
| **Entwurf**     | Auszahlung wurde erstellt, kann noch angepasst werden | Freigeben oder Löschen |
| **Freigegeben** | Auszahlung wurde geprüft und zur Zahlung freigegeben  | Als bezahlt markieren  |
| **Bezahlt**     | Auszahlung wurde durchgeführt                         | Abgeschlossen          |

### Freigeben

<Steps>
  <Step title="Auszahlung prüfen">
    Öffne die Auszahlung und prüfe die enthaltenen Provisionen, Beträge und den Vertriebsmitarbeiter.
  </Step>

  <Step title="Freigeben">
    Klicke auf **Freigeben**. Optional kannst du ein Zieldatum und eine Notiz hinterlegen.

    Die Freigabe wird mit Zeitstempel und dem freigebenden Benutzer protokolliert.
  </Step>
</Steps>

### Als bezahlt markieren

Sobald die Auszahlung tatsächlich überwiesen wurde:

<Steps>
  <Step title="Als bezahlt markieren">
    Klicke auf **Als bezahlt markieren**. Alle enthaltenen Provisionen werden auf den Status "Ausgezahlt" gesetzt.
  </Step>
</Steps>

<Warning>
  Einmal als bezahlt markierte Auszahlungen können nicht rückgängig gemacht werden. Korrekturen erfolgen über Rückforderungen in der nächsten Auszahlung.
</Warning>

***

## Exporte

Auszahlungen und Provisionen können als Excel-Dateien exportiert werden. Alle verfügbaren Exporte mit den enthaltenen Spalten und Tabellenblättern findest du unter [Excel-Exporte](/guide/commissions/exports).


# Provisionspläne
Source: https://docs.fynn.eu/guide/commissions/plans

Provisionspläne definieren, wie Provisionen berechnet werden: flexible Sätze, Produktregeln und Geltungsbereiche.

## Übersicht

Ein Provisionsplan definiert die Berechnungslogik für Vertriebsprovisionen. Du kannst mehrere Pläne für unterschiedliche Vertriebsstrukturen erstellen, z.B. einen Plan für das Neukundengeschäft und einen für Bestandskunden.

<Frame>
  <img alt="Provisionsplan konfigurieren" />
</Frame>

***

## Plan erstellen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Pläne öffnen">
        Navigiere zu **Provisionen > Aktionen > Einstellungen > Pläne** und klicke auf **Neuer Plan**.
      </Step>

      <Step title="Grunddaten festlegen">
        Konfiguriere die Berechnungsparameter:

        | Parameter           | Beschreibung                                                                              |
        | ------------------- | ----------------------------------------------------------------------------------------- |
        | **Name**            | Bezeichnung des Plans (z.B. "Neukundenvertrieb 10 %")                                     |
        | **Prozentsatz**     | Basisprovision in Prozent (z.B. 10 %)                                                     |
        | **Basis**           | Berechnung auf **Netto** oder **Brutto**-Betrag der Rechnungspositionen                   |
        | **Auslöser**        | Wann die Provision berechnet wird: bei **Rechnungsstellung** oder bei **Zahlungseingang** |
        | **Geltungsbereich** | Für **alle Rechnungen** oder nur den **ersten Vertragszeitraum**                          |
      </Step>

      <Step title="Produktregeln hinzufügen (optional)">
        Über den Bereich **Produktregeln** kannst du den Provisionssatz pro Produkt überschreiben. Mehr dazu im Abschnitt [Produktregeln](#produktregeln).
      </Step>

      <Step title="Optionale Einstellungen">
        * **Deal erforderlich**: Nur Rechnungen mit verknüpftem HubSpot-Deal generieren Provisionen
        * **Mindestauszahlung pro Vertriebsmitarbeiter**: Erst ab dieser monatlichen Provisionssumme je Vertriebsmitarbeiter wird ausgezahlt. Bleibt die Summe darunter, wird der ganze Monat zurückgehalten
        * **Mindestumsatz pro Monat**: Erreicht ein Vertriebsmitarbeiter diesen Umsatz im Monat nicht, gibt es für den gesamten Monat keine Provision. Wird die Grenze erreicht, wird der komplette Umsatz provisioniert
      </Step>

      <Step title="Plan speichern">
        Der Plan ist sofort aktiv und wird bei neuen Rechnungen für zugewiesene Kunden angewendet.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    ```bash theme={null}
    POST /api/commissions/plans

    {
      "name": "Neukundenvertrieb 10 %",
      "percentage": 0.10,
      "basisType": "net",
      "triggerEvent": "invoice_finalized",
      "scope": "first_contract_period",
      "requireDeal": false,
      "payoutThresholdAmount": { "amount": 0, "currency": "EUR", "precision": 2 },
      "monthlyRevenueThreshold": { "amount": 0, "currency": "EUR", "precision": 2 },
      "rules": [
        {
          "externalProductReference": "enterprise-plan",
          "percentage": 0.20,
          "priority": 1
        }
      ]
    }
    ```
  </Tab>
</Tabs>

***

## Auslöser: Rechnungsstellung vs. Zahlungseingang

| Auslöser              | Wann berechnet                                | Empfohlen für                                             |
| --------------------- | --------------------------------------------- | --------------------------------------------------------- |
| **Rechnungsstellung** | Sobald die Rechnung finalisiert wird          | Schnelle Sichtbarkeit, wenn Zahlungsrisiko gering ist     |
| **Zahlungseingang**   | Sobald die Rechnung als bezahlt markiert wird | Konservativ: Provision erst bei tatsächlichem Geldeingang |

<Info>
  Der Auslöser bestimmt nur, **wann** die Provision berechnet wird. Die Auszahlung erfolgt in beiden Fällen erst nach manueller Freigabe.
</Info>

***

## Geltungsbereich

| Scope                       | Beschreibung                                                      | Anwendungsfall                                         |
| --------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
| **Alle Rechnungen**         | Provision auf jede Rechnung des zugewiesenen Kunden               | Laufende Vertriebsprovision (z.B. Reseller, Partner)   |
| **Erster Vertragszeitraum** | Provision nur auf Rechnungen innerhalb der ersten Vertragsperiode | Neukundenvergütung, keine Provision auf Verlängerungen |

<Tip>
  Der erste Vertragszeitraum wird automatisch aus dem Abonnement ermittelt. Rechnungen, deren Leistungszeitraum nach dem Ende der ersten Vertragsperiode liegt, generieren keine Provision.
</Tip>

***

## Produktregeln

Nicht jedes Produkt hat die gleiche Marge. Beim Erstellen oder Bearbeiten eines Plans kannst du Produktregeln definieren, die den Basisprozentsatz für bestimmte Produkte überschreiben.

### Beispiel

| Produkt            | Basisprovision | Produktregel | Effektiver Satz           |
| ------------------ | -------------- | ------------ | ------------------------- |
| Starter Plan       | 10 %           | -            | 10 %                      |
| Professional Plan  | 10 %           | 15 %         | **15 %**                  |
| Enterprise Plan    | 10 %           | 20 %         | **20 %**                  |
| Einrichtungsgebühr | 10 %           | 0 %          | **0 %** (keine Provision) |

Jede Regel enthält:

* **Externe Produktreferenz**: Kennung des Produkts (z.B. Produkt-ID oder externer Schlüssel)
* **Prozentsatz**: Abweichender Provisionssatz für dieses Produkt
* **Priorität**: Reihenfolge bei mehreren Regeln

<Info>
  Produktregeln werden anhand der Rechnungsposition ermittelt. Gibt es keine Regel für ein Produkt, greift der Basisprozentsatz des Plans.
</Info>

***

## Plan aktivieren und deaktivieren

Pläne können jederzeit aktiviert oder deaktiviert werden. Deaktivierte Pläne generieren keine neuen Provisionen, bestehende Provisionen bleiben erhalten.

***

## Mehrere Pläne

Du kannst beliebig viele Pläne erstellen. Ein Vertriebsmitarbeiter hat einen **Standard-Plan**, der bei Kundenzuweisungen automatisch verwendet wird. Bei individuellen Zuweisungen kann ein abweichender Plan gewählt werden.

```
Vertriebsmitarbeiter: Max Mustermann
├── Standard-Plan: "Neukundenvertrieb 10 %"
│
├── Kunde A → verwendet Standard-Plan (10 %)
├── Kunde B → verwendet Standard-Plan (10 %)
└── Kunde C → individueller Plan: "Partner Premium 15 %"
```


# Vertriebsmitarbeiter
Source: https://docs.fynn.eu/guide/commissions/sales-reps

Vertriebsmitarbeiter anlegen, Kunden zuweisen und Provisionen pro Mitarbeiter nachverfolgen.

## Übersicht

Vertriebsmitarbeiter sind die Empfänger von Provisionen. Jeder Mitarbeiter kann einem oder mehreren Kunden zugewiesen werden. Die Zuweisung bestimmt, für welche Rechnungen Provisionen berechnet werden.

<Frame>
  <img alt="Vertriebsmitarbeiter" />
</Frame>

***

## Vertriebsmitarbeiter anlegen

<Tabs>
  <Tab title="Manuell anlegen">
    <Steps>
      <Step title="Mitarbeiter erstellen">
        Navigiere zu **Provisionen > Aktionen > Einstellungen > Vertriebsmitarbeiter** und klicke auf **Neuer Mitarbeiter**.
      </Step>

      <Step title="Daten eingeben">
        * **Vorname und Nachname**
        * **E-Mail-Adresse**
        * **Standard-Provisionsplan**: wird bei Kundenzuweisungen als Standard verwendet
      </Step>

      <Step title="Speichern">
        Der Mitarbeiter kann nun Kunden zugewiesen werden.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Aus externem System importieren">
    Vertriebsmitarbeiter können direkt aus HubSpot oder Xentral importiert werden. Die Stammdaten (Name, E-Mail) werden automatisch übernommen.

    <Steps>
      <Step title="Import starten">
        Navigiere zu **Provisionen > Aktionen > Einstellungen > Vertriebsmitarbeiter** und klicke auf **Mitarbeiter importieren**.
      </Step>

      <Step title="System und Mitarbeiter auswählen">
        In der Liste werden alle verfügbaren Mitarbeiter aus HubSpot und Xentral angezeigt. Wähle den gewünschten Mitarbeiter aus.
      </Step>

      <Step title="Plan zuweisen und speichern">
        Weise einen Standard-Provisionsplan zu und speichere den Mitarbeiter.
      </Step>
    </Steps>

    <Info>
      Bei HubSpot-Importen wird der Mitarbeiter mit dem HubSpot-Benutzer verknüpft. Dadurch können Deals automatisch dem richtigen Vertriebsmitarbeiter zugeordnet werden.
    </Info>
  </Tab>
</Tabs>

***

## Kunden zuweisen

Die Kundenzuweisung verbindet einen Kunden mit einem Vertriebsmitarbeiter. Ab diesem Zeitpunkt werden Provisionen für alle neuen Rechnungen dieses Kunden berechnet.

<Frame>
  <img alt="Kundenzuweisung" />
</Frame>

### Einzeln zuweisen

<Steps>
  <Step title="Mitarbeiter öffnen">
    Navigiere zum Vertriebsmitarbeiter und öffne den Tab **Zuweisungen**.
  </Step>

  <Step title="Kunde zuweisen">
    Klicke auf **Kunde zuweisen** und suche den gewünschten Kunden.

    Optional kannst du einen abweichenden Provisionsplan für diese spezifische Zuweisung wählen.
  </Step>
</Steps>

### Mehrere Kunden gleichzeitig zuweisen

Für größere Vertriebsteams kannst du mehrere Kunden auf einmal verwalten:

* **Mehrfach zuweisen**: Mehrere Kunden auf einen Mitarbeiter zuweisen
* **Mehrfach übertragen**: Kunden von einem Mitarbeiter auf einen anderen übertragen
* **Mehrfach entziehen**: Zuweisungen für mehrere Kunden aufheben

<Warning>
  Wird eine Zuweisung aufgehoben, werden keine neuen Provisionen mehr berechnet. Bestehende offene Provisionen bleiben erhalten und können weiterhin genehmigt und ausgezahlt werden.
</Warning>

***

## Mitarbeiter-Detailansicht

Die Detailansicht zeigt eine Übersicht des Mitarbeiters mit Kennzahlen und Tabs:

<Frame>
  <img alt="Mitarbeiter-Detail" />
</Frame>

| Tab              | Inhalt                                                      |
| ---------------- | ----------------------------------------------------------- |
| **Übersicht**    | Offene, genehmigte und ausgezahlte Provisionen als Metriken |
| **Zuweisungen**  | Alle aktiven und inaktiven Kundenzuweisungen                |
| **Provisionen**  | Alle Provisionen des Mitarbeiters mit Status und Beträgen   |
| **Auszahlungen** | Alle Auszahlungen des Mitarbeiters                          |

***

## Mitarbeiter archivieren

Vertriebsmitarbeiter können archiviert werden, wenn sie nicht mehr aktiv sind. Archivierte Mitarbeiter:

* Erscheinen nicht mehr in der aktiven Mitarbeiterliste
* Generieren keine neuen Provisionen
* Behalten alle historischen Provisionen und Auszahlungen

<Tip>
  Vor dem Archivieren: Stelle sicher, dass alle offenen Provisionen genehmigt oder storniert und alle Auszahlungen abgeschlossen sind.
</Tip>

***

## Kundenausschlüsse

Bestimmte Kunden können global von der Provisionsberechnung ausgeschlossen werden, z.B. interne Testaccounts oder verbundene Unternehmen.

<Frame>
  <img alt="Kundenausschlüsse" />
</Frame>

Ausgeschlossene Kunden generieren keine Provisionen, unabhängig von der Zuweisung. Der Ausschluss wird mit Grund und Zeitstempel protokolliert.


# Kundenbereich
Source: https://docs.fynn.eu/guide/customers/customer-portal

Kundenbereich

Im Kundenbereich können Kunden eigenständig ihre Rechnungsadressen und Zahlungsmethoden verwalten, Abonnements einsehen, kündigen und Rechnungen herunterladen.

## Erreichbarkeit

Der Kundenbereich ist standardmäßig über die URL `[tenant-username].customerfront.app` erreichbar.

### Eigene Domain

Für den Kundenbereich und Warenkorb kann eine eigene Domain aufgeschaltet werden. Schreibe uns eine kurze E-Mail mit dem Wunsch an [hi@fynn.eu](mailto:hi@fynn.eu).

## Funktionsumfang

### Abonnements

Unter dem Bereich "Abonnements" können Kunden ihre aktiven Abonnements einsehen, kündigen und Kündigungen widerrufen.
Zudem sind Vertragsdetails wie Vertragsbeginn, Vertragsende und der nächste Rechnungsbetrag einsehbar.

<Frame>
  <img alt="Kundenbereich - Abonnements" />
</Frame>

## Rechnungsadressen

Unter dem Bereich "Rechnungsadresse" können Kunden eine Standard-Rechnungsadresse hinterlegen, die für alle zukünftigen Abonnements und Rechnungen verwendet wird.
Alternativ kann eine neue Rechnungsadresse hinterlegt werden.

<Frame>
  <img alt="Kundenbereich - Rechnungsadressen" />
</Frame>

## Lieferadressen

Wenn die Lieferadresse für deine Organisation aktiviert ist, können Kunden im Bereich "Adressen" zusätzlich eine eigene Lieferadresse hinterlegen und bearbeiten.
Ist noch keine eigene Lieferadresse gesetzt, wird die Standardadresse verwendet. Kunden können jederzeit eine neue Lieferadresse anlegen oder wieder auf die Standardadresse zurücksetzen.

<Info>
  Die Bearbeitung der Lieferadresse im Kundenbereich ist optional. Schreibe uns eine kurze E-Mail an [hi@fynn.eu](mailto:hi@fynn.eu), wenn du die Funktion freischalten möchtest.
</Info>

## Zahlungsmethoden

Unter dem Bereich "Zahlungsmethoden" können Kunden eine Standard-Zahlungsmethode hinterlegen, die für alle zukünftigen Abonnements und Rechnungen verwendet wird.
Alternativ kann eine neue Zahlungsmethode hinterlegt werden.

Sobald ein Kunde eine Standard-Zahlungsmethode setzt oder ändert, übernimmt Fynn sie automatisch für den bestehenden Vertrag: Aktive Abonnements werden auf die neue Methode umgestellt und offene Rechnungen werden automatisch darüber eingezogen. Der Kunde muss offene Rechnungen also nicht mehr selbst überweisen.

Rechnungen, für die bereits ein Einzug läuft, die Teil eines Zahlplans sind oder sich in der Mahnung befinden, bleiben unberührt.

<Frame>
  <img alt="Kundenbereich - Zahlungsmethoden" />
</Frame>

## Rechnungen

Unter dem Bereich "Rechnungen" können Kunden alle Rechnungen einsehen und herunterladen.
Läuft für eine Rechnung gerade ein automatischer Einzug per SEPA, PayPal oder Karte, ist sie mit dem Hinweis "Zahlung in Verarbeitung" gekennzeichnet.

<Frame>
  <img alt="Kundenbereich - Rechnungen" />
</Frame>

## Persönlicher Ansprechpartner

Unter dem Bereich "Persönlicher Ansprechpartner" können Kunden ihren persönlichen Ansprechpartner einsehen.
Dieser ist unter [Persönlicher Ansprechpartner hinterlegen](/guide/customers/introduction#persönlicher-ansprechpartner-hinterlegen) einstellbar.

<Frame>
  <img alt="Kundenbereich - Persönlicher Ansprechpartner" />
</Frame>

## Link zum Kundenbereich erstellen

Um Kunden authentifiziert in den Kundenbereich zu leiten, kann ein personalisierter Link erstellt werden.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Link erstellen">
        Klicke auf "Kunden" in der linken Navigation und wähle den Kunden aus, für den du einen authentifizierten Link erstellen möchtest.

        Klicke oben rechts auf die drei Punkte und wähle "Kundenbereich-Link erstellen" aus.
      </Step>

      <Step title="Link erfolgreich erstellt">
        Der Link wurde erfolgreich erstellt und wurde in die Zwischenablage kopiert. Du kannst den Link nun an den Kunden weiterleiten.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Um einen Link zum Kundenbereich zu erstellen, kann die API verwendet werden.

    ```bash theme={null}
    POST /customers/{customerId}/authenticate
    ```

    Als Antwort wird eine URL zurückgegeben, die den Kunden authentifiziert in den Kundenbereich leitet.
    Den Access- & Refresh-Token kannst du andernfalls für die API Authentifierung verwenden, um eigene Anfragen an die API zu stellen.

    ```json theme={null}
    {
        "data": {
            "customerAreaLink": "https://[tenant-username].customerfront.app/customer-area/login?token=abc",
            "accessToken": "eyxxxxxx",
            "refreshToken": "eyxxxxxx"
        }
    }
    ```

    [Zur API-Dokumentation](/api-reference/customer/authenticate-customer)
  </Tab>
</Tabs>

## Login-E-Mail an Kunden senden

Du kannst Kunden eine E-Mail mit einem Login-Link senden, über den sie direkt in ihren Kundenbereich gelangen – ohne Passwort oder Code eingeben zu müssen.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kunde auswählen">
        Klicke auf "Kunden" in der linken Navigation und wähle den Kunden aus.
      </Step>

      <Step title="Login-E-Mail senden">
        Klicke oben rechts auf die drei Punkte und wähle "Login-E-Mail senden" aus.

        Der Kunde erhält eine E-Mail mit einem Link, über den er sich direkt einloggen kann.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    ```bash theme={null}
    POST /customers/{customerId}/send-login-email
    ```

    Der Kunde erhält eine E-Mail mit einem Login-Link zum Kundenbereich.

    [Zur API-Dokumentation](/api-reference/customer/send-login-email)
  </Tab>
</Tabs>

<Tip>
  Diese Funktion ist besonders nützlich für Support-Anfragen oder um Kunden beim Zugang zu ihrem Kundenbereich zu helfen.
</Tip>

## Kundenbereich anpassen

Im Kundenbereich können einzelne Bereiche oder Funktionen angepasst werden. Hierzu gehören:

* Ansprechpartner anzeigen
* Rechnungen anzeigen
* Rechnungsadresse verwalten
* Zahlungsmethoden verwalten
* Abonnements einsehen
* Abonnements kündigen
* Verhalten bei Kündigung während Testphase

Die Einstellungen findest du unter "Einstellungen" > "Hosted Pages".

<Frame>
  <img alt="Kundenbereich - Anpassungen" />
</Frame>

### Verhalten bei Kündigung während Testphase

Wenn ein Kunde ein Abonnement während der Testphase kündigt, kann das Verhalten des Kündigungszeitpunktes festgelegt werden.

Folgende Optionen stehen zur Verfügung:

* **Abonnement zum Zeitpunkt der Kündigung beenden**: Das Abonnement wird sofort gekündigt, auch wenn die Testphase noch nicht abgelaufen ist.
* **Abonnement zum Ende der Testphase beenden**: Das Abonnement wird zum Ende der Testphase beendet, die Küdigung wird vorgemerkt.

<Tip>
  Die Einstellungen gelten für alle Kunden, die über den Kundenbereich kündigen.
</Tip>

<Info>
  Diese Einstellung ist für die Wallet nicht relevant, da bei Kündigung durch einen Mitarbeiter der Kündigungszeitpunkt manuell festgelegt wird.
</Info>

## Zahlungsmethode hinzufügen per Link

Um Kunden die Möglichkeit zu geben, eine Zahlungsmethode per Link hinzuzufügen, kann ein personalisierter Link erstellt und optional per E-Mail versendet werden.

Der Kunde kann anschließend auswählen, ob die Zahlungsmethode für bestehende und zukünftige Abonnements verwendet werden soll.
Zudem wird die Zahlungsmethode für offene Rechnungen verwendet, sofern die letzte Zahlung nicht erfolgreich war.

<Check>
  Die Zahlungsmethode wird automatisch als Standard-Zahlungsmethode hinterlegt.
</Check>

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Link erstellen">
        Klicke auf "Kunden" in der linken Navigation und wähle den Kunden aus, für den du einen Link erstellen möchtest.

        Klicke oben rechts auf die drei Punkte und wähle "Zahlungsmethode hinzufügen" aus.
        Wähle die Zahlungsmethoden aus, die der Kunde hinzufügen kann und ob eine E-Mail versendet werden soll.

        Klicke auf "Link erstellen".

        <Frame>
          <img alt="Zahlungsmethode hinzufügen" />
        </Frame>
      </Step>

      <Step title="Link erfolgreich erstellt">
        Der Link wurde erfolgreich erstellt und wurde in die Zwischenablage kopiert. Du kannst den Link nun an den Kunden weiterleiten.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Um einen Link zum Hinzufügen einer Zahlungsmethode zu erstellen, kann die API verwendet werden.

    ```bash theme={null}
    POST /payment-methods/link
    ```

    [Weitere Informationen zur API](/api-reference/paymentmethod/create-payment-method-link)
  </Tab>
</Tabs>


# E-Mail-Adressen verwalten
Source: https://docs.fynn.eu/guide/customers/email-management

Verwalte E-Mail-Adressen und lege fest, welche E-Mails für Rechnungen und Mahnungen verwendet werden.

## Übersicht

Jeder Kunde kann mehrere E-Mail-Adressen haben. Über die E-Mail-Zuordnung legst du fest, welche Adressen für welchen Zweck verwendet werden:

| Rolle                | Auswahl         | Verwendung                                                          |
| -------------------- | --------------- | ------------------------------------------------------------------- |
| **Primär-E-Mail**    | Einzelauswahl   | Standard-Kontakt-E-Mail (Zahlungsmethoden-Benachrichtigungen, etc.) |
| **Rechnungs-E-Mail** | Mehrfachauswahl | Empfänger für Rechnungen, Gutschriften und Finanzdokumente          |
| **Mahnwesen-E-Mail** | Mehrfachauswahl | Empfänger für Zahlungserinnerungen und Mahnungen                    |

<Frame>
  <img alt="E-Mail-Adressverwaltung" />
</Frame>

## E-Mail-Adressen zuordnen

<Steps>
  <Step title="Kundenstammdaten öffnen">
    Navigiere zum gewünschten Kunden und öffne den Reiter **Stammdaten**.

    Im Bereich **E-Mail-Adressen** findest du drei Dropdowns zur Zuordnung der Rollen.
  </Step>

  <Step title="Primär-E-Mail festlegen">
    Wähle im Dropdown **Primär-E-Mail** die Standard-Kontakt-E-Mail des Kunden aus.

    <Info>
      Es kann immer nur eine Primär-E-Mail festgelegt werden.
    </Info>
  </Step>

  <Step title="Rechnungs-E-Mail festlegen">
    Wähle im Dropdown **Rechnungs-E-Mail** eine oder mehrere E-Mail-Adressen aus, die Rechnungen erhalten sollen.

    Ausgewählte E-Mails werden als Chips im Dropdown angezeigt und können per Klick auf das ✕ entfernt werden.

    <Tip>
      Wenn keine Rechnungs-E-Mail gesetzt ist, wird automatisch die Primär-E-Mail verwendet.
    </Tip>
  </Step>

  <Step title="Mahnwesen-E-Mail festlegen">
    Wähle im Dropdown **Mahnwesen-E-Mail** eine oder mehrere E-Mail-Adressen aus, die Zahlungserinnerungen und Mahnungen erhalten sollen.

    <Tip>
      Wenn keine Mahnwesen-E-Mail gesetzt ist, werden Mahnungen an die Rechnungs-E-Mail gesendet.
      Ist auch keine Rechnungs-E-Mail gesetzt, wird die Primär-E-Mail verwendet.
    </Tip>
  </Step>
</Steps>

## E-Mail-Adresse hinzufügen

Neue E-Mail-Adressen können direkt aus jedem Dropdown hinzugefügt werden:

<Steps>
  <Step title="Dropdown öffnen">
    Öffne eines der drei E-Mail-Dropdowns (Primär, Rechnung oder Mahnwesen).
  </Step>

  <Step title="Neue E-Mail hinzufügen">
    Klicke am Ende der Dropdown-Liste auf **+ Neue E-Mail-Adresse hinzufügen**.

    Gib die E-Mail-Adresse und optional den Empfängernamen ein und bestätige mit **Hinzufügen**.
  </Step>

  <Step title="E-Mail sofort zuordnen">
    Die neue E-Mail-Adresse steht sofort in allen Dropdowns zur Auswahl zur Verfügung.
  </Step>
</Steps>

## Mahnwesen-E-Mail: Fallback-Kette

Wenn eine Mahnung ausgelöst wird, bestimmt das System den Empfänger anhand folgender Reihenfolge:

```
1. Mahnwesen-E-Mail(s) gesetzt?
   ├── Ja → Mahnung an alle Mahnwesen-E-Mails senden
   └── Nein ↓
2. Rechnungs-E-Mail(s) gesetzt?
   ├── Ja → Mahnung an alle Rechnungs-E-Mails senden
   └── Nein ↓
3. Primär-E-Mail → Mahnung an Primär-E-Mail senden
```

<Info>
  Durch die Fallback-Kette ist sichergestellt, dass Mahnungen immer zugestellt werden, auch wenn keine explizite Mahnwesen-E-Mail konfiguriert ist.
  Bestehende Kunden ohne Mahnwesen-E-Mail verhalten sich wie bisher.
</Info>

## Welche Benachrichtigungen nutzen welche E-Mail?

| Benachrichtigungstyp                     | E-Mail-Rolle                        |
| ---------------------------------------- | ----------------------------------- |
| Rechnung erstellt / bezahlt / storniert  | Rechnungs-E-Mail                    |
| Gutschrift / Erstattung                  | Rechnungs-E-Mail                    |
| Zahlungserinnerung / Mahnung             | **Mahnwesen-E-Mail** (mit Fallback) |
| SEPA-Vorabinformation                    | Rechnungs-E-Mail                    |
| Preisänderung / Abo-Kündigung            | Rechnungs-E-Mail                    |
| Zahlungsmethode hinzugefügt / abgelaufen | Primär-E-Mail                       |

## API

<Tabs>
  <Tab title="E-Mail erstellen">
    ```bash theme={null}
    POST /customers/{customerId}/email-addresses

    {
      "email": "buchhaltung@example.com",
      "receiverName": "Buchhaltung",
      "isInvoiceEmail": true,
      "isDunningEmail": false,
      "isDefault": false
    }
    ```
  </Tab>

  <Tab title="Mahnwesen-Flag setzen">
    ```bash theme={null}
    PATCH /customer-email-addresses/{id}
    Content-Type: application/merge-patch+json

    { "isDunningEmail": true }
    ```
  </Tab>

  <Tab title="Nach Typ filtern">
    ```bash theme={null}
    GET /customers/{customerId}/email-addresses?isDunningEmail=true
    GET /customers/{customerId}/email-addresses?isInvoiceEmail=true
    ```
  </Tab>
</Tabs>

Weitere API-Endpunkte findest du in der [API-Referenz](/api-reference/customeremail/get-customer-email-addresses).


# E-Mail-Versand und Statusverfolgung
Source: https://docs.fynn.eu/guide/customers/email-tracking

Verfolge den Versandstatus von E-Mails und verwalte die Kommunikation mit deinen Kunden.

## Übersicht

Fynn bietet eine umfassende E-Mail-Versandverfolgung, mit der du den Status jeder gesendeten E-Mail einsehen kannst. Du kannst sehen, ob E-Mails erfolgreich zugestellt wurden, geöffnet wurden oder ob es Probleme beim Versand gab.

<Frame>
  <img alt="E-Mail-Übersicht im Kunden-Tab" />
</Frame>

## Globale E-Mail-Übersicht

Neben der kundenbezogenen Ansicht bietet Fynn eine mandantenweite E-Mail-Übersicht, in der alle gesendeten E-Mails zentral einsehbar sind — unabhängig vom Kunden.

### Globale Liste öffnen

<Steps>
  <Step title="E-Mail-Übersicht aufrufen">
    Navigiere zu **Benachrichtigungen > Gesendete E-Mails** in der linken Navigation.
  </Step>

  <Step title="E-Mails durchsuchen und filtern">
    Die globale E-Mail-Liste unterstützt folgende Filter:

    * **Zeitraum**: Eingrenzen nach Versanddatum
    * **Status**: Filtern nach Zustellstatus (Zugestellt, Ausstehend, Zurückgewiesen, Fehlgeschlagen, etc.)
    * **Betreff**: Volltextsuche im E-Mail-Betreff
    * **Empfänger**: Suche nach Empfänger-E-Mail-Adresse
    * **Kunde**: Einschränkung auf einen bestimmten Kunden
  </Step>
</Steps>

### Organisationsübergreifende Ansicht

Wenn ein Kunde Teil einer [Organisationsstruktur](/guide/customers/organization-hierarchy) ist, kann die E-Mail-Liste auch alle E-Mails der zugehörigen Child-Kunden anzeigen. Aktiviere dafür die Option **Parent-Kunde einbeziehen** bei der Kundenfilterung.

## E-Mail-Tab im Kundenbereich

Im Kundenbereich findest du einen eigenen Tab "E-Mails", der alle an den Kunden gesendeten E-Mails chronologisch auflistet.

### E-Mail-Liste anzeigen

<Steps>
  <Step title="Kundenbereich öffnen">
    Navigiere zu einem Kunden in der [Kundenübersicht](https://app.fynn.eu/customers) und wähle den gewünschten Kunden aus.
  </Step>

  <Step title="E-Mail-Tab öffnen">
    Klicke auf den Tab **"E-Mails"** in der Kundenansicht.

    <Frame>
      <img alt="E-Mail-Tab im Kundenbereich" />
    </Frame>
  </Step>

  <Step title="E-Mail-Liste durchsuchen">
    Die E-Mail-Liste zeigt alle gesendeten E-Mails mit folgenden Informationen:

    * **Datum**: Wann die E-Mail gesendet wurde
    * **Betreff**: Der E-Mail-Betreff
    * **Typ**: Art der E-Mail (Rechnung, Mahnung, Benachrichtigung, etc.)
    * **Status**: Aktueller Versandstatus
    * **Geöffnet**: Anzahl der Öffnungen

    <Tip>
      Bei E-Mails mit mehreren Empfängern siehst du "An X Empfänger" unter dem Betreff.
    </Tip>
  </Step>
</Steps>

## E-Mail-Status verstehen

Jede E-Mail hat einen Status, der den aktuellen Versandzustand anzeigt. Die Status-Badges sind farbcodiert, damit du auf einen Blick erkennen kannst, ob alles in Ordnung ist.

### Status-Badges

<CardGroup>
  <Card title="Ausstehend" icon="clock">
    Die E-Mail wurde in die Warteschlange gestellt, ist aber noch nicht versendet worden.
  </Card>

  <Card title="Zugestellt" icon="check-circle">
    Die E-Mail wurde erfolgreich an den E-Mail-Server des Empfängers zugestellt.
  </Card>

  <Card title="Geöffnet" icon="eye">
    Der Empfänger hat die E-Mail geöffnet. Bei mehrfachen Öffnungen wird die Anzahl angezeigt.
  </Card>

  <Card title="Zurückgewiesen" icon="exclamation-triangle">
    Die E-Mail konnte nicht zugestellt werden (z.B. ungültige E-Mail-Adresse oder volles Postfach).
  </Card>

  <Card title="Fehlgeschlagen" icon="x-circle">
    Der Versand der E-Mail ist fehlgeschlagen (z.B. Serverfehler).
  </Card>

  <Card title="Custom SMTP" icon="envelope">
    Die E-Mail wurde über einen benutzerdefinierten SMTP-Server versendet. Detaillierte Statusverfolgung ist nicht verfügbar.
  </Card>
</CardGroup>

<Note>
  Der Status "Custom SMTP" erscheint, wenn E-Mails über einen benutzerdefinierten SMTP-Server versendet werden. In diesem Fall ist keine detaillierte Statusverfolgung (Öffnungen, Bounces, etc.) möglich, da der SMTP-Server keine Webhooks sendet.
</Note>

## E-Mail-Details anzeigen

Für jede E-Mail kannst du detaillierte Informationen anzeigen, einschließlich des vollständigen E-Mail-Inhalts und des Zustellungsverlaufs.

<Steps>
  <Step title="E-Mail-Details öffnen">
    Klicke auf eine E-Mail in der Liste, um die Detailansicht zu öffnen.

    <Frame>
      <img alt="E-Mail-Detailansicht" />
    </Frame>
  </Step>

  <Step title="E-Mail-Informationen einsehen">
    In der Detailansicht findest du:

    * **Betreff**: Vollständiger E-Mail-Betreff
    * **Status**: Aktueller Versandstatus mit Badge
    * **Versandart**: Ob die E-Mail über Fynn oder einen eigenen SMTP-Server versendet wurde
    * **Von/An**: Absender und alle Empfänger
    * **Gesendet am**: Zeitpunkt des Versands
    * **Zugestellt am**: Zeitpunkt der Zustellung (falls verfügbar)
    * **Geöffnet am**: Zeitpunkt der ersten Öffnung (falls verfügbar)
  </Step>

  <Step title="E-Mail-Inhalt anzeigen">
    Der vollständige E-Mail-Inhalt wird in einer sicheren Vorschau angezeigt. Du kannst so sehen, wie die E-Mail beim Empfänger angekommen ist.

    <Warning>
      Die E-Mail-Vorschau wird in einer sandboxed Umgebung angezeigt, um Sicherheit zu gewährleisten.
    </Warning>
  </Step>
</Steps>

## Status bei mehreren Empfängern

Wenn eine E-Mail an mehrere Empfänger gesendet wird, wird für jeden Empfänger ein separater Status verfolgt.

### Per-Empfänger-Status

<Steps>
  <Step title="E-Mail mit mehreren Empfängern öffnen">
    Öffne die Detailansicht einer E-Mail, die an mehrere Empfänger gesendet wurde.
  </Step>

  <Step title="Status pro Empfänger anzeigen">
    In der Detailansicht findest du einen Abschnitt **"Status pro Empfänger"**, der für jeden Empfänger den individuellen Status anzeigt.

    <Frame>
      <img alt="Status pro Empfänger" />
    </Frame>

    <Info>
      Der Gesamtstatus der E-Mail zeigt immer den "schlimmsten" Status an. Wenn z.B. eine E-Mail an drei Empfänger gesendet wurde und einer zurückgewiesen wurde, zeigt der Gesamtstatus "Zurückgewiesen" an, auch wenn die anderen beiden erfolgreich zugestellt wurden.
    </Info>
  </Step>

  <Step title="Zustellungsverlauf pro Empfänger">
    Im Zustellungsverlauf siehst du, welche Ereignisse zu welchem Empfänger gehören. Jedes Ereignis ist mit dem entsprechenden Empfänger gekennzeichnet.
  </Step>
</Steps>

## Zustellungsverlauf

Der Zustellungsverlauf zeigt alle wichtigen Ereignisse im Lebenszyklus einer E-Mail chronologisch an.

### Verfügbare Ereignisse

* **Gesendet**: E-Mail wurde an den E-Mail-Server übergeben
* **Zugestellt**: E-Mail wurde erfolgreich zugestellt
* **Geöffnet**: Empfänger hat die E-Mail geöffnet
* **Geklickt**: Empfänger hat auf einen Link in der E-Mail geklickt
* **Zurückgewiesen**: E-Mail konnte nicht zugestellt werden
* **Fehlgeschlagen**: Versand ist fehlgeschlagen

<Frame>
  <img alt="Zustellungsverlauf" />
</Frame>

## E-Mail-Versand über Fynn

Fynn bietet zwei Möglichkeiten, E-Mails zu versenden, die unterschiedliche Möglichkeiten zur Statusverfolgung bieten.

### E-Mail-Versand über Fynn (Empfohlen)

Wenn E-Mails über Fynn versendet werden, steht eine umfassende Statusverfolgung zur Verfügung:

* ✅ Detaillierte Statusverfolgung (Zugestellt, Geöffnet, Geklickt, Zurückgewiesen)
* ✅ Echtzeit-Updates über Webhooks
* ✅ Per-Empfänger-Status bei mehreren Empfängern
* ✅ Vollständiger Zustellungsverlauf

<Note>
  E-Mails werden standardmäßig über Fynn versendet, wenn keine benutzerdefinierte SMTP-Konfiguration vorhanden ist.
</Note>

### E-Mail-Versand über eigenen SMTP-Server

Wenn du einen eigenen SMTP-Server konfiguriert hast, werden E-Mails über diesen Server versendet:

* ⚠️ Basis-Statusverfolgung (nur Versand-Erfolg/Fehler)
* ⚠️ Keine detaillierte Statusverfolgung (keine Öffnungen, Bounces, etc.)
* ⚠️ Status wird als "Custom SMTP" angezeigt

<Warning>
  Bei E-Mails, die über einen eigenen SMTP-Server versendet werden, ist keine detaillierte Statusverfolgung möglich, da SMTP-Server keine Webhooks senden. Du siehst nur, ob die E-Mail erfolgreich an den SMTP-Server übergeben wurde.
</Warning>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Warum sehe ich keinen Status für eine E-Mail?">
    Wenn eine E-Mail gerade erst versendet wurde, kann es einige Sekunden dauern, bis der Status aktualisiert wird. Bei E-Mails, die über Custom SMTP versendet wurden, ist nur ein Basis-Status verfügbar.
  </Accordion>

  <Accordion title="Was bedeutet 'Custom SMTP (keine detaillierte Statusverfolgung)'?">
    Dieser Status erscheint, wenn E-Mails über einen benutzerdefinierten SMTP-Server versendet werden. In diesem Fall kann Fynn keine detaillierten Informationen über Öffnungen, Bounces oder Klicks bereitstellen, da der SMTP-Server keine Webhooks sendet.
  </Accordion>

  <Accordion title="Warum zeigt der Status 'Zurückgewiesen' an, obwohl die E-Mail zugestellt wurde?">
    Wenn eine E-Mail an mehrere Empfänger gesendet wurde und mindestens einer zurückgewiesen wurde, zeigt der Gesamtstatus "Zurückgewiesen" an. In der Detailansicht kannst du den Status pro Empfänger einsehen.
  </Accordion>

  <Accordion title="Wie aktualisiert sich der Status?">
    Bei E-Mails, die über Fynn versendet wurden, werden Status-Updates automatisch in Echtzeit aktualisiert. Du musst die Seite nicht aktualisieren, um die neuesten Status-Informationen zu sehen.
  </Accordion>

  <Accordion title="Kann ich sehen, wer eine E-Mail geöffnet hat?">
    Ja, bei E-Mails mit mehreren Empfängern kannst du in der Detailansicht sehen, welcher Empfänger die E-Mail geöffnet hat. Die Öffnungsereignisse sind im Zustellungsverlauf mit dem entsprechenden Empfänger gekennzeichnet.
  </Accordion>
</AccordionGroup>


# Kunde verwalten
Source: https://docs.fynn.eu/guide/customers/introduction

Erstelle und verwalte Kunden.

## Kunde erstellen

Erstelle einen neuen Kunden um Abonnements und Rechnungen zu erstellen.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kunden erstellen - Maske öffnen">
        Um die Kunden erstellen Maske zu öffnen, gibt es mehrere Möglichkeiten.

        Die schnellste Möglichkeit ist es, oben links auf das Plus-Symbol zu klicken und dann "Kunde" auszuwählen.
        Alternativ kannst du einfach `c` `n` als Tastenkombination verwenden.

        <Frame>
          <img alt="Plus-Shortcut" />
        </Frame>

        Andernfalls kannst du auch auf ["Kunden"](https://app.fynn.eu/customers) in der linken Navigation klicken und dann auf "Neu".
      </Step>

      <Step title="Fülle die Kundendetails aus">
        Fülle die Kundendetails aus. Je nach Kundentyp (Privatperson oder Unternehmen) sind unterschiedliche Felder erforderlich.

        <Tip>
          Standardmäßig wird eine Kundennummer auf Basis des [Nummernkreises](/guide/tenant/number-ranges) generiert.
          Du kannst die Kundennummer auch manuell festlegen, indem du auf "Kundennummer" klickst und eine eigene Nummer eingibst.
        </Tip>

        <Info>
          **Automatische Spracherkennung:** Die Sprache des Kunden wird automatisch anhand des Landes vorgeschlagen.
          Kunden aus DACH-Ländern (DE, AT, CH) erhalten Deutsch, alle anderen Englisch.
          Die Sprache bestimmt, in welcher Sprache [Benachrichtigungen](/guide/notifications/introduction) und [Rechnungen](/guide/invoices/introduction) erstellt werden.
          Du kannst die vorgeschlagene Sprache jederzeit manuell überschreiben.
        </Info>

        <AccordionGroup>
          <Accordion title="Empfängeradresse">
            Wird die Empfängeradresse nicht ausgefüllt, wird automatisch eine leere Adresse erstellt. Diese kannst du im Nachhinein bearbeiten.

            Die Empfängeradresse wird zur Erstellung von [Rechnungen](/guide/invoices) und [Angeboten](/guide/offers) verwendet.

            <Frame>
              <img alt="Empfängeradresse" />
            </Frame>
          </Accordion>

          <Accordion title="Abweichende Rechnungsdaten">
            In einigen Fällen kann es erforderlich sein, dass die Rechnungs E-Mail Adresse von der Empfängeradresse abweicht.

            In diesem Fall kannst du die abweichenden Rechnungsdaten ausfüllen.
          </Accordion>

          <Accordion title="DATEV">
            <Note>
              Die DATEV-Integration ist als Add-On verfügbar. Kontaktiere uns, wenn du die DATEV-Integration aktivieren möchtest.
            </Note>

            Wenn du die DATEV-Integration aktiviert hast, kannst du hier die DATEV-Debitorennummer eingeben oder automatisch auf Basis des [Nummernkreises](/guide/tenant/number-ranges) generieren lassen.

            <Frame>
              <img alt="DATEV Einstellungen" />
            </Frame>
          </Accordion>
        </AccordionGroup>

        <Frame>
          <img alt="Kunde anlegen" />
        </Frame>

        Klicke nun auf <b>Kunde erstellen</b> um den Kunden anzulegen.
      </Step>

      <Step title="Kunde wurde erfolgreich angelegt">
        Der Kunde wurde erfolgreich angelegt. Du kannst nun [Abonnements](/guide/subscriptions), [Angebote](/guide/offers) und [Rechnungen](/guide/invoices) für den Kunden erstellen.

        <Frame>
          <img alt="Kunde erfolgreich angelegt" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Kunde erstellen](/api-reference/customer/create-customer) Endpunkt.

    ```bash theme={null}
    POST /customers
    ```

    Alternativ kannst du den [Kunden abrufen](/api-reference/customer/get-customer)
    oder den [Kunden über die API aktualisieren](/api-reference/customer/update-customer).
  </Tab>

  <Tab title="Importieren">
    Der Import der Kundendaten ist aktuell über folgende Wege möglich:

    * Anlage über die [API](/api-reference/customer/create-customer)
    * DATEV-Debitorenstamm-Import
    * Stripe-Import

    <Tip>
      Solltest du Interesse an einem Stripe oder DATEV-Debitorenstamm-Import haben, oder von einer anderen Subscription Billing Lösung migrieren wollen, kontaktiere uns bitte hierzu.
    </Tip>
  </Tab>
</Tabs>

## Kunde bearbeiten

Nachdem du einen Kunden erstellt hast, kannst du die Kundendetails jederzeit bearbeiten.

<Warning>
  Unter Umständen kann es sein, dass du die Kundendetails nicht bearbeiten kannst, sofern du nicht die entsprechenden Berechtigungen hast oder die Kunden in der Web-Oberfläche schreibgeschützt sind.
</Warning>

Um die Einstellungen zu schreibgeschützte Kunden zu ändern, siehe [Schreibgeschützte Kunden](/guide/tenant/ui-defaults#Schreibgeschützte-Kunden).

<Steps>
  <Step title="Kunden bearbeiten - Maske öffnen">
    Um die Kundendetails zu bearbeiten, klicke auf "Kunden" in der linken Navigation und wähle den Kunden aus, den du bearbeiten möchtest.

    Klicke nun auf "Bearbeiten" auf der rechten Seite um die Kundendetails zu bearbeiten.
  </Step>

  <Step title="Kundendetails bearbeiten">
    Passe die Kundendetails an und klicke auf "Speichern" um die Änderungen zu übernehmen.

    <Frame>
      <img alt="Kunde bearbeiten" />
    </Frame>
  </Step>

  <Step title="Kundenadresse bearbeiten">
    Um die Adresse des Kunden zu bearbeiten, bleibe in der selben Maske und wähle das passende Dropdown im Bereich "Adressen" aus.

    Neben der Adresse kannst du über das "Stift"-Symbol die Adresse bearbeiten.

    <Info>
      Bei einer Änderung der Adresse wird die Adresse ebenfalls für bestehende Abonnements aktualisiert, sofern diese am Abonnement ausgewählt wurde, oder die Standardadresse verwendet werden soll.
      Wünscht du dies nicht, lege bitte eine neue Adresse an und wähle diese explizit am Abonnement aus.
    </Info>

    <Frame>
      <img alt="Adresse bearbeiten" />
    </Frame>
  </Step>

  <Step title="Kunde wurde erfolgreich bearbeitet" />
</Steps>

## Kunde archivieren

Du kannst einen Kunden archivieren, um diesen in der Kundenübersicht auszublenden.
Archivierte Kunden können zu einem späteren Zeitpunkt wiederhergestellt werden.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kunden archivieren">
        Um einen Kunden zu archivieren, klicke auf "Kunden" in der linken Navigation und wähle den Kunden aus, den du archivieren möchtest.

        Klicke nun auf "Archivieren" auf der rechten Seite um den Kunden zu archivieren.
      </Step>

      <Step title="Kunden archivieren bestätigen">
        Bestätige das Archivieren des Kunden, indem du auf "Archivieren" klickst.

        <Check>
          Einmal archivierte Kunden können wiederhergestellt werden.
        </Check>
      </Step>

      <Step title="Kunde wurde erfolgreich archiviert">
        Der Kunde wurde erfolgreich archiviert und wird in der Kundenübersicht ausgeblendet.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Kunde archivieren](/api-reference/customer/archive-customer) Endpunkt.

    ```bash theme={null}
    PUT /customers/{customerId}/archive
    ```
  </Tab>
</Tabs>

## Kunde löschen

Du kannst einen Kunden löschen, wenn dieser nicht mehr benötigt wird.

Um einen Kunden löschen zu können, müssen folgende Bedingungen erfüllt sein:

* Der Kunde darf keine aktiven Abonnements besitzen
* Der Kunde darf keine Rechnungen besitzen
* Der Kunde darf keine abgeschlossenen Bestellungen besitzen
* Der Kunde darf keine Zahlungen besitzen

<Tip>
  Sollte eines der oben genannten Kriterien nicht erfüllt sein, kannst du stattdessen den \[Kunden archivieren]\(#Kunde archivieren).
  Archivierte Kunden werden in der Kundenübersicht ausgeblendet.
</Tip>

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kunden löschen">
        Um einen Kunden zu löschen, klicke auf "Kunden" in der linken Navigation und wähle den Kunden aus, den du löschen möchtest.

        Klicke nun auf "Löschen" auf der rechten Seite um den Kunden zu löschen.
      </Step>

      <Step title="Kunden löschen bestätigen">
        Bestätige die Löschung des Kunden, indem du auf "Unwiderruflich löschen" klickst.

        <Warning>
          Einmal gelöschte Kunden können **nicht** wiederhergestellt werden.
        </Warning>
      </Step>

      <Step title="Kunde wurde erfolgreich gelöscht">
        Der Kunde wurde erfolgreich gelöscht.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Kunde löschen](/api-reference/customer/delete-customer) Endpunkt.

    ```bash theme={null}
    DELETE /customers/{customerId}
    ```
  </Tab>
</Tabs>

## Kunden exportieren

Um Kunden als Xlsx-Datei zu exportieren, navigiere zur Kundenübersicht und klicke auf "Exportieren".
Der Export umfasst alle Kunden, die in deiner Organisation angelegt sind.

Im Export sind folgende Informationen enthalten:

* Kundenstammdaten
* Standard-Rechnungsadresse
* Standard-Kundenadresse
* Kunden-E-Mail-Adresse
* Rechnungs-E-Mail-Adresse
* Standard-Zahlungsart

<Frame>
  <img alt="Kunden exportieren" />
</Frame>

## Persönlicher Ansprechpartner hinterlegen

Du kannst für jeden Kunden einen persönlichen Ansprechpartner hinterlegen. Dieser wird auf Angeboten, im [Kundenbereich](/guide/customers/customer-portal) und in der Kundendetailansicht angezeigt.

## Einstellungen

Individuelle Einstellungen pro Kunde wie Zahlungsfrist, automatischer Versand und Mahnwesen findest du unter [Kundeneinstellungen](/guide/customers/settings).


# Organisationsstruktur
Source: https://docs.fynn.eu/guide/customers/organization-hierarchy

Bilde Unternehmenshierarchien mit Parent-Child-Beziehungen zwischen Kunden ab.

Viele Organisationen bestehen aus einer übergeordneten Einheit mit mehreren Abteilungen, Standorten oder Tochtergesellschaften. Die Organisationsstruktur ermöglicht es, diese Beziehungen direkt in Fynn abzubilden — mit einer klaren Parent-Child-Hierarchie zwischen Kunden.

<Info>
  Die Organisationsstruktur erfordert die Aktivierung des Feature-Flags `customer.hierarchy`. Kontaktiere den Support, um diese Funktion für deinen Mandanten freizuschalten.
</Info>

## Überblick

Mit der Organisationsstruktur kannst du:

* **Parent-Child-Beziehungen** zwischen Kunden definieren (z. B. Hauptunternehmen → Abteilungen)
* **Bis zu 3 Hierarchieebenen** abbilden (Hauptunternehmen → Tochtergesellschaft → Abteilung)
* **Abonnements, Rechnungen und Transaktionen** gefiltert nach Organisationszugehörigkeit einsehen
* **Aktivitäten** zur Nachverfolgung von Hierarchieänderungen nutzen

<Note>
  Die Organisationsstruktur ist eine rein organisatorische Funktion. Sie hat in der aktuellen Version keinen Einfluss auf die Rechnungsstellung oder Zahlungsabwicklung. Sie bildet die Grundlage für zukünftige Funktionen wie die organisationsbasierte Abrechnung (Consolidated Billing).
</Note>

## Anwendungsbeispiele

| Branche          | Parent-Kunde              | Child-Kunden                            |
| ---------------- | ------------------------- | --------------------------------------- |
| Gesundheitswesen | Klinik Musterstadt        | Radiologie, Orthopädie, Kardiologie     |
| Recht            | Kanzlei Schmidt & Partner | Standort Berlin, Standort München       |
| Einzelhandel     | Retail Group GmbH         | Filiale Nord, Filiale Süd, Filiale West |

## Hierarchie verwalten

### Parent-Kunde zuweisen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zum Kunden, der als Child-Kunde einem übergeordneten Kunden zugewiesen werden soll.
      </Step>

      <Step title="Parent-Kunde zuweisen">
        Im Bereich Organisationsstruktur kannst du den übergeordneten Kunden (Parent) auswählen und zuweisen.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Set parent customer](/api-reference/customer/set-parent-customer) Endpunkt.

    ```bash theme={null}
    PUT /customers/{customerId}/set-parent
    ```

    ```json theme={null}
    {
        "parentCustomerId": "00000000-0000-0000-0000-000000000000"
    }
    ```
  </Tab>
</Tabs>

### Parent-Kunde entfernen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zum Child-Kunden, dessen Parent-Zuweisung entfernt werden soll.
      </Step>

      <Step title="Parent-Zuweisung entfernen">
        Im Bereich Organisationsstruktur kannst du die bestehende Parent-Zuweisung entfernen. Der Kunde wird dadurch wieder zu einem eigenständigen Kunden ohne Hierarchie.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Remove parent customer](/api-reference/customer/remove-parent-customer) Endpunkt.

    ```bash theme={null}
    PUT /customers/{customerId}/remove-parent
    ```
  </Tab>
</Tabs>

### Child-Kunden einsehen

<Tabs>
  <Tab title="Web-App verwenden">
    Auf der Kundendetailseite eines Parent-Kunden wird die Anzahl der Child-Kunden angezeigt. Über den Bereich Organisationsstruktur kannst du direkt zu den Child-Kunden navigieren.
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Get customer children](/api-reference/customer/get-customer-children) Endpunkt, um alle direkten Child-Kunden inklusive Metriken abzurufen.

    ```bash theme={null}
    GET /customers/{customerId}/children
    ```

    Die Antwort enthält für jeden Child-Kunden die Kundendaten sowie die Anzahl aktiver Abonnements (`activeSubscriptionCount`).
  </Tab>
</Tabs>

### Gesamte Hierarchie anzeigen

Über die API kannst du die vollständige Hierarchie eines Kunden als Baumstruktur abrufen — unabhängig davon, ob du den Parent- oder einen Child-Kunden angibst. Die Antwort beginnt immer beim Root-Kunden.

```bash theme={null}
GET /customers/{customerId}/hierarchy
```

```json theme={null}
{
    "root": {
        "id": "uuid-100",
        "name": "Klinik Musterstadt",
        "customerNumber": "CUST-100",
        "isCurrentCustomer": false,
        "children": [
            {
                "id": "uuid-101",
                "name": "Radiologie",
                "customerNumber": "CUST-101",
                "isCurrentCustomer": true,
                "children": []
            },
            {
                "id": "uuid-102",
                "name": "Orthopädie",
                "customerNumber": "CUST-102",
                "isCurrentCustomer": false,
                "children": []
            }
        ]
    }
}
```

## Kundenliste filtern

Die Kundenliste unterstützt zusätzliche Filter für die Organisationsstruktur:

| Filter             | Beschreibung                                                       |
| ------------------ | ------------------------------------------------------------------ |
| `parentCustomerId` | Zeigt nur die direkten Child-Kunden eines bestimmten Parent-Kunden |
| `isParent=true`    | Zeigt nur Kunden, die Child-Kunden haben                           |
| `hasParent=true`   | Zeigt nur Kunden, die einem Parent-Kunden zugewiesen sind          |

Beispiel über die API:

```bash theme={null}
GET /customers?parentCustomerId={parentId}
GET /customers?isParent=true
GET /customers?hasParent=true
```

## Organisationsübergreifende Ansichten

Wenn ein Parent-Kunde ausgewählt ist, können Abonnements, Rechnungen und Transaktionen aller zugehörigen Child-Kunden über den `parentCustomer`-Filter zusammen eingesehen werden.

```bash theme={null}
GET /subscriptions?parentCustomer={parentCustomerId}
GET /invoices?parentCustomer={parentCustomerId}
GET /transactions?parentCustomer={parentCustomerId}
```

## Validierungsregeln

Bei der Verwaltung der Organisationsstruktur gelten folgende Regeln:

| Regel              | Beschreibung                                                                         |
| ------------------ | ------------------------------------------------------------------------------------ |
| Maximale Tiefe     | Die Hierarchie unterstützt maximal 3 Ebenen (Root → Child → Grandchild)              |
| Keine Zirkelbezüge | Ein Kunde kann nicht sein eigener Parent sein, weder direkt noch indirekt            |
| Gleicher Mandant   | Parent- und Child-Kunde müssen zum selben Mandanten gehören                          |
| Aktiver Parent     | Der Parent-Kunde darf nicht archiviert sein                                          |
| Archivierung       | Ein Kunde mit aktiven (nicht archivierten) Child-Kunden kann nicht archiviert werden |

## Webhooks

Änderungen an der Organisationsstruktur lösen Webhook-Events aus:

| Event                      | Beschreibung                      |
| -------------------------- | --------------------------------- |
| `customer.parent.assigned` | Ein Parent-Kunde wurde zugewiesen |
| `customer.parent.removed`  | Ein Parent-Kunde wurde entfernt   |

Weitere Informationen zur Konfiguration von Webhooks findest du unter [Webhooks](/guide/webhooks/introduction).

## Ausblick

Die Organisationsstruktur ist die Grundlage für zukünftige Abrechnungsfunktionen auf Organisationsebene. Geplant sind unter anderem:

* **Organisationsbasierte Abrechnung (Consolidated Billing):** Rechnungen für Child-Kunden können an den Parent-Kunden gerichtet werden.
* **Flexible Zahlungssteuerung:** Pro Child-Kunde kann festgelegt werden, wer Rechnungsempfänger und Zahlungspflichtiger ist.
* **Konsolidierungszeiträume:** Rechnungen können monatlich oder quartalsweise zusammengefasst werden.


# Kundeneinstellungen
Source: https://docs.fynn.eu/guide/customers/settings

Individuelle Einstellungen pro Kunde konfigurieren

## Übersicht

Die Kundeneinstellungen ermöglichen es dir, spezifische Einstellungen für jeden Kunden zu konfigurieren.
Standardmäßig werden diese Einstellungen aus der Organisation übernommen.

Woher die Einstellungen übernommen werden, kannst du durch den Vererbungshinweis erkennen:

* **Vererbt von Organisation**: Die Einstellung wird aus den Organisationseinstellungen übernommen
* **Vererbt aus Standardwerten**: Die Einstellung verwendet den Systemstandard
* **Kundenspezifischer Wert**: Die Einstellung wurde individuell für diesen Kunden gesetzt

<Info>
  Ist eine Einstellung einmal kundenindividuell gesetzt, kann diese nicht mehr automatisch von der Organisation übernommen werden.
</Info>

## Einstellungen öffnen

<Steps>
  <Step title="Kundendetails öffnen">
    Navigiere zu "Kunden" und wähle den gewünschten Kunden aus.
  </Step>

  <Step title="Einstellungen Tab öffnen">
    Klicke auf den Tab "Einstellungen" in der Kundendetailansicht.
  </Step>
</Steps>

## Elektronische Rechnung

Konfiguriere, ob und in welchem Format der Kunde elektronische Rechnungen erhalten soll.

Alle Einstellungen und Details zur elektronischen Rechnung findest du unter [e-Rechnung](/guide/invoices/e-invoicing).

## Zahlungsfrist anpassen

Die Zahlungsfrist wird standardmäßig auf 14 Tage gesetzt und aus der Organisation übernommen. Du kannst die Zahlungsfrist für den Kunden individuell anpassen.

<Frame>
  <img alt="Zahlungsfrist" />
</Frame>

<Tip>
  Die Zahlungsfrist wird auf alle neuen Rechnungen für diesen Kunden angewendet. Bestehende Rechnungen werden nicht geändert.
</Tip>

## Belege automatisch versenden

Deaktiviere diese Option, um Rechnungen aus einem Abonnement nicht automatisch freizugeben.
Hierdurch kannst du die Rechnung vor dem Versand noch einmal prüfen und ggf. anpassen.

<Frame>
  <img alt="Belege automatisch versenden" />
</Frame>

<Warning>
  Wenn diese Option deaktiviert ist, musst du Rechnungen manuell finalisieren und versenden.
</Warning>

## Zahlungserinnerungen deaktivieren

Deaktiviere diese Option, um keine Zahlungserinnerungen für den Kunden zu versenden.
Hiermit wird die Zahlungserinnerung als auch Mahnungen für den Kunden deaktiviert.

<Frame>
  <img alt="Zahlungserinnerungen deaktivieren" />
</Frame>

<Note>
  Diese Einstellung betrifft nur automatische Zahlungserinnerungen. Manuelle Erinnerungen können weiterhin versendet werden.
</Note>

## Kundenguthaben (Wallet)

Steuere das Verhalten des Kundenguthabens für diesen Kunden individuell. Standardmäßig werden die Werte aus den globalen Abrechnungseinstellungen übernommen.

### Überzahlungen als Guthaben verbuchen

Aktiviere diese Option, damit Überzahlungen automatisch dem Kundenguthaben gutgeschrieben werden. Ist sie deaktiviert, bleiben Überzahlungen als Differenz bestehen und müssen manuell bearbeitet werden.

### Guthaben automatisch auf offene Rechnungen anrechnen

Wenn aktiviert, wird vorhandenes Guthaben dieses Kunden automatisch auf seine offenen Rechnungen angerechnet, beginnend mit der ältesten fälligen Rechnung.

<Info>
  Mehr Details zur Funktionsweise findest du unter [Kundenguthaben](/guide/invoices/wallet-balance). Die globalen Standardwerte werden unter [Einstellungen > Abrechnung](/guide/tenant/billing) konfiguriert.
</Info>

## Mahngebühren deaktivieren

Deaktiviere diese Option, um keine Mahngebühren für den Kunden zu berechnen.

<Frame>
  <img alt="Mahngebühren deaktivieren" />
</Frame>

## API

Du kannst die Kundeneinstellungen auch über die API abrufen und ändern:

<Tabs>
  <Tab title="Einstellungen abrufen">
    ```bash theme={null}
    GET /customers/{customerId}/settings
    ```

    [API Dokumentation](/api-reference/customersettings/get-settings)
  </Tab>

  <Tab title="Einstellungen ändern">
    ```bash theme={null}
    PUT /customers/{customerId}/settings
    ```

    [API Dokumentation](/api-reference/customersettings/update-settings)
  </Tab>
</Tabs>


# Entwickler
Source: https://docs.fynn.eu/guide/developers/introduction

Integriere deine Anwendung mit Fynn über die API, Webhooks und erweiterte Funktionen

Fynn bietet umfangreiche Entwickler-Tools, um deine Anwendungen nahtlos mit unserer Plattform zu integrieren. Ob du Zahlungsprozesse automatisieren, Kundendaten synchronisieren oder benutzerdefinierte Workflows erstellen möchtest – hier findest du alle notwendigen Ressourcen.

## Schnellstart

<CardGroup>
  <Card title="API Referenz" icon="book" href="/api-reference/introduction">
    Vollständige Dokumentation aller API-Endpunkte mit Beispielen.
  </Card>

  <Card title="API-Schlüssel erstellen" icon="key" href="https://app.fynn.eu/settings/api-tokens">
    Generiere API-Schlüssel für die Authentifizierung.
  </Card>
</CardGroup>

## Integrationsoptionen

### REST API

Die Fynn API ermöglicht dir den vollständigen Zugriff auf alle Funktionen der Plattform. Mit der RESTful API kannst du:

* **Kunden verwalten**: Erstellen, aktualisieren und abrufen von Kundendaten
* **Abonnements steuern**: Abonnements erstellen, ändern und kündigen
* **Rechnungen generieren**: Rechnungen erstellen, finalisieren und versenden
* **Zahlungen verarbeiten**: Zahlungsmethoden hinzufügen und Transaktionen verwalten
* **Produkte konfigurieren**: Katalog mit Produkten und Preisen verwalten

<Card title="API Dokumentation" icon="book-open" href="/api-reference/introduction">
  Lerne die API-Grundlagen und erkunde alle verfügbaren Endpunkte.
</Card>

### Webhooks

Webhooks ermöglichen es dir, in Echtzeit auf Ereignisse in Fynn zu reagieren. Du erhältst automatisch Benachrichtigungen, wenn:

* Ein neuer Kunde erstellt wird
* Eine Zahlung eingeht oder fehlschlägt
* Ein Abonnement gestartet, geändert oder gekündigt wird
* Eine Rechnung erstellt oder bezahlt wird

<Card title="Webhooks einrichten" icon="bell" href="/guide/webhooks/introduction">
  Konfiguriere Webhooks für Echtzeit-Ereignisse.
</Card>

### OAuth 2.0

Für Anwendungen, die im Namen von Benutzern auf Fynn zugreifen, bieten wir OAuth 2.0 Authentifizierung. Dies ermöglicht:

* Sichere Benutzerautorisierung ohne Passwort-Weitergabe
* Zugriff auf benutzerspezifische Daten
* Single Sign-On (SSO) Integration
* OpenID Connect für Identitätsmanagement

<Card title="OAuth2 Flow" icon="lock" href="/guide/oauth2/introduction">
  Implementiere sichere Authentifizierung mit OAuth 2.0.
</Card>

### Fynn Functions

Mit Fynn Functions kannst du die Plattform-Logik erweitern und benutzerdefinierte Regeln implementieren:

* **Checkout-Erweiterungen**: Dynamische Lieferkosten, Produktoptionen
* **Benutzerdefinierte Validierung**: Eigene Geschäftslogik im Checkout
* **Externe API-Integrationen**: Verbindung zu Drittsystemen

<Card title="Fynn Functions" icon="function" href="/guide/functions/index">
  Erweitere Fynn mit benutzerdefinierten Funktionen.
</Card>

## Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mittels API-Schlüssel.

<Steps>
  <Step title="API-Schlüssel erstellen">
    Gehe zu [Einstellungen > API-Schlüssel](https://app.fynn.eu/settings/api-tokens) und erstelle einen neuen Schlüssel.
  </Step>

  <Step title="Schlüssel sicher speichern">
    Der Schlüssel wird nur einmal angezeigt. Speichere ihn sicher ab.
  </Step>

  <Step title="Anfragen authentifizieren">
    Füge den Schlüssel als Bearer Token im Authorization Header hinzu:

    ```bash theme={null}
    curl -H "Authorization: Bearer YOUR_API_KEY" \
         https://coreapi.io/v1/customers
    ```
  </Step>
</Steps>

<Warning>
  Teile deinen API-Schlüssel niemals öffentlich. Verwende Umgebungsvariablen, um Schlüssel sicher zu speichern.
</Warning>

## Entwicklungsumgebungen

Fynn bietet zwei Umgebungen für die Entwicklung:

| Umgebung       | API URL                      | Beschreibung                       |
| -------------- | ---------------------------- | ---------------------------------- |
| **Production** | `https://coreapi.io`         | Live-Umgebung für Produktionsdaten |
| **Preview**    | `https://preview.coreapi.io` | Testumgebung für Entwicklung       |

<Tip>
  Nutze die Preview-Umgebung für Tests und Entwicklung, bevor du Änderungen in der Produktion ausrollst.
</Tip>

## Hilfreiche Ressourcen

<CardGroup>
  <Card title="n8n Integration" icon="robot" href="/integrations/automation/n8n">
    Automatisiere Workflows mit n8n und Fynn.
  </Card>

  <Card title="Postman Collection" icon="folder" href="/api-reference/introduction">
    Importiere die API in Postman für schnelles Testen.
  </Card>
</CardGroup>

## Support

Benötigst du Hilfe bei der Integration? Unser Entwickler-Support steht dir zur Verfügung:

* **E-Mail**: [hi@fynn.eu](mailto:hi@fynn.eu)
* **Termin buchen**: [Beratungsgespräch vereinbaren](https://cal.com/team/fynn/fynn-documentation)


# MCP-Server
Source: https://docs.fynn.eu/guide/developers/mcp

Verbinde KI-Assistenten wie Claude direkt mit Fynn: Kunden anlegen und pflegen, Abonnements einsehen, Angebote vollständig erstellen und versenden, Rechnungen bearbeiten und DATEV-Exporte starten.

Der Fynn MCP-Server setzt das [Model Context Protocol](https://modelcontextprotocol.io) um und macht die wichtigsten Fynn-Funktionen für KI-Assistenten wie Claude direkt zugänglich. Statt eine Benutzeroberfläche zu öffnen, beschreibst du, was du brauchst, und der Assistent ruft die passenden Tools auf.

Typische Einsatzfälle:

* Kunden anlegen, suchen und Stammdaten pflegen
* Abonnements und ihre Positionen einsehen, Preise anpassen
* Angebote vollständig erstellen, mit Inhalten befüllen und an Empfänger zustellen
* Rechnungen erstellen, bearbeiten und zur Freigabe einreichen
* DATEV-Cloud-Export per Bestätigungsdialog starten

## Verbindung einrichten

### Endpunkt

```
POST https://coreapi.io/portal/mcp
```

Für die Sandbox-Umgebung ersetze den Host durch `preview.coreapi.io`.

### Transport

Der Server verwendet **Streamable HTTP** (MCP-Spezifikation 2025-03-26). MCP-Clients, die dieses Transport-Protokoll unterstützen, verbinden sich direkt mit dem Endpunkt oben.

### Authentifizierung

Jede Anfrage benötigt zwei Header:

| Header             | Wert                     |
| ------------------ | ------------------------ |
| `Authorization`    | `Bearer <API-Schlüssel>` |
| `X-Fynn-Tenant-Id` | UUID der Organisation    |

Den API-Schlüssel erstellst du unter [Einstellungen > API-Schlüssel](https://app.fynn.eu/settings/api-tokens). Die Organisations-ID findest du in den Einstellungen deiner Organisation.

### Konfigurationsbeispiel

Die meisten MCP-Clients (z. B. Claude Desktop) nehmen eine JSON-Konfiguration. Hier ein Beispiel:

```json theme={null}
{
  "mcpServers": {
    "fynn": {
      "type": "http",
      "url": "https://coreapi.io/portal/mcp",
      "headers": {
        "Authorization": "Bearer <API-SCHLÜSSEL>",
        "X-Fynn-Tenant-Id": "<ORGANISATIONS-ID>"
      }
    }
  }
}
```

## Berechtigungen

Alle Tools respektieren die Rollen-Berechtigungen des verbundenen Nutzers. Wer in Fynn keine Rechnung lesen darf, bekommt über den MCP-Server auch keine. Die Anfrage schlägt in dem Fall mit einer klaren Fehlermeldung fehl, statt leere Daten zu liefern.

***

## Konventionen

Einige Konventionen gelten für alle schreibenden Tools:

**Geldbeträge** werden immer als Dezimalstring mit Währung übergeben, nie als Cent-Integer:

```json theme={null}
{ "amount": "149.00", "currency": "EUR" }
```

**Datumsangaben** sind ISO-8601 mit Zeitzonen-Offset, z. B. `2026-09-01T00:00:00+02:00`. Reine Kalenderdaten (`2026-09-01`) sind bei Datumsfeldern erlaubt; das Tool interpretiert sie als Mitternacht in der Organisations-Zeitzone.

**Menschliche Bezeichner** (Kundennummer, Abonummer, Belegnummer) werden neben UUIDs akzeptiert. Du musst IDs nicht vorab nachschlagen, wenn du die lesbare Nummer kennst.

**`nextSteps`** in Schreibantworten: Jede erfolgreiche Schreibantwort enthält einen `nextSteps`-Array mit konkreten Hinweisen, welche Tools als nächstes sinnvoll wären.

***

## Tool-Referenz

Die folgenden Tools stehen zur Verfügung, gruppiert nach Funktionsbereich.

### Allgemein

#### `fynn_ping`

Prüft die Verbindung, Authentifizierung und den Organisations-Kontext. Gibt `ok`, die Organisations-ID und einen Zeitstempel zurück. Nimmt keine Parameter entgegen.

***

### Kunden

#### `customer_search`

Sucht nach Kunden anhand eines Suchbegriffs oder einer Abonummer.

| Parameter            | Typ     | Pflicht | Beschreibung                                                        |
| -------------------- | ------- | ------- | ------------------------------------------------------------------- |
| `search`             | string  |         | Teiltreffer auf Name, Firma, Kundennummer oder DATEV-Debitorenkonto |
| `subscriptionNumber` | string  |         | Abonummer, über die der zugehörige Kunde direkt ermittelt wird      |
| `page`               | integer |         | Seitennummer (1-basiert, Standard 1)                                |
| `limit`              | integer |         | Treffer pro Seite (max. 50, Standard 20)                            |

Gibt Identitätsfelder zurück (ID, Kundennummer, Anzeigename, Typ, Status), keine Adressen oder Kontaktdaten.

***

#### `customer_create`

Legt einen neuen Kunden an. Typ Firma: `companyName` ist Pflicht. Typ Privatperson: `firstName` und `lastName` sind Pflicht. Ohne `customerNumber` wird die Nummer automatisch vergeben (Normalfall).

Vor der Anlage wird geprüft, ob ein Kunde mit gleicher E-Mail oder gleichem Firmennamen bereits existiert. Wenn ja, gibt das Tool den vorhandenen Kunden zurück (`status: "duplicate_warning"`) und legt keinen zweiten an. Mit `allowDuplicate: true` lässt sich die Anlage trotzdem erzwingen. Fehlen Pflichtfelder, kommen die Fehlermeldungen feldbezogen zurück (`status: "validation_error"`).

| Parameter        | Typ     | Pflicht | Beschreibung                                         |
| ---------------- | ------- | ------- | ---------------------------------------------------- |
| `email`          | string  | ja      | Rechnungs- und Kommunikations-E-Mail                 |
| `companyName`    | string  |         | Firmenname (Pflicht für Firmenkunden)                |
| `firstName`      | string  |         | Vorname (Pflicht für Privatpersonen)                 |
| `lastName`       | string  |         | Nachname (Pflicht für Privatpersonen)                |
| `gender`         | string  |         | `male`, `female` oder `diverse`                      |
| `vatId`          | string  |         | USt-IdNr., z. B. `DE123456789`                       |
| `phone`          | string  |         | Telefonnummer                                        |
| `street`         | string  |         | Straße                                               |
| `houseNumber`    | string  |         | Hausnummer                                           |
| `zip`            | string  |         | Postleitzahl                                         |
| `city`           | string  |         | Ort                                                  |
| `countryCode`    | string  |         | ISO-3166-1 alpha-2, z. B. `DE` (Standard `DE`)       |
| `addition`       | string  |         | Adresszusatz                                         |
| `invoiceEmail`   | string  |         | Separate Rechnungs-E-Mail                            |
| `customerNumber` | string  |         | Kundennummer (ohne Angabe automatisch vergeben)      |
| `language`       | string  |         | `de` oder `en` (ohne Angabe aus dem Land abgeleitet) |
| `currencyCode`   | string  |         | Währungscode, z. B. `EUR`                            |
| `timeZone`       | string  |         | Zeitzone, z. B. `Europe/Berlin`                      |
| `taxExempt`      | string  |         | `auto` oder `exempt` (Standard `auto`)               |
| `allowDuplicate` | boolean |         | `true` erzwingt die Anlage trotz Dublettenverdacht   |

Gibt `{ status, customer, nextSteps }` zurück. Berechtigung: `customer:write`.

***

#### `customer_update`

Aktualisiert die Stammdaten eines bestehenden Kunden. Nur mitgesendete Felder werden geändert; fehlende Felder bleiben unverändert. Kundennummer, DATEV-Debitorenkonto und Vertriebskanal-Bezug können nicht geändert werden. Adresse, Rechnungs-E-Mail und Kundenstatus (Archivierung) sind nicht Teil dieses Stammdaten-Updates.

| Parameter      | Typ    | Pflicht | Beschreibung                                |
| -------------- | ------ | ------- | ------------------------------------------- |
| `customerId`   | string | ja      | UUID des zu ändernden Kunden                |
| `companyName`  | string |         | Neuer Firmenname                            |
| `firstName`    | string |         | Neuer Vorname                               |
| `lastName`     | string |         | Neuer Nachname                              |
| `vatId`        | string |         | Neue USt-IdNr.                              |
| `phone`        | string |         | Neue Telefonnummer                          |
| `language`     | string |         | Neue Sprache (`de` oder `en`)               |
| `currencyCode` | string |         | Neuer Währungscode                          |
| `countryCode`  | string |         | Neues Land (ISO-3166-1 alpha-2)             |
| `timeZone`     | string |         | Neue Zeitzone                               |
| `gender`       | string |         | Neue Anrede (`male`, `female`, `diverse`)   |
| `taxExempt`    | string |         | Neue Steuerbefreiung (`auto` oder `exempt`) |

Gibt `{ status, customer, nextSteps }` zurück. Berechtigung: `customer:write`.

***

#### `customer_balance`

Liefert den Debitorensaldo eines Kunden. Ohne Zeitraum den aktuellen Gesamtsaldo, mit Zeitraum zusätzlich Soll-/Haben-Summen. Beträge sind in Cent mit Währungsangabe.

| Parameter    | Typ    | Pflicht | Beschreibung                                                 |
| ------------ | ------ | ------- | ------------------------------------------------------------ |
| `customerId` | string | ja      | UUID des Kunden                                              |
| `yearMonth`  | string |         | Monat im Format `YYYY-MM`, z. B. `2026-01`                   |
| `from`       | string |         | Untere Datumsgrenze `YYYY-MM-DD` (alternativ zu `yearMonth`) |
| `to`         | string |         | Obere Datumsgrenze `YYYY-MM-DD` (alternativ zu `yearMonth`)  |

***

#### `customer_payments`

Listet Zahlungstransaktionen eines Kunden, neueste zuerst. Enthält Datum, Betrag (Cent), Status, Zahlungsart und Belegnummer, jedoch keine Bankdaten oder IBAN.

| Parameter    | Typ     | Pflicht | Beschreibung                              |
| ------------ | ------- | ------- | ----------------------------------------- |
| `customerId` | string  | ja      | UUID des Kunden                           |
| `dateFrom`   | string  |         | Untere Datumsgrenze `YYYY-MM-DD`          |
| `dateTo`     | string  |         | Obere Datumsgrenze `YYYY-MM-DD`           |
| `page`       | integer |         | Seitennummer (Standard 1)                 |
| `limit`      | integer |         | Treffer pro Seite (max. 100, Standard 25) |

***

### Abonnements

Die Abo-Tools sind rein lesend und dienen dazu, den aktuellen Bestand einzusehen, bevor mit `update_subscription_prices` Preise angepasst werden. Alle Ergebnisse sind auf die Organisation beschränkt. Berechtigung: `subscription:read`.

#### `subscription_search`

Sucht Abonnements der Organisation. Menschliche Bezeichner werden aufgelöst: statt der Kunden-UUID kann die Kundennummer angegeben werden.

| Parameter            | Typ     | Pflicht | Beschreibung                                                                   |
| -------------------- | ------- | ------- | ------------------------------------------------------------------------------ |
| `customerId`         | string  |         | UUID des Kunden, dessen Abos gesucht werden                                    |
| `customerNumber`     | string  |         | Kundennummer (Alternative zu `customerId`)                                     |
| `subscriptionNumber` | string  |         | Abonummer (exakter Treffer)                                                    |
| `status`             | string  |         | Abo-Status, z. B. `active`, `cancelled`, `paused`                              |
| `productId`          | string  |         | UUID eines Produkts, findet Abos mit mindestens einer Position dieses Produkts |
| `page`               | integer |         | Seitennummer (Standard 1)                                                      |
| `limit`              | integer |         | Treffer pro Seite (max. 50, Standard 20)                                       |

Gibt pro Treffer zurück: ID, Nummer, Kunde (ID, Kundennummer, Anzeigename), Status, Vertragsbeginn/-ende, Abrechnungsintervall, Anzahl Positionen und den wiederkehrenden Netto-Monatsbetrag. Beträge als `{ amount, currency }`.

***

#### `subscription_get`

Liest ein Abonnement im Detail. Entweder `subscriptionId` (UUID) oder `subscriptionNumber` (Abonummer) angeben.

| Parameter            | Typ    | Pflicht | Beschreibung                                |
| -------------------- | ------ | ------- | ------------------------------------------- |
| `subscriptionId`     | string |         | UUID des Abonnements                        |
| `subscriptionNumber` | string |         | Abonummer (Alternative zu `subscriptionId`) |

Gibt zurück: Kopfdaten (ID, Nummer, Status, Kunde, Vertragsbeginn/-ende, Abrechnungsintervall, PO-Nummer, Probelaufende), Vertragsperioden (Anzahl, Laufzeit, Kündigungsfrist), Summen (Anzahl Positionen, wiederkehrender Netto-Monatsbetrag) und eine kompakte Positionsübersicht. Vollständige Positionsdetails liefert `subscription_items`.

***

#### `subscription_items`

Liest die Positionen eines Abonnements im Detail. Gleiche Eingabe wie `subscription_get`.

| Parameter            | Typ    | Pflicht | Beschreibung                                |
| -------------------- | ------ | ------- | ------------------------------------------- |
| `subscriptionId`     | string |         | UUID des Abonnements                        |
| `subscriptionNumber` | string |         | Abonummer (Alternative zu `subscriptionId`) |

Gibt je Position zurück: ID, Status, Produkt, Preisplan, Preismodell, Menge, Stückpreis (null bei tiered/volume/percentage), wiederkehrender Netto-Monatsbetrag, Rabatte (Name, Typ, Prozent, Fixbetrag, Frequenz, Befristung, Status) und Laufzeitfenster.

***

#### `update_subscription_prices`

Bereitet eine Preisänderung für **alle passenden Abos eines Kunden** vor und legt eine Freigabe-Aufgabe in der App-Inbox an. Die Preise werden dabei **nicht** direkt geändert.

Ein typischer Auftrag lautet: „Setze alle Abos von Kunde XY auf 0,89 € monatlich." Da sich das Abrechnungsintervall eines laufenden Abos nicht ändern lässt, erfolgt die Anpassung als Transfer-Leistung: Das Intervall bleibt bestehen, nur der Betrag wird angepasst. Ein jährlich abgerechnetes Abo wird auf das Zwölffache des Monatspreises gesetzt (0,89 € monatlich ergeben 10,68 € jährlich), ein monatliches auf den Monatspreis selbst. Der monatlich wiederkehrende Umsatz (MRR) wird dabei direkt fortgeschrieben.

Geändert werden nur laufende, wiederkehrende Positionen mit festem Preis (Flat Fee) oder Preis pro Einheit (Per Unit) in der Zielwährung; der Preistyp bleibt dabei erhalten. Bei Per-Unit-Positionen wird der Preis pro Einheit gesetzt, die monatliche MRR ergibt sich aus Menge mal Einheitspreis. Alle übrigen Positionen werden mit Begründung als übersprungen ausgewiesen und bleiben unverändert.

Der Ablauf ist zweistufig: Der KI-Assistent erstellt die Vorschau und die Freigabe-Aufgabe, ein Mensch prüft und genehmigt sie anschließend in der App-Inbox. Erst nach der manuellen Freigabe werden die Preise tatsächlich geändert. Ändern sich die Abos des Kunden zwischen Anfrage und Freigabe, wird die Freigabe abgelehnt und muss neu angefordert werden. Freigabe-Anfragen verfallen 72 Stunden nach der Erstellung.

| Parameter               | Typ    | Pflicht | Beschreibung                                                                                                      |
| ----------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `customerId`            | string | ja      | UUID des Kunden                                                                                                   |
| `targetMonthlyNetPrice` | number | ja      | Monatlicher Netto-Zielpreis in Euro (z. B. `0.89`). Jährlich abgerechnete Abos werden auf das Zwölffache gesetzt. |
| `currency`              | string |         | ISO-Währungscode (Standard: Währung des Kunden). Abos mit abweichender Währung werden übersprungen.               |

Gibt `{ actionItemId, status: "pending_approval", customerId, targetMonthlyNetPrice, currency, summary, hint }` zurück. `summary` enthält die Kundendaten, die Anzahl der zu ändernden und der übersprungenen Positionen sowie je Position das Produkt, das Abrechnungsintervall, den bisherigen und den neuen Betrag, die bisherige und die neue monatliche MRR und das Datum, ab dem die Änderung gilt. Gibt es keine passende Position, kommt eine klare Fehlermeldung und es wird keine Aufgabe angelegt. Mit `pending_action_status` (Parameter `actionItemId`) fragst du den Freigabestatus ab. Berechtigung: `subscription:write`.

***

### Rechnungen

#### `invoice_search`

Sucht Belege (Rechnungen, Gutschriften, Stornos). Filterbar nach Status, Belegtyp, Kunde und Finalisierungszeitraum. Beträge in Cent, Daten als ISO-8601.

| Parameter         | Typ     | Pflicht | Beschreibung                                                                   |
| ----------------- | ------- | ------- | ------------------------------------------------------------------------------ |
| `search`          | string  |         | Teiltreffer auf Belegnummer oder Kundennummer                                  |
| `statuses`        | array   |         | Belegstatus, z. B. `["STATUS_PAID", "STATUS_UNPAID"]`                          |
| `type`            | string  |         | Belegtyp: `TYPE_INVOICE`, `TYPE_CREDIT`, `TYPE_CANCEL`, `TYPE_REFUND`          |
| `customerId`      | string  |         | UUID des Kunden                                                                |
| `finalizedAfter`  | string  |         | Untere Datumsgrenze `YYYY-MM-DD`                                               |
| `finalizedBefore` | string  |         | Obere Datumsgrenze `YYYY-MM-DD`                                                |
| `sort`            | string  |         | Sortierfeld: `finalizationDate`, `number`, `dueDate`, `creationDate`, `status` |
| `sortDirection`   | string  |         | `asc` oder `desc` (Standard `desc`)                                            |
| `page`            | integer |         | Seitennummer (Standard 1)                                                      |
| `limit`           | integer |         | Treffer pro Seite (max. 100, Standard 20)                                      |

***

#### `invoice_reference_chain`

Löst die Storno-/Referenzkette eines Belegs auf. Gibt den Beleg selbst, den referenzierten Ursprungsbeleg sowie alle Stornos/Gutschriften zurück, die auf diesen Beleg verweisen.

| Parameter       | Typ    | Pflicht | Beschreibung                            |
| --------------- | ------ | ------- | --------------------------------------- |
| `invoiceId`     | string |         | UUID des Belegs                         |
| `invoiceNumber` | string |         | Belegnummer (alternativ zu `invoiceId`) |

***

#### `invoice_pdf_download`

Erstellt einen zeitlich begrenzten Download-Link für die PDF-Datei eines Belegs. Gibt `url`, `filename` und `expiresAt` zurück, keine Binärdaten.

| Parameter      | Typ     | Pflicht | Beschreibung                                             |
| -------------- | ------- | ------- | -------------------------------------------------------- |
| `invoiceId`    | string  | ja      | UUID des Belegs                                          |
| `secondsValid` | integer |         | Gültigkeitsdauer in Sekunden (60 bis 3600, Standard 300) |

***

#### `invoices_zip_download`

Bündelt die PDFs mehrerer Belege in ein ZIP-Archiv und gibt einen signierten Download-Link zurück. Belege ohne PDF werden übersprungen.

| Parameter         | Typ    | Pflicht | Beschreibung                                     |
| ----------------- | ------ | ------- | ------------------------------------------------ |
| `finalizedAfter`  | string |         | Untere Datumsgrenze `YYYY-MM-DD`                 |
| `finalizedBefore` | string |         | Obere Datumsgrenze `YYYY-MM-DD`                  |
| `statuses`        | array  |         | Belegstatus-Filter                               |
| `type`            | string |         | Belegtyp-Filter                                  |
| `customerId`      | string |         | UUID des Kunden                                  |
| `zipName`         | string |         | Optionaler Name des ZIP-Archivs ohne Dateiendung |

### Rechnungen erstellen und bearbeiten

Die schreibenden Rechnungs-Tools erfordern die Berechtigung `invoice:write`. Eine Rechnung durchläuft dabei einen klaren Lebenszyklus: Anlegen als Entwurf, Positionen hinzufügen und bearbeiten, und schließlich Finalisieren oder Schließen. Eine finalisierte Rechnung ist unveränderlich und rechtlich bindend; für die Finalisierung ist daher eine manuelle Freigabe durch einen Menschen erforderlich.

#### `invoice_create`

Legt eine neue Rechnung im Status Entwurf an. Positionen werden nicht hier, sondern anschließend mit `invoice_add_position` oder `invoice_add_product_position` hinzugefügt.

| Parameter      | Typ    | Pflicht | Beschreibung                                                                                      |
| -------------- | ------ | ------- | ------------------------------------------------------------------------------------------------- |
| `customerId`   | string | ja      | UUID des Kunden. Der Kunde muss aktiv sein.                                                       |
| `currencyCode` | string |         | Währungscode, z. B. `"EUR"`. Ohne Angabe die Standardwährung des Kunden.                          |
| `dueDate`      | string |         | Fälligkeitsdatum im Format `YYYY-MM-DD`. Ohne Angabe die Standard-Zahlungsfrist der Organisation. |
| `title`        | string |         | Rechnungstitel. Ohne Angabe der Titel aus der Standard-Rechnungsvorlage.                          |
| `introduction` | string |         | Einleitungstext.                                                                                  |
| `closing`      | string |         | Schlusstext.                                                                                      |
| `internalNote` | string |         | Interne Notiz (nicht auf dem Beleg sichtbar).                                                     |

Gibt die neue Entwurfs-Rechnung mit Kopfdaten, Positionen und Summen (in Cent) zurück.

***

#### `invoice_get`

Liest eine Rechnung mit Kopfdaten, Positionen und Summen. Die Rechnungs-ID kann eine UUID oder eine Belegnummer sein.

| Parameter   | Typ    | Pflicht | Beschreibung                            |
| ----------- | ------ | ------- | --------------------------------------- |
| `invoiceId` | string | ja      | UUID der Rechnung oder die Belegnummer. |

Gibt zurück: Kopfdaten (id, number, status, type, customer, currencyCode, dueDate, finalizedAt, title, introduction, closing, internalNote), Summen (`totals.net`/`tax`/`gross` in Cent), Positionen und ein `editable`-Kennzeichen.

***

#### `invoice_update`

Aktualisiert die Kopf-Felder einer noch nicht finalisierten Rechnung. Nur mitgesendete Felder werden geändert; fehlende Felder bleiben unverändert.

| Parameter           | Typ    | Pflicht | Beschreibung                                                    |
| ------------------- | ------ | ------- | --------------------------------------------------------------- |
| `invoiceId`         | string | ja      | UUID der Rechnung.                                              |
| `title`             | string |         | Neuer Titel.                                                    |
| `introduction`      | string |         | Neuer Einleitungstext.                                          |
| `closing`           | string |         | Neuer Schlusstext.                                              |
| `internalNote`      | string |         | Interne Notiz.                                                  |
| `dueDate`           | string |         | Fälligkeitsdatum im Format `YYYY-MM-DD`.                        |
| `customerAddressId` | string |         | UUID einer bestehenden Kundenadresse als neue Rechnungsadresse. |
| `paymentMethodId`   | string |         | UUID einer bestehenden Zahlungsart des Kunden.                  |

Gibt die aktualisierte Rechnung zurück (gleiche Struktur wie `invoice_get`).

***

#### `invoice_add_position`

Fügt einer Entwurfs-Rechnung eine frei definierte Position hinzu. Preis und Steuergruppe sind immer explizit anzugeben.

| Parameter            | Typ    | Pflicht | Beschreibung                                                                 |
| -------------------- | ------ | ------- | ---------------------------------------------------------------------------- |
| `invoiceId`          | string | ja      | UUID der Entwurfs-Rechnung.                                                  |
| `name`               | string | ja      | Bezeichnung der Position.                                                    |
| `unitId`             | string | ja      | UUID der Einheit.                                                            |
| `unitPrice`          | string | ja      | Netto-Einzelpreis als String im Format `"12.34"` (Punkt als Trennzeichen).   |
| `taxGroupId`         | string | ja      | UUID der Steuergruppe.                                                       |
| `quantity`           | number |         | Menge (Standard 1, kann negativ sein).                                       |
| `description`        | string |         | Optionale Positionsbeschreibung.                                             |
| `discountPercentage` | number |         | Rabatt in Prozent (0-100). Schließt `discountFixed` aus.                     |
| `discountFixed`      | string |         | Fester Netto-Rabatt als String `"12.34"`. Schließt `discountPercentage` aus. |
| `serviceDateFrom`    | string |         | Leistungszeitraum-Beginn `YYYY-MM-DD`. Nur gemeinsam mit `serviceDateTo`.    |
| `serviceDateTo`      | string |         | Leistungszeitraum-Ende `YYYY-MM-DD`. Nur gemeinsam mit `serviceDateFrom`.    |
| `productId`          | string |         | UUID eines Produkts für Statistikzwecke (keine Preisableitung).              |

Gibt `{ positionId, invoice }` zurück, wobei `invoice` die aktualisierte Rechnung mit Summen in Cent enthält.

***

#### `invoice_add_product_position`

Leitet eine Rechnungsposition aus einem Produkt im Katalog ab. Bezeichnung, Einheit und Steuergruppe stammen aus dem Produkt; der Preis kommt entweder aus einem Flat-Fee-Preisplan oder aus einem expliziten Preis-Override.

<Info>
  Ein Preis wird nie geraten. Fehlt sowohl ein passender Preisplan als auch ein `unitPrice`-Override, lehnt das Tool die Anfrage mit einer klaren Fehlermeldung ab.
</Info>

| Parameter     | Typ    | Pflicht | Beschreibung                                                                 |
| ------------- | ------ | ------- | ---------------------------------------------------------------------------- |
| `invoiceId`   | string | ja      | UUID der Entwurfs-Rechnung.                                                  |
| `productId`   | string | ja      | UUID des Produkts, aus dem die Position abgeleitet wird.                     |
| `pricePlanId` | string |         | UUID eines Flat-Fee-Preisplans des Produkts für die Preisableitung.          |
| `unitPrice`   | string |         | Preis-Override als String `"12.34"`. Hat Vorrang vor dem Preisplan.          |
| `quantity`    | number |         | Menge (Standard 1).                                                          |
| `taxGroupId`  | string |         | Override der Steuergruppe (UUID). Ohne Angabe die Steuergruppe des Produkts. |
| `name`        | string |         | Override der Positionsbezeichnung. Ohne Angabe der Produktname.              |

Gibt `{ positionId, invoice }` zurück (Summen in Cent).

***

#### `invoice_update_position`

Aktualisiert eine Position einer bearbeitbaren Rechnung. Nur mitgesendete Felder werden geändert.

| Parameter            | Typ    | Pflicht | Beschreibung                                                                |
| -------------------- | ------ | ------- | --------------------------------------------------------------------------- |
| `invoiceId`          | string | ja      | UUID der Rechnung.                                                          |
| `positionId`         | string | ja      | UUID der zu ändernden Position.                                             |
| `name`               | string |         | Neuer Positionsname.                                                        |
| `quantity`           | number |         | Neue Menge.                                                                 |
| `unitPrice`          | string |         | Neuer Netto-Einzelpreis als String `"12.34"`.                               |
| `taxGroupId`         | string |         | UUID der Steuergruppe.                                                      |
| `description`        | string |         | Neue Positionsbeschreibung.                                                 |
| `discountPercentage` | number |         | Rabatt in Prozent (0-100). Schließt `discountFixed` aus.                    |
| `discountFixed`      | string |         | Fester Netto-Rabatt als String `"5.00"`. Schließt `discountPercentage` aus. |
| `serviceDateFrom`    | string |         | Leistungsdatum von (`YYYY-MM-DD`).                                          |
| `serviceDateTo`      | string |         | Leistungsdatum bis (`YYYY-MM-DD`).                                          |

Gibt `{ positions[], totals }` zurück (Beträge in Cent).

***

#### `invoice_remove_position`

Entfernt eine Position von einer bearbeitbaren Rechnung. Die verbleibenden Positionen werden neu nummeriert und die Summen neu berechnet.

| Parameter    | Typ    | Pflicht | Beschreibung                       |
| ------------ | ------ | ------- | ---------------------------------- |
| `invoiceId`  | string | ja      | UUID der Rechnung.                 |
| `positionId` | string | ja      | UUID der zu entfernenden Position. |

Gibt `{ positions[], totals }` zurück (Beträge in Cent).

***

#### `invoice_close`

Schließt eine Rechnung endgültig, ohne sie zu finalisieren. Der Beleg erhält den Status `STATUS_CLOSED` und wird verworfen: keine Belegnummer, kein PDF, keine Zahlung. Nur aus den Status Entwurf (`STATUS_DRAFT`) oder `STATUS_NEW` heraus möglich.

| Parameter   | Typ    | Pflicht | Beschreibung                             |
| ----------- | ------ | ------- | ---------------------------------------- |
| `invoiceId` | string | ja      | UUID der Rechnung.                       |
| `reason`    | string |         | Optionaler Kommentar (max. 255 Zeichen). |

Gibt `{ id, status }` zurück.

***

#### `invoice_finalize`

Bereitet die Finalisierung einer Rechnung vor und legt eine Freigabe-Aufgabe in der App-Inbox an. Die Rechnung wird dabei **nicht** direkt finalisiert.

Da eine finalisierte Rechnung rechtlich bindend und unveränderlich ist, läuft die Finalisierung zweistufig ab: Der KI-Assistent prüft, ob die Rechnung finalisierbar ist (gültige Zahlungsart, aktiver Kunde), und legt dann eine Freigabe-Aufgabe an. Ein Mensch prüft und genehmigt diese anschließend in der App-Inbox. Erst nach der manuellen Freigabe wird die Rechnung tatsächlich finalisiert.

Ein zweiter Aufruf für dieselbe Rechnung liefert die bereits vorhandene offene Aufgabe zurück, sofern die Rechnung seit der ersten Anfrage nicht verändert wurde; die Parameter der ursprünglichen Anfrage bleiben dabei bestehen. Wurde die Rechnung geändert, wird die alte Aufgabe verworfen und eine neue mit neuer `actionItemId` angelegt. Freigabe-Anfragen verfallen 72 Stunden nach der Erstellung und müssen dann erneut gestellt werden.

| Parameter   | Typ     | Pflicht | Beschreibung                                                                                                |
| ----------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `invoiceId` | string  | ja      | UUID der Rechnung.                                                                                          |
| `dueDate`   | string  |         | Fälligkeitsdatum im Format `YYYY-MM-DD`. Ohne Angabe gilt die Standard-Zahlungsfrist bei der Finalisierung. |
| `sendEmail` | boolean |         | Ob bei der Freigabe eine E-Mail an den Kunden gesendet wird (Standard: `true`).                             |

Gibt `{ actionItemId, status: "pending_approval", invoiceId, summary, hint }` zurück, wobei `summary` Gesamtbeträge (Netto, Steuer, Brutto in Cent), Anzahl Positionen und Kundendaten enthält, und `hint` den Hinweis auf die notwendige manuelle Freigabe in der Inbox. Mit `pending_action_status` (Parameter `actionItemId`) kannst du den Freigabestatus und das Ablaufdatum abfragen. Berechtigung: `invoice:finalize`.

***

#### `pending_action_status`

Fragt den Status einer Freigabe-Aufgabe ab, zum Beispiel einer per `invoice_finalize` angelegten Rechnungsfreigabe.

| Parameter      | Typ    | Pflicht | Beschreibung                                      |
| -------------- | ------ | ------- | ------------------------------------------------- |
| `actionItemId` | string | ja      | UUID der Freigabe-Aufgabe aus `invoice_finalize`. |

Gibt `{ id, type, status, createdAt, resolvedAt, expiresAt, invoiceId, executions }` zurück. `expiresAt` ist der Zeitpunkt (UTC), zu dem die Freigabe-Anfrage abläuft; danach muss sie per `invoice_finalize` neu angefordert werden.

Mögliche Werte für `status`: `open`, `snoozed`, `in_progress`, `resolved`, `dismissed`.

Jeder Eintrag in `executions` enthält `actionKey` (z. B. `approve` oder `reject`), `resultStatus` (`success` oder `failure`), `resultMessage` und `executedAt`. Bei erfolgreicher Freigabe steht in `resultMessage` die vergebene Belegnummer. Schlägt die Freigabe fehl, weil die Rechnung nach der Anfrage geändert wurde oder die Anfrage abgelaufen ist, enthält `resultMessage` den Grund; die Rechnung bleibt in dem Fall unfinalisiert. Berechtigung: `action-item:read`.

***

#### `invoice_write_off_small_difference`

Bucht einen geringfügigen Restbetrag (Kleinstbetragsdifferenz) auf einer finalisierten, noch nicht bezahlten Rechnung aus, sodass die Rechnung als vollständig bezahlt gilt. Es wird keine E-Mail an den Kunden verschickt.

Voraussetzungen: Die Rechnung muss finalisiert und unbezahlt oder gemahnt sein. Der offene Betrag muss kleiner als der konfigurierte Kleinstbetrag-Schwellenwert sein und größer als 0.

| Parameter   | Typ    | Pflicht | Beschreibung                    |
| ----------- | ------ | ------- | ------------------------------- |
| `invoiceId` | string | ja      | UUID der finalisierten Rechnung |

Berechtigung: `invoice:write`.

***

## Rechnung mit KI erstellen und finalisieren: ein typischer Ablauf

So erstellst du mit einem KI-Assistenten eine vollständige Rechnung und sendest sie zur Freigabe:

<Steps>
  <Step title="Rechnung anlegen">
    Lege eine neue Rechnung für den gewünschten Kunden an:

    ```json theme={null}
    {
      "tool": "invoice_create",
      "arguments": {
        "customerId": "<KUNDEN-ID>",
        "title": "Leistungen Juli 2026",
        "dueDate": "2026-08-15"
      }
    }
    ```

    Die Antwort enthält die `invoiceId`, die du für alle weiteren Aufrufe benötigst.
  </Step>

  <Step title="Positionen hinzufügen">
    Füge Positionen aus dem Katalog oder frei definierte Positionen hinzu:

    ```json theme={null}
    {
      "tool": "invoice_add_product_position",
      "arguments": {
        "invoiceId": "<RECHNUNGS-ID>",
        "productId": "<PRODUKT-ID>",
        "pricePlanId": "<PREISPLAN-ID>",
        "quantity": 5
      }
    }
    ```

    Beachte: `unitPrice` kommt immer aus dem Preisplan oder einem expliziten Override, nie aus einer Schätzung.
  </Step>

  <Step title="Rechnung prüfen">
    Lies die aktuelle Rechnung mit allen Positionen und Summen, bevor du die Finalisierung anforderst:

    ```json theme={null}
    {
      "tool": "invoice_get",
      "arguments": { "invoiceId": "<RECHNUNGS-ID>" }
    }
    ```
  </Step>

  <Step title="Freigabe anfordern">
    Erstelle die Freigabe-Aufgabe. Die Rechnung wird **noch nicht** finalisiert:

    ```json theme={null}
    {
      "tool": "invoice_finalize",
      "arguments": {
        "invoiceId": "<RECHNUNGS-ID>",
        "sendEmail": true
      }
    }
    ```

    Die Antwort enthält `actionItemId`, `status: "pending_approval"`, eine Zusammenfassung der Rechnung und einen `hint`-Text. Informiere die Nutzerin oder den Nutzer, dass die Freigabe in der App-Inbox wartet.
  </Step>

  <Step title="Mensch prüft und gibt frei">
    Ein Mitarbeiter öffnet die Inbox, prüft die Rechnung und gibt sie frei oder lehnt sie ab. Dieser Schritt findet ausschließlich in der App statt und kann nicht durch den KI-Assistenten übersprungen werden.
  </Step>

  <Step title="Status abfragen">
    Frage den Freigabestatus ab, bis die Aufgabe bearbeitet wurde:

    ```json theme={null}
    {
      "tool": "pending_action_status",
      "arguments": { "actionItemId": "<AUFGABEN-ID>" }
    }
    ```

    Bei `status: "resolved"` und `executions[0].resultStatus: "success"` ist die Rechnung finalisiert; `resultMessage` enthält die Belegnummer. Bei `resultStatus: "failure"` wurde die Rechnung nicht finalisiert (z. B. weil sie nach der Anfrage geändert wurde); erstelle in dem Fall eine neue Freigabe-Anfrage.
  </Step>
</Steps>

<Warning>
  Eine genehmigte Rechnung ist rechtlich bindend und unveränderlich. Die manuelle Freigabe kann nicht aus dem MCP-Server heraus umgangen werden.
</Warning>

***

## Audit

Jeder Tool-Aufruf über den MCP-Server wird automatisch protokolliert: Nutzerkonto, Organisation, Tool-Name, Parameter (ohne sensible Inhalte), Ergebnis und Ausführungsdauer. Der Audit-Log ist unveränderlich und dient der Nachvollziehbarkeit für Compliance-Anforderungen. Auch fehlgeschlagene oder abgelehnte Aufrufe werden erfasst.

***

### DATEV

#### `datev_export_status`

Zeigt, ob ein DATEV-Cloud-Konto verbunden ist, und liefert für jeden Monat eine Zusammenfassung der exportierten und offenen Buchungen sowie den letzten Export-Status.

| Parameter    | Typ     | Pflicht | Beschreibung                                                           |
| ------------ | ------- | ------- | ---------------------------------------------------------------------- |
| `monthsBack` | integer |         | Anzahl Monate rückwärts für die Übersicht (1 bis 36, Standard 12)      |
| `yearMonth`  | string  |         | Monat `YYYY-MM`, für den die einzelnen Export-Läufe aufgelistet werden |

***

#### `datev_cloud_export_start`

Startet einen DATEV-Cloud-Export für einen oder mehrere Monate. Dieses Tool verändert Daten. Ohne `confirm: true` kommt eine Rückfrage zur Bestätigung zurück, es wird nichts ausgeführt.

| Parameter    | Typ     | Pflicht | Beschreibung                                                   |
| ------------ | ------- | ------- | -------------------------------------------------------------- |
| `yearMonth`  | string  |         | Einzelner Monat `YYYY-MM`                                      |
| `yearMonths` | array   |         | Liste von Monaten `YYYY-MM` (alternativ zu `yearMonth`)        |
| `confirm`    | boolean |         | Muss `true` sein, um den Export tatsächlich zu starten         |
| `sendAgain`  | boolean |         | Auch erneut senden, wenn bereits exportiert (Standard `false`) |

***

### Produktkatalog

#### `product_tree`

Liefert den Produktkatalog als Kategorie-Baum. Jeder Knoten enthält `id`, `name`, `path`, `count` (Anzahl Produkte) und `children`. Mit `includeProducts: true` zusätzlich eine flache Produktliste.

| Parameter         | Typ     | Pflicht | Beschreibung                                                        |
| ----------------- | ------- | ------- | ------------------------------------------------------------------- |
| `includeProducts` | boolean |         | Wenn `true`, zusätzlich eine flache Produktliste (Standard `false`) |
| `locale`          | string  |         | Sprache für Produkt- und Einheitennamen, z. B. `"de"` oder `"en"`   |

***

#### `product_search`

Sucht Produkte im Katalog. Teiltreffer auf Produktname, internen Namen und Produktnummer.

| Parameter         | Typ     | Pflicht | Beschreibung                                         |
| ----------------- | ------- | ------- | ---------------------------------------------------- |
| `query`           | string  |         | Suchbegriff                                          |
| `familyId`        | string  |         | UUID einer Produktkategorie                          |
| `includeArchived` | boolean |         | Archivierte Produkte einschließen (Standard `false`) |
| `limit`           | integer |         | Maximale Trefferzahl (max. 50, Standard 20)          |
| `offset`          | integer |         | Offset für die Paginierung (Standard 0)              |
| `locale`          | string  |         | Sprache für Namen, z. B. `"de"` oder `"en"`          |

***

#### `product_prices`

Liefert alle Preispläne eines Produkts in vollständiger Form. Die zurückgegebene Preisplan-ID ist genau die `pricePlan`-Referenz, die ein Angebots-Produkteintrag (`subscriptionProposal`) benötigt. Alle Beträge sind ganzzahlige Cent.

| Parameter   | Typ    | Pflicht | Beschreibung      |
| ----------- | ------ | ------- | ----------------- |
| `productId` | string | ja      | UUID des Produkts |

Je Preisplan wird zurückgegeben: `id`, `name`, `internalName`, `status`, `currency`, `chargeType`, `billingInterval`, `billingFrequency`, `payInAdvance`, `proRata`, `freeUnits`, `minimumCommitment` und ein `price`-Block mit den Beträgen in Cent.

***

### Angebote

Die Angebots-Tools sind in drei Gruppen aufgeteilt: Lesen, Inhalte aufbauen (Intent-Tools) und Zustellen. Lesende Tools benötigen `offer:read`, schreibende `offer:write`. Angenommene oder archivierte Angebote sind unveränderlich.

**Intent-Tools** (`offer_set_content`, `offer_add_section`, `offer_set_pricing`, `offer_set_parties`, `offer_set_signature`, `offer_set_letterhead`) nehmen fachliche Eingaben entgegen und lassen den Server die interne Dokument-Repräsentation aufbauen. Du schreibst dabei niemals Tiptap/ProseMirror-JSON und keine Preis-Snapshots von Hand. Jede Schreibantwort dieser Tools enthält das gerechnete Preis-View-Model, sodass du sofort siehst, ob Preise und Rabatte korrekt greifen.

**Zustellungs-Tools** (`offer_publish`, `offer_add_recipient`, `offer_list_recipients`, `offer_remove_recipient`, `offer_preview_link`, `offer_download_pdf`, `offer_activities`) verwalten den Versand an Empfänger. `offer_add_recipient` ist ausgehend: es verschickt eine echte E-Mail. Frage daher vor dem Aufruf ausdrücklich nach, ob an genau diese Person zugestellt werden soll.

#### `offer_block_types`

Listet alle unterstützten Block-Typen mit Metadaten auf (ob der Block atomar ist, ob er in PDF und Dokument erlaubt ist, und welche Attribute er akzeptiert). Mit optionalem `type` kommt zusätzlich ein konkretes Beispiel-Node zurück, das direkt an `offer_add_block` übergeben werden kann.

| Parameter | Typ    | Pflicht | Beschreibung                                           |
| --------- | ------ | ------- | ------------------------------------------------------ |
| `type`    | string |         | Block-Typ, z. B. `"heading"`, `"subscriptionProposal"` |

***

#### `offer_get`

Liest den Zustand eines Angebots effizient: Einstellungen (ID, Nummer, Name, Status, Anzeigesprache, Kunde, Gültigkeitsdatum, Annahme-Modus, Variablen) und eine kompakte Abschnitts- und Block-Übersicht. Mit `sectionIndex` (und optional `blockIndex`) wird zusätzlich der rohe JSON-Body genau dieses Abschnitts oder Blocks zurückgegeben.

| Parameter      | Typ     | Pflicht | Beschreibung                                     |
| -------------- | ------- | ------- | ------------------------------------------------ |
| `offerId`      | string  | ja      | ULID des Angebots                                |
| `sectionIndex` | integer |         | 0-basierter Abschnitts-Index für den rohen Body  |
| `blockIndex`   | integer |         | 0-basierter Block-Index innerhalb des Abschnitts |

***

#### `offer_create`

Legt ein neues Angebot an. Alle Parameter sind optional: ein Angebot ohne Kunde ist ausdrücklich erlaubt.

| Parameter        | Typ    | Pflicht | Beschreibung                                    |
| ---------------- | ------ | ------- | ----------------------------------------------- |
| `customerId`     | string |         | UUID des Kunden                                 |
| `name`           | string |         | Angebotstitel                                   |
| `locale`         | string |         | Anzeigesprache, z. B. `"de"`, `"en"`, `"de-DE"` |
| `validUntil`     | string |         | Gültigkeitsdatum ISO-8601, z. B. `2026-12-31`   |
| `salesChannelId` | string |         | UUID oder technischer Name des Vertriebskanals  |
| `templateId`     | string |         | UUID einer Angebotsvorlage                      |

***

#### `offer_update`

Aktualisiert die Einstellungen eines Angebots. Nur mitgesendete Felder werden geändert; fehlende Felder bleiben unverändert.

| Parameter         | Typ    | Pflicht | Beschreibung                                            |
| ----------------- | ------ | ------- | ------------------------------------------------------- |
| `offerId`         | string | ja      | ULID des Angebots                                       |
| `name`            | string |         | Neuer Angebotstitel                                     |
| `locale`          | string |         | Neue Anzeigesprache                                     |
| `validUntil`      | string |         | Neues Gültigkeitsdatum (leerer String löscht das Datum) |
| `acceptanceMode`  | string |         | `click`, `esignature` oder `print`                      |
| `customVariables` | object |         | Eigene Variablen als flaches Objekt                     |

***

#### `offer_add_block`

Fügt einen Block in einen Angebots-Abschnitt ein. Den gültigen Block-Node erhältst du über `offer_block_types`. Hat das Angebot noch keine Abschnitte, wird automatisch einer angelegt.

| Parameter      | Typ     | Pflicht | Beschreibung                                              |
| -------------- | ------- | ------- | --------------------------------------------------------- |
| `offerId`      | string  | ja      | ULID des Angebots                                         |
| `block`        | object  | ja      | Tiptap-Node mit `type` und optional `attrs`/`content`     |
| `sectionIndex` | integer |         | 0-basierter Abschnitts-Index (Standard 0)                 |
| `position`     | integer |         | Einfüge-Position im Abschnitt (Standard: am Ende anfügen) |

***

#### `offer_update_block`

Ersetzt einen bestehenden Block vollständig durch den übergebenen Tiptap-Node.

| Parameter      | Typ     | Pflicht | Beschreibung                 |
| -------------- | ------- | ------- | ---------------------------- |
| `offerId`      | string  | ja      | ULID des Angebots            |
| `sectionIndex` | integer | ja      | 0-basierter Abschnitts-Index |
| `blockIndex`   | integer | ja      | 0-basierter Block-Index      |
| `block`        | object  | ja      | Neuer Tiptap-Node            |

***

#### `offer_remove_block`

Entfernt einen Block aus einem Abschnitt; die nachfolgenden Blöcke rücken auf.

| Parameter      | Typ     | Pflicht | Beschreibung                 |
| -------------- | ------- | ------- | ---------------------------- |
| `offerId`      | string  | ja      | ULID des Angebots            |
| `sectionIndex` | integer | ja      | 0-basierter Abschnitts-Index |
| `blockIndex`   | integer | ja      | 0-basierter Block-Index      |

***

#### `offer_upload_image`

Lädt ein Bild für die Verwendung in Angeboten hoch. Erlaubt sind PNG, JPEG, WebP und GIF (max. 5 MB, dekodiert). Der MIME-Typ wird aus den Bilddaten erkannt; die Dateiendung wird entsprechend erzwungen. SVG wird abgelehnt. Die Antwort enthält `mediaId`, `url`, `filename` und einen fertigen `imageBlock`, der direkt an `offer_add_block` übergeben werden kann.

| Parameter  | Typ    | Pflicht | Beschreibung                                    |
| ---------- | ------ | ------- | ----------------------------------------------- |
| `filename` | string | ja      | Dateiname des Bilds                             |
| `data`     | string | ja      | Base64-kodierte Bilddaten (max. 5 MB dekodiert) |
| `altText`  | string |         | Alternativtext für das Bild                     |
| `title`    | string |         | Titel des Bilds                                 |

***

#### `offer_add_section`

Fügt dem Angebot einen neuen Textabschnitt aus Markdown hinzu. Der Server konvertiert Markdown in das Editor-Format; du schreibst nie Tiptap-JSON. Unterstützt werden Überschriften, Absätze, Fett/Kursiv, Listen, Tabellen (GFM) und Links.

| Parameter  | Typ    | Pflicht | Beschreibung                                                |
| ---------- | ------ | ------- | ----------------------------------------------------------- |
| `offerId`  | string | ja      | UUID des Angebots                                           |
| `heading`  | string |         | Optionale Abschnittsüberschrift (wird als H2 vorangestellt) |
| `markdown` | string | ja      | Abschnittsinhalt als Markdown                               |

Gibt die neue `sectionId` zurück (für spätere `offer_set_content`-Aufrufe).

***

#### `offer_set_content`

Setzt den Prosa-Inhalt eines bestehenden Abschnitts aus Markdown (ersetzt den Abschnitts-Body). Gleiche Markdown-Unterstützung wie `offer_add_section`. Für Positionen und Preise stattdessen `offer_set_pricing` nutzen.

| Parameter   | Typ    | Pflicht | Beschreibung                                                 |
| ----------- | ------ | ------- | ------------------------------------------------------------ |
| `offerId`   | string | ja      | UUID des Angebots                                            |
| `sectionId` | string | ja      | ID des Abschnitts (aus `offer_get` oder `offer_add_section`) |
| `markdown`  | string | ja      | Neuer Abschnittsinhalt als Markdown                          |

***

#### `offer_set_pricing`

Setzt die Positionen und Preise eines Angebots aus fachlicher Sicht (ersetzt den kompletten Preisblock). Preise als `{ "amount": "1500.00", "currency": "EUR" }` angeben, nie als Cent-Integer. `price` weglassen bedeutet Listenpreis des Preisplans. Befristete Rabatte über `discount.months`: der Server baut daraus intern zwei Positionen mit Vertragsfenstern.

Jede Schreibantwort enthält das gerechnete Preis-View-Model mit Positionen, Rabatt-Labels, Phasen, Summen und Vertragswert.

| Parameter       | Typ    | Pflicht | Beschreibung                                                                                                                                                                                        |
| --------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offerId`       | string | ja      | UUID des Angebots                                                                                                                                                                                   |
| `contractStart` | string | ja      | Vertragsbeginn als Kalenderdatum, z. B. `2026-09-01`                                                                                                                                                |
| `term`          | object |         | Laufzeit in Monaten: `{ months, cancellationMonths }`                                                                                                                                               |
| `currency`      | string |         | ISO-4217-Code, z. B. `EUR`                                                                                                                                                                          |
| `lines`         | array  | ja      | Positionen. Je Position: `productId`, `pricePlanId` (Pflicht), `quantity`, `name`, `price` (`{ amount, currency }`), `discount` (`{ percent }` oder `{ amount }`, optional `months` für Befristung) |

***

#### `offer_set_parties`

Setzt den Parteien-Block eines Angebots (Verkäufer, Käufer, Rechnungsempfänger, Referenz, Gültig-bis, PO-Nummer). Der Block wird automatisch angelegt, falls noch nicht vorhanden. Nur übergebene Felder werden geändert (Merge, kein Zurücksetzen). Datumsangaben als ISO-8601 mit Zeitzonen-Offset.

| Parameter    | Typ    | Pflicht | Beschreibung                            |
| ------------ | ------ | ------- | --------------------------------------- |
| `offerId`    | string | ja      | UUID des Angebots                       |
| `seller`     | object |         | Verkäufer-Partei                        |
| `buyer`      | object |         | Käufer-Partei                           |
| `billTo`     | object |         | Rechnungsempfänger-Partei               |
| `reference`  | string |         | Dokument-Referenz/Betreff               |
| `issueDate`  | string |         | Ausstellungsdatum (ISO-8601 mit Offset) |
| `validUntil` | string |         | Gültig-bis (ISO-8601 mit Offset)        |
| `poNumber`   | string |         | Bestellnummer des Käufers               |

***

#### `offer_set_signature`

Setzt den Signatur-Block eines Angebots (Modus, Partei-Beschriftungen, Annahmetext). Block wird automatisch angelegt. Nur übergebene Felder werden geändert. Den Annahme-Modus des Angebots (`click`, `esignature`, `print`) setzt du über `offer_update`.

| Parameter        | Typ     | Pflicht | Beschreibung                                  |
| ---------------- | ------- | ------- | --------------------------------------------- |
| `offerId`        | string  | ja      | UUID des Angebots                             |
| `mode`           | string  |         | Signatur-Modus des Blocks                     |
| `sellerLabel`    | string  |         | Beschriftung der Verkäufer-Unterschrift       |
| `buyerLabel`     | string  |         | Beschriftung der Käufer-Unterschrift          |
| `requireTitle`   | boolean |         | Titel/Position bei der Unterschrift verlangen |
| `acceptanceText` | string  |         | Annahmetext über der Unterschrift             |

***

#### `offer_set_letterhead`

Setzt den Briefkopf-Block eines Angebots (Logo und Breite). Block wird automatisch angelegt. Nur übergebene Felder werden geändert. Logo-ID erhältst du aus `offer_upload_image`.

| Parameter     | Typ     | Pflicht | Beschreibung                                   |
| ------------- | ------- | ------- | ---------------------------------------------- |
| `offerId`     | string  | ja      | UUID des Angebots                              |
| `logoMediaId` | string  |         | Medien-ID des Logos (aus `offer_upload_image`) |
| `logoWidth`   | integer |         | Logo-Breite in Pixel                           |
| `logoUrl`     | string  |         | Logo-URL (Alternative zu `logoMediaId`)        |

***

#### `offer_preview`

Gibt die gerechnete Angebots-Vorschau zurück (Proposal-View-Model). Rechnet denselben Calculator durch wie die Käuferansicht und der PDF-Druck: Positionen mit Stückpreis, Menge, Rabatt-Label und Betrag; Phasen mit Datumsbereich; Summen; Vertragswert. So lässt sich vor dem Versand prüfen, ob Preise und Rabatte korrekt greifen.

| Parameter | Typ    | Pflicht | Beschreibung                                                 |
| --------- | ------ | ------- | ------------------------------------------------------------ |
| `offerId` | string | ja      | UUID des Angebots                                            |
| `locale`  | string |         | Locale für Zahlen-/Datums-Labels, z. B. `de-DE` oder `en-US` |

Berechtigung: `offer:read`.

***

#### `offer_preview_link`

Gibt einen internen Vorschau-Link für ein Angebot zurück, ohne einen Empfänger anzulegen und ohne eine E-Mail zu verschicken. Rein lesend, keine Nebenwirkung. Nutze diesen Link zum Prüfen vor der Zustellung.

| Parameter | Typ    | Pflicht | Beschreibung      |
| --------- | ------ | ------- | ----------------- |
| `offerId` | string | ja      | UUID des Angebots |

***

#### `offer_publish`

Veröffentlicht ein Angebot. Erst nach der Veröffentlichung erhält ein Empfänger einen gültigen Link und kann die Einladungs-E-Mail erhalten.

Standardmäßig werden vorhandene Empfänger nicht benachrichtigt (`notifyRecipients: false`). Mit `notifyRecipients: true` wird eine E-Mail an bereits angelegte Empfänger verschickt (dann ausgehend). Greift ein Freigabe-Workflow, geht das Angebot nicht sofort live, sondern in den Status „Freigabe ausstehend" (`outcome: "pending_approval"` + `requestId`).

Veröffentlichen ist kundenwirksam und braucht eine menschliche Freigabe: Der erste Aufruf gibt `status: "confirmation_required"` mit einer Vorschau zurück und veröffentlicht nichts. Das Bestätigungs-Token steckt nicht in der Antwort, sondern nur in einer Freigabe-Karte, die ein Mensch bestätigt. Unterstützt der Client keine Freigabe-Karten, wird eine Freigabe-Aufgabe im Posteingang angelegt (`status: "pending_approval"`). Greifen zusätzlich die Freigabe-Regeln des Angebots, geht es auch nach der Bestätigung nicht sofort live, sondern in den bestehenden Freigabeprozess (`outcome: "pending_approval"` mit `requestId`), den die berechtigte Person abschließt.

| Parameter          | Typ     | Pflicht | Beschreibung                                                                             |
| ------------------ | ------- | ------- | ---------------------------------------------------------------------------------------- |
| `offerId`          | string  | ja      | UUID des Angebots                                                                        |
| `notifyRecipients` | boolean |         | Vorhandene Empfänger per E-Mail benachrichtigen (Standard `false`, bei `true` ausgehend) |
| `customMessage`    | string  |         | Persönliche Nachricht für die Benachrichtigung (nur mit `notifyRecipients: true`)        |
| `confirmToken`     | string  |         | Bestätigungs-Token aus der Freigabe-Karte                                                |

***

#### `offer_list_recipients`

Listet die Empfänger eines Angebots auf (an wen es bereits zugestellt wurde). Rein lesend, verschickt nichts.

| Parameter | Typ    | Pflicht | Beschreibung      |
| --------- | ------ | ------- | ----------------- |
| `offerId` | string | ja      | UUID des Angebots |

Gibt pro Empfänger zurück: `id`, `email`, `firstName`, `lastName`, `role` (`read`/`sign`/`countersigner`), `signingStatus` und den persönlichen Link. Berechtigung: `offer:read`.

***

#### `offer_add_recipient`

<Warning>
  Dieses Tool ist ausgehend: Bei einem bereits veröffentlichten Angebot verschickt es eine echte E-Mail an eine echte Person. Frage vor dem Aufruf ausdrücklich nach, ob an genau diese Adresse zugestellt werden soll.
</Warning>

Legt einen Empfänger an und stellt ihm das Angebot zu. Ist das Angebot noch nicht veröffentlicht, wird der Empfänger angelegt, aber keine E-Mail verschickt (`emailSent: false`); rufe dann zuerst `offer_publish` auf.

Bei einem veröffentlichten Angebot ist der Versand die einzige ausgehende, nicht umkehrbare Aktion und verlangt eine menschliche Freigabe. Der erste Aufruf gibt `status: "confirmation_required"` mit einer Vorschau zurück und versendet nichts. Das Bestätigungs-Token liegt bewusst nicht in der Modell-Antwort, sondern nur in einer Freigabe-Karte, die ein Mensch bestätigt. Unterstützt der Client keine Freigabe-Karten, wird stattdessen eine Freigabe-Aufgabe im Posteingang angelegt (`status: "pending_approval"` mit `actionItemId`); eine zweite Person gibt sie dort frei, woraufhin die Einladung tatsächlich versendet wird. Ein KI-Modell allein kann diesen Versand also nicht auslösen.

| Parameter      | Typ    | Pflicht | Beschreibung                                                                       |
| -------------- | ------ | ------- | ---------------------------------------------------------------------------------- |
| `offerId`      | string | ja      | UUID des Angebots                                                                  |
| `email`        | string | ja      | E-Mail-Adresse des Empfängers                                                      |
| `firstName`    | string |         | Vorname                                                                            |
| `lastName`     | string |         | Nachname                                                                           |
| `role`         | string |         | `read` (nur ansehen, Standard) oder `sign` (unterschreiben)                        |
| `confirmToken` | string |         | Bestätigungs-Token aus der Freigabe-Karte (nur bei veröffentlichtem Angebot nötig) |

Gibt zurück: Empfänger-Daten, `emailSent` (ob eine Mail rausging), `hint` und `nextSteps`. Berechtigung: `offer:write`.

***

#### `offer_remove_recipient`

Entfernt einen Empfänger von einem Angebot (verändernd, aber nicht ausgehend). Der Empfänger kann das Angebot danach nicht mehr über seinen Link aufrufen. Empfänger, die bereits unterschreiben oder unterschrieben haben, können nicht entfernt werden.

| Parameter     | Typ    | Pflicht | Beschreibung                                      |
| ------------- | ------ | ------- | ------------------------------------------------- |
| `offerId`     | string | ja      | UUID des Angebots                                 |
| `recipientId` | string | ja      | ULID des Empfängers (aus `offer_list_recipients`) |

***

#### `offer_download_pdf`

Rendert den aktuellen Stand eines Angebots als PDF und gibt einen zeitlich begrenzten Download-Link zurück. Keine Binärdaten in der Antwort, nur der Link. Das Angebot wird nicht verändert.

| Parameter      | Typ     | Pflicht | Beschreibung                                                       |
| -------------- | ------- | ------- | ------------------------------------------------------------------ |
| `offerId`      | string  | ja      | UUID des Angebots                                                  |
| `secondsValid` | integer |         | Gültigkeitsdauer des Links in Sekunden (60 bis 3600, Standard 300) |

Gibt `url`, `filename` und `expiresAt` (ISO-8601) zurück. Berechtigung: `offer:read`.

***

#### `offer_activities`

Liest das Aktivitätsprotokoll eines Angebots (geöffnet, angesehen, angenommen usw.). Rein lesend.

| Parameter | Typ    | Pflicht | Beschreibung      |
| --------- | ------ | ------- | ----------------- |
| `offerId` | string | ja      | UUID des Angebots |

Gibt eine chronologische Liste zurück (älteste zuerst): `id`, `type`, `occurredAt` (ISO-8601), `actor`, `metadata` und `links`. Das Protokoll ist nie leer (enthält mindestens „Angebot erstellt"). Berechtigung: `offer:read`.

***

<Tip>
  `offer_add_block` und `offer_update_block` bleiben als erweiterter Zugriff erhalten, wenn du genaue Kontrolle über den Tiptap-Node-Baum benötigst. Bevorzuge aber immer die Intent-Tools: sie schützen vor ungültigen Dokumentstrukturen und 0,00-Euro-Positionen.
</Tip>

***

## Angebote mit KI erstellen: ein typischer Ablauf

So erstellst du mit einem KI-Assistenten ein vollständiges Angebot und stellst es zu:

<Steps>
  <Step title="Kunden und Katalog auflösen">
    Suche den Kunden mit `customer_search`, um die UUID zu bestätigen. Suche dann das gewünschte Produkt mit `product_search` und lade die Preispläne mit `product_prices`.

    IDs nie raten. Die zurückgegebenen `productId` und `pricePlanId` benötigst du im Schritt „Positionen setzen".
  </Step>

  <Step title="Angebot anlegen">
    Lege ein leeres Angebot für den Kunden an:

    ```json theme={null}
    {
      "tool": "offer_create",
      "arguments": {
        "customerId": "<KUNDEN-ID>",
        "name": "Software-Paket 2026",
        "locale": "de",
        "validUntil": "2026-12-31"
      }
    }
    ```

    Die Antwort enthält die `offerId` für alle weiteren Aufrufe.
  </Step>

  <Step title="Textabschnitte hinzufügen">
    Füge Abschnitte als Markdown hinzu. Der Server konvertiert Markdown in das Editor-Format:

    ```json theme={null}
    {
      "tool": "offer_add_section",
      "arguments": {
        "offerId": "<ANGEBOTS-ID>",
        "heading": "Leistungsumfang",
        "markdown": "Wir liefern ...\n\n- Punkt 1\n- Punkt 2"
      }
    }
    ```

    Die Antwort enthält die `sectionId` für spätere Änderungen per `offer_set_content`.
  </Step>

  <Step title="Positionen und Preise setzen">
    Setze die Positionen über `offer_set_pricing`. Preise immer als Dezimalstring, nie als Cent-Integer. `price` weglassen bedeutet Listenpreis:

    ```json theme={null}
    {
      "tool": "offer_set_pricing",
      "arguments": {
        "offerId": "<ANGEBOTS-ID>",
        "contractStart": "2026-09-01",
        "term": { "months": 24, "cancellationMonths": 3 },
        "currency": "EUR",
        "lines": [
          {
            "productId": "<PRODUKT-ID>",
            "pricePlanId": "<PREISPLAN-ID>",
            "name": "Fynn Pro – Lizenz"
          },
          {
            "productId": "<ONBOARDING-PRODUKT-ID>",
            "pricePlanId": "<ONBOARDING-PLAN-ID>",
            "name": "Implementierung & Onboarding",
            "price": { "amount": "1500.00", "currency": "EUR" }
          }
        ]
      }
    }
    ```

    Die Antwort enthält direkt das gerechnete View-Model. Prüfe dort, ob alle Positionen erwartete Beträge zeigen und keine 0,00-Euro-Zeilen vorkommen.
  </Step>

  <Step title="Vorschau prüfen">
    Rufe `offer_preview_link` auf, um einen internen Vorschau-Link zu erhalten, ohne eine E-Mail zu verschicken. Alternativ liefert `offer_preview` das gerechnete View-Model direkt.

    Besprich das Ergebnis mit der Person und frage, ob das Angebot so versendet werden soll.
  </Step>

  <Step title="Angebot veröffentlichen">
    Veröffentliche das Angebot. Erst danach erhält ein Empfänger einen gültigen Link:

    ```json theme={null}
    {
      "tool": "offer_publish",
      "arguments": { "offerId": "<ANGEBOTS-ID>" }
    }
    ```

    Greift ein Freigabe-Workflow, gibt die Antwort `outcome: "pending_approval"` zurück. Ein Mensch muss die Freigabe in der App-Inbox bestätigen, bevor das Angebot live geht.
  </Step>

  <Step title="Empfänger einladen (nach ausdrücklicher Bestätigung)">
    Frage zuerst ausdrücklich, an welche Person zugestellt werden soll. Erst nach Bestätigung den Empfänger anlegen:

    ```json theme={null}
    {
      "tool": "offer_add_recipient",
      "arguments": {
        "offerId": "<ANGEBOTS-ID>",
        "email": "erika.musterfrau@beispiel.de",
        "firstName": "Erika",
        "lastName": "Musterfrau",
        "role": "sign"
      }
    }
    ```

    Die Antwort enthält `emailSent: true`, wenn die Einladungs-E-Mail rausgegangen ist, sowie den persönlichen Link des Empfängers.
  </Step>
</Steps>

<Info>
  Alle Angebots-Tools respektieren den Lebenszyklus: ein angenommenes oder archiviertes Angebot kann nicht mehr verändert werden. Prüfe den Status vorab mit `offer_get`.
</Info>

***

## Ressourcen

Neben Tools stellt der MCP-Server Ressourcen bereit. Ressourcen sind lesbare Datenobjekte mit einer festen URI: Ein KI-Client kann sie in seinen Kontext laden, ohne dafür einen Tool-Aufruf zu verbrauchen. Alle Ressourcen sind organisations-beschränkt.

| URI                                        | Inhalt                                                                                                                          |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `fynn://glossary`                          | Deutsche Fachbegriffe (Debitor, Mandant, PRAP, EXTF, GoBD, ZUGFeRD usw.)                                                        |
| `fynn://schema/price-plan`                 | Preisplan-Schemas pro Preistyp, wie `product_prices` sie zurückgibt                                                             |
| `fynn://schema/offer-block/{type}`         | Schema und Beispiel-Node eines bestimmten Block-Typs                                                                            |
| `fynn://schema/subscription-proposal-line` | Schema einer Angebotsposition (subscriptionProposal-Zeile)                                                                      |
| `fynn://guide/offer-authoring`             | Schritt-für-Schritt-Anleitung zum Aufbau eines Angebots                                                                         |
| `fynn://guide/pricing-and-discounts`       | Preiseinheiten, Preistypen, Rabattformen und häufige Fehler                                                                     |
| `fynn://guide/invoicing`                   | Belege anlegen, Positionen ergänzen, finalisieren; GoBD-Grenzen                                                                 |
| `fynn://guide/datev-export`                | DATEV-Cloud-Export-Ablauf: Voraussetzungen, Bestätigung, Status                                                                 |
| `fynn://catalog/products`                  | Aktive Produkte der Organisation (Katalogfelder), ohne Tool-Aufruf abrufbar                                                     |
| `fynn://catalog/price-plans/{productId}`   | Preispläne eines Produkts. Geld immer als Objekt `{amount, currency}` mit Dezimalstring in Euro                                 |
| `fynn://tenant/settings`                   | Konfiguration der Organisation: Firmenidentität, Adresse, Sprache, Zeitzone, Steuerberechnungsmodus                             |
| `fynn://offer/{offerId}`                   | Einstellungen und Abschnitts-Gliederung eines Angebots (lesend). Für die gerechneten Zahlen `fynn://offer/{offerId}/view-model` |
| `fynn://examples/offer/reference`          | Kopierbares Referenzbeispiel für die Angebots-Preisgestaltung über `offer_set_pricing`                                          |

Die dynamischen Ressourcen liefern dieselben Zahlen wie die passenden Tools, kosten aber keinen Tool-Aufruf. Geldbeträge folgen in `fynn://catalog/price-plans/{productId}` der einheitlichen Form `{"amount": "149.00", "currency": "EUR"}` (Dezimalstring in der Hauptwährungseinheit), damit ein aus der Ressource übernommener Preis ohne Umrechnung in `offer_set_pricing` passt.

### Autovervollständigung

Für die Platzhalter parametrisierter Ressourcen bietet der Server Vorschläge über `completion/complete` an. Ein Client kann so einen Wert vervollständigen, statt ihn zu raten:

| Platzhalter   | Ressource                                                     | Vorschläge                                                 |
| ------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
| `{type}`      | `fynn://schema/offer-block/{type}`                            | Bekannte Blocktypen aus der Registry                       |
| `{productId}` | `fynn://catalog/price-plans/{productId}`                      | Eigene Produkte (Treffer auf Name, interner Name, Nummer)  |
| `{offerId}`   | `fynn://offer/{offerId}`, `fynn://offer/{offerId}/view-model` | Eigene Angebote (Treffer auf Nummer, Name), neueste zuerst |

Die Vorschläge sind organisations-beschränkt und respektieren die Leserechte: Ohne die passende Berechtigung liefert die Vervollständigung eine leere Liste.

***

## Prompts

Der MCP-Server stellt zwei geführte Prompts bereit. Ein Prompt ist eine vorbereitete Anweisung, die ein KI-Client in seine Unterhaltung einbetten kann.

### `angebot_erstellen`

Geführter Ablauf zum Erstellen eines Angebots: Kunde auflösen, Katalog prüfen, Positionen schemasicher aufbauen, Konditionen setzen, Vorschau prüfen und Rückfrage vor dem Versand. Optionale Argumente: `kunde`, `produkte`, `laufzeit`, `rabatt`.

### `angebot_pruefen`

Prüft ein Angebot vor dem Versand anhand einer Checkliste: Summen plausibel, keine 0,00-Euro-Positionen, `validUntil` gesetzt, Empfänger vorhanden, Freigabe nötig? Pflichtargument: `offerId`.

***

## Fortschritt und Rückfragen

### Fortschrittsmeldungen

Länger laufende Tools (DATEV-Cloud-Export, PDF- und ZIP-Download) senden Fortschrittsmeldungen mit einem beschreibenden Text. Das geschieht nur, wenn der Client den Aufruf mit einem `progressToken` im `_meta`-Feld anfordert. Ohne `progressToken` bleibt die Antwort ein einfaches JSON-Objekt, es ändert sich nichts am Verhalten. Ein Client, der den Fortschritt sehen möchte, sendet im `tools/call` also zum Beispiel `"_meta": { "progressToken": "abc" }` und erhält die Antwort als Ereignis-Stream mit den Fortschrittsmeldungen vor dem Endergebnis.

### Bestätigung und Freigabe

Aktionen mit echter Außenwirkung sind durch eine serverseitige Rückfrage abgesichert. Statt einer interaktiven Nachfrage über das Protokoll (die über die zustandslose HTTP-Anbindung nicht sicher zurücklaufen kann) gibt es drei Stufen, je nach Fallhöhe der Aktion:

* **Einfache Bestätigung** (sichtbares Token): Der erste Aufruf gibt `status: "confirmation_required"` mit einem `confirmToken` und einer Vorschau zurück und führt nichts aus. Derselbe Aufruf mit unveränderten Argumenten und dem `confirmToken` löst die Aktion aus. Das schützt vor einer versehentlichen Ausführung bei geringer Fallhöhe.
* **Menschliche Freigabe** (zum Beispiel `offer_publish` und `offer_add_recipient` bei einem veröffentlichten Angebot): Der erste Aufruf gibt ebenfalls `status: "confirmation_required"` zurück, aber das Token liegt bewusst nicht in der Antwort, sondern nur in einer Freigabe-Karte, die im Client als eigenständige, abgeschottete Ansicht erscheint. Nur ein Mensch kann dort bestätigen; ein KI-Modell kann das Token nicht selbst erzeugen. Unterstützt der Client keine Freigabe-Karten, wird automatisch eine Freigabe-Aufgabe im Posteingang angelegt (`status: "pending_approval"`). Greifen beim Veröffentlichen zusätzlich die Freigabe-Regeln des Angebots, übernimmt der bestehende Freigabeprozess und die berechtigte Person gibt frei.
* **Vier-Augen-Freigabe im Posteingang** (zum Beispiel `invoice_finalize`, `update_subscription_prices`): Es entsteht immer eine Freigabe-Aufgabe (`status: "pending_approval"` mit `actionItemId`), die eine zweite Person im Posteingang der App freigibt oder ablehnt. Mit `pending_action_status` fragst du den Stand ab.

In allen Fällen wird ein Bestätigungs-Token abgelehnt und eine frische Vorschau ausgestellt, wenn sich der zugrunde liegende Zustand zwischen Rückfrage und Bestätigung geändert hat. So bleibt die Kontrolle beim Menschen, ohne dass der KI-Client eine Aktion mit Außenwirkung ungefragt auslöst.

`datev_cloud_export_start` nutzt weiterhin eine einfache `confirm: true`-Bestätigung.

### Listen und Änderungen

Die Listen-Methoden (`tools/list`, `resources/list`, `resources/templates/list`, `prompts/list`) sind paginiert: Der Server liefert bis zu 50 Einträge pro Seite und, falls mehr existieren, einen `nextCursor`. Ein Client sollte dem `nextCursor` folgen, bis keiner mehr zurückkommt. Der aktuelle Umfang liegt unter dieser Grenze, sodass in der Regel eine Seite genügt.

Der Server meldet keine nachträglichen Listen-Änderungen (`listChanged`). Der Satz an Tools, Ressourcen und Prompts steht beim Verbindungsaufbau fest und bleibt für die Dauer der Sitzung unverändert, daher gibt es nichts nachzumelden.


# MCP-Server
Source: https://docs.fynn.eu/guide/developers/mcp-server

Verbinde KI-Tools direkt mit deinen Fynn-Daten. Der Fynn MCP-Server stellt Kunden, Abonnements, Rechnungen, Angebote und den DATEV-Export als Werkzeuge bereit, die dein KI-Client aufruft.

Der **Fynn MCP-Server** verbindet KI-Tools mit deinen Fynn-Daten. MCP (Model Context Protocol) ist ein offener Standard, über den KI-Clients wie Claude Code, Claude Desktop oder andere MCP-fähige Anwendungen Werkzeuge aufrufen. Statt Antworten zu erfinden, fragt der KI-Client die echten Daten direkt bei Fynn ab: Kunden anlegen, Abonnements einsehen, Angebote erstellen und versenden, Rechnungen bearbeiten oder einen DATEV-Export anstoßen.

<Info>
  Endpunkt: `https://coreapi.io/portal/mcp` (Sandbox: `https://preview.coreapi.io/portal/mcp`). Die Verbindung läuft über den Streamable-HTTP-Transport der MCP-Spezifikation.
</Info>

## Verfügbare Werkzeuge

| Bereich        | Werkzeuge                                                                   |
| -------------- | --------------------------------------------------------------------------- |
| Kunden         | Suchen, anlegen, Stammdaten aktualisieren, Saldo und Zahlungen abrufen      |
| Abonnements    | Abos und ihre Positionen einsehen, Preise anpassen (mit Freigabe)           |
| Rechnungen     | Suchen, anlegen, bearbeiten, finalisieren (mit Freigabe), PDF herunterladen |
| Angebote       | Anlegen, Texte und Preise setzen, veröffentlichen, Empfänger einladen       |
| DATEV          | Export starten und Status abfragen                                          |
| Produktkatalog | Produkte und Preispläne suchen                                              |
| Allgemein      | Verbindung testen (Ping)                                                    |

Schreibende Werkzeuge sind deutlich als verändernd gekennzeichnet. Werkzeuge, die E-Mails an echte Personen verschicken, sind zusätzlich als ausgehend markiert und fragen vor dem Versand nach einer Bestätigung. Kritische Aktionen (Rechnungsfinalisierung, Preisänderungen) laufen zweistufig: der KI-Assistent bereitet vor, ein Mensch gibt in der App-Inbox frei.

## Zugriffs-Token in der App anlegen

Der MCP-Server authentifiziert sich mit einem persönlichen API-Token. Jeder Nutzer legt seine Token selbst an.

<Steps>
  <Step title="API-Tokens öffnen">
    Öffne in der App **Konto** und dort **API-Tokens**.
  </Step>

  <Step title="Token erstellen">
    Lege einen neuen Token an. Vergib einen sprechenden Namen, damit du später erkennst, wofür der Token gedacht ist, etwa nach Werkzeug oder Gerät.
  </Step>

  <Step title="Ablaufdatum setzen">
    Setze ein Ablaufdatum. So läuft der Token automatisch aus, falls du ihn vergisst.
  </Step>

  <Step title="Token kopieren">
    Der Token wird genau einmal angezeigt. Kopiere ihn sofort und speichere ihn sicher. Danach lässt er sich nicht mehr einsehen.
  </Step>
</Steps>

<Tip>
  Lege pro Werkzeug oder Gerät einen eigenen Token an. So kannst du einen einzelnen Zugang widerrufen, ohne die anderen zu unterbrechen.
</Tip>

Alternativ funktioniert auch ein organisationsweiter API-Schlüssel aus **Einstellungen > Entwickler > API-Schlüssel**. Ein solcher Schlüssel ist an die Organisation gebunden, nicht an einen einzelnen Nutzer.

## Claude Code anbinden

In Claude Code fügst du den Server mit einem Befehl hinzu. Ersetze `api_DEIN_TOKEN` durch deinen Token.

```bash theme={null}
claude mcp add --transport http fynn https://coreapi.io/portal/mcp \
  --header "Authorization: Bearer api_DEIN_TOKEN"
```

Danach stehen die Fynn-Werkzeuge in Claude Code zur Verfügung. Mit dem Ping-Werkzeug prüfst du, ob die Verbindung steht.

## Andere MCP-Clients anbinden

Viele MCP-Clients lesen ihre Serverliste aus einer `.mcp.json`. Trage den Fynn-Server als HTTP-Server ein und schicke deinen Token im `Authorization`-Header mit.

```json theme={null}
{
  "mcpServers": {
    "fynn": {
      "type": "http",
      "url": "https://coreapi.io/portal/mcp",
      "headers": {
        "Authorization": "Bearer api_DEIN_TOKEN"
      }
    }
  }
}
```

## Sicherheit und Berechtigungen

<Warning>
  Ein Token gibt Zugriff auf deine Fynn-Daten. Behandle ihn wie ein Passwort. Trage ihn nicht in geteilte Repositories ein und gib ihn nicht weiter.
</Warning>

* **Der Token trägt deine Rechte.** Er ist an deinen Benutzer gebunden und hat exakt die Berechtigungen, die du in der jeweiligen Organisation hast. Was du in der App nicht sehen oder bearbeiten darfst, liefert oder verändert auch der MCP-Server nicht.
* **Alle Ergebnisse sind organisationsgetrennt.** Ein Token gibt niemals Daten anderer Organisationen zurück.
* **Abgelaufene Token werden abgelehnt.** Nach dem Ablaufdatum funktioniert ein Token nicht mehr.
* **Schreibende Werkzeuge sind gekennzeichnet.** Jedes Tool, das Daten verändert, ist in der Beschreibung mit „ACHTUNG: verändernd" markiert. Ausgehende Aktionen (z. B. E-Mail an Empfänger) erfordern eine ausdrückliche Bestätigung, bevor sie ausgeführt werden.

### Zielorganisation wählen

Gehörst du zu mehreren Organisationen, kannst du die Zielorganisation über den zusätzlichen Header `X-Fynn-Tenant-Id` festlegen.

```bash theme={null}
claude mcp add --transport http fynn https://coreapi.io/portal/mcp \
  --header "Authorization: Bearer api_DEIN_TOKEN" \
  --header "X-Fynn-Tenant-Id: DEINE_ORGANISATIONS_ID"
```

Ohne diesen Header gilt deine Standard-Organisation. Bei einem organisationsweiten API-Schlüssel gilt immer dessen Organisation, der Header hat dann keine Wirkung.

## Token widerrufen

Vermutest du, dass ein Token in falsche Hände geraten ist, lösche ihn in der App unter **Konto > API-Tokens**. Ab dem nächsten Aufruf wird der Zugriff sofort abgelehnt. Erstelle bei Bedarf einen neuen Token und trage ihn in deinem MCP-Client ein.


# Vertriebskanäle über die API
Source: https://docs.fynn.eu/guide/developers/sales-channels

Wie Fynn den aktiven Vertriebskanal pro Request auflöst, wie du Kunden einem Kanal zuordnest, und die Endpunkte zum Verwalten von Kanälen, eigenen Domains und Branding.

Ein **Vertriebskanal** (Sales Channel) bildet eine Marke deiner Organisation ab und bestimmt Branding, Domain, erlaubte Zahlungsmethoden, Coupon-Verhalten und Kundenbereich. Diese Seite erklärt das Verhalten aus Entwicklersicht. Die fachliche Einführung findest du unter [Vertriebskanäle](/guide/tenant/sales-channels).

<Info>
  Jede Organisation hat **immer** einen Kanal mit dem technischen Namen `default`. Er ist der universelle Fallback und kann nicht gelöscht werden. Vertriebskanäle sind organisatorisch, sie isolieren **keine** Daten. Kunden, Subscriptions, Rechnungen, Produkte und Preise bleiben organisationsweit.
</Info>

<Note>
  In den Beispielen ist `$BASE_URL` die Basis-URL deiner Fynn-API und `$API_TOKEN` ein API-Token, das als `Authorization: Bearer` mitgeschickt wird.
</Note>

## Kanal-Auflösung

Fynn löst den aktiven Vertriebskanal **pro eingehendem Request** auf, nachdem der Tenant feststeht. Es gewinnt der erste Treffer in dieser Kette:

<Steps>
  <Step title="Header X-Sales-Channel-Id">
    Expliziter Kanal per Header `X-Sales-Channel-Id: <uuid>`. Wird für interne Wallet- und Tool-Zugriffe genutzt, wenn der Aufrufer den Kanal kennt.
  </Step>

  <Step title="Header X-Cart-Token">
    `X-Cart-Token: <token>` löst den Warenkorb auf; dessen Kanal stammt aus dem CheckoutLink. Das ist der reguläre Weg im Checkout der Kundenfront.
  </Step>

  <Step title="Domain (Host / Origin / Referer)">
    Der Host der Anfrage wird über die Customerfront-Domain zum Kanal aufgelöst. Bei Cross-Origin-Aufrufen der Kundenfront-SPA (der `Host` ist dann die API-Domain) wird zusätzlich `Origin`, dann `Referer`, dann `X-Source-Domain` herangezogen, dieselbe Header-Reihenfolge, mit der auch der Tenant aufgelöst wird.
  </Step>

  <Step title="Default-Kanal">
    Greift keiner der Schritte, wird der `default`-Kanal der Organisation verwendet.
  </Step>
</Steps>

<Warning>
  **Cross-Tenant-Guard:** Jeder aufgelöste Kanal wird gegen den Tenant des Requests geprüft. Gehört ein per Header oder Cart-Token referenzierter Kanal zu einer anderen Organisation, wird er still verworfen, und die Kette läuft zum nächsten Schritt weiter. Auf einen fremden Kanal fällt sie nie zurück.
</Warning>

Praktische Konsequenz: Verbindest du eine eigene Domain mit einem Kanal (siehe [Eigene Domains](#eigene-domains)), erreichen Aufrufe über diese Domain automatisch den richtigen Kanal, ohne dass du einen Header setzen musst. Eine Domain ist immer **genau einem** Kanal zugeordnet.

## Der `salesChannel` am Kunden

Jeder Kunde gehört genau einem Vertriebskanal an. Die Zuordnung steuert, welches Branding der Kunde in Bestätigungen, Dokumenten und im Self-Service sieht.

### Beim Anlegen und Aktualisieren (Eingabe)

Die Felder `POST /customers` und `PATCH /customers/{id}` akzeptieren ein optionales Feld `salesChannel`:

* Wert ist die **UUID** oder der **technische Name** des Kanals (zum Beispiel `"default"`).
* Der Kanal muss existieren und zur aktuellen Organisation gehören, andernfalls antwortet die API mit `422` und einer Validierungsmeldung am Feld.
* Lässt du das Feld bei der **Anlage** leer, weist Fynn den aktuell aufgelösten bzw. den `default`-Kanal zu.

```bash Kunde einem Kanal zuordnen theme={null}
curl -X POST "$BASE_URL/customers" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "companyName": "Acme GmbH",
    "salesChannel": "b2b-shop"
  }'
```

```bash Kanal eines Kunden ändern theme={null}
curl -X PATCH "$BASE_URL/customers/{id}" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "salesChannel": "default" }'
```

### In der Ausgabe (Lesen)

In Kunden-Antworten (sowie eingebettet in CheckoutLink, Cart und Webhook-Envelopes) erscheint der Kanal als kompakte Referenz:

```json theme={null}
{
  "id": "0f9b…",
  "companyName": "Acme GmbH",
  "salesChannel": {
    "id": "45d60990-cde6-4139-b64f-79b79c6c6d98",
    "name": "b2b-shop",
    "brandName": "Acme B2B"
  }
}
```

| Feld        | Bedeutung                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `id`        | UUID des Kanals.                                                                                |
| `name`      | Stabiler technischer Name (zum Beispiel `default`). Eindeutig pro Organisation, nicht änderbar. |
| `brandName` | Anzeigename der Marke für E-Mails, PDFs und Checkout.                                           |

## Vertriebskanäle verwalten

Die folgenden Endpunkte verwalten Kanäle und ihre Einstellungen. Sie erfordern ein API-Token mit der Berechtigung `sales-channel:read` (lesend) bzw. `sales-channel:write` (schreibend).

| Methode         | Pfad                                            | Zweck                                                             | Berechtigung                   |
| --------------- | ----------------------------------------------- | ----------------------------------------------------------------- | ------------------------------ |
| `GET`           | `/api/sales-channels`                           | Alle Kanäle der Organisation auflisten                            | `sales-channel:read`           |
| `POST`          | `/api/sales-channels`                           | Kanal anlegen                                                     | `sales-channel:write`          |
| `GET`           | `/api/sales-channels/{id}`                      | Einen Kanal abrufen                                               | `sales-channel:read`           |
| `PATCH`         | `/api/sales-channels/{id}`                      | Stammdaten, Coupons, Zahlungsmethoden, Weiterleitungs-URLs ändern | `sales-channel:write`          |
| `DELETE`        | `/api/sales-channels/{id}`                      | Kanal löschen (nur ohne Referenzen, nicht den `default`)          | `sales-channel:write`          |
| `PATCH`         | `/api/sales-channels/{id}/appearance`           | Logo, Farben, Rechtstexte ändern                                  | `sales-channel:write`          |
| `GET` · `PATCH` | `/api/sales-channels/{id}/customer-area`        | Kundenbereich lesen/ändern                                        | `sales-channel:read` · `write` |
| `GET` · `PATCH` | `/api/sales-channels/{id}/email-settings`       | Absender, Sendedomain, Mail-Vorlage                               | `sales-channel:read` · `write` |
| `GET` · `PATCH` | `/api/sales-channels/{id}/document-settings`    | Belegvorlagen (Logo-Position, Fußbereich)                         | `sales-channel:read` · `write` |
| `GET`           | `/api/sales-channels/{id}/domain`               | Standard-Domain des Kanals                                        | `sales-channel:read`           |
| `GET`           | `/api/sales-channels/payment-methods/available` | Verfügbare Zahlungsmethoden (aktive Gateways)                     | `sales-channel:read`           |

### Kanal anlegen

```bash theme={null}
curl -X POST "$BASE_URL/api/sales-channels" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "b2b-shop",
    "brandName": "Acme B2B",
    "websiteUrl": "https://b2b.acme.example"
  }'
```

| Feld         | Pflicht | Regeln                                                                                                                        |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `name`       | ja      | Technischer Name. Nur Kleinbuchstaben, Ziffern und Bindestriche (`^[a-z0-9-]+$`), 1 bis 255 Zeichen. **Nicht** mehr änderbar. |
| `brandName`  | ja      | Anzeigename der Marke, 1 bis 255 Zeichen.                                                                                     |
| `websiteUrl` | nein    | Muss `https` sein.                                                                                                            |

Beim Anlegen wird automatisch eine Standard-Customerfront-Domain aus `name` und einem festen Suffix erzeugt. Der `name` ist später unveränderlich, weil er in URLs und Logs auftaucht.

### Kanal aktualisieren

`PATCH /api/sales-channels/{id}` ist partiell, nur übergebene Felder werden geändert.

```bash theme={null}
curl -X PATCH "$BASE_URL/api/sales-channels/{id}" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowCoupons": false,
    "allowedPaymentMethods": ["sepa_direct_debit"],
    "paymentSuccessUrl": "https://b2b.acme.example/danke"
  }'
```

| Feld                                                                                       | Typ            | Bedeutung                                                                                                           |
| ------------------------------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `brandName`                                                                                | string         | Anzeigename der Marke.                                                                                              |
| `websiteUrl`                                                                               | string (https) | „Zurück zur Website"-Link.                                                                                          |
| `phone`                                                                                    | string         | Kontakt-Telefonnummer.                                                                                              |
| `allowCoupons`                                                                             | boolean        | Kanal-Gate für Coupons (siehe unten).                                                                               |
| `allowedPaymentMethods`                                                                    | string\[]      | Whitelist der Zahlungsmethoden. Leer = keine Einschränkung. Jeder Wert muss auf ein aktives Gateway abbildbar sein. |
| `paymentSuccessUrl` `paymentCancelUrl` `paymentFailureUrl` `paymentPendingUrl` `returnUrl` | string (https) | Weiterleitungs-URLs nach dem Zahlvorgang.                                                                           |

### Vollständige Kanal-Repräsentation

`GET /api/sales-channels/{id}` liefert die volle Sicht inklusive eingebetteter Appearance-Felder:

```json theme={null}
{
  "id": "45d60990-cde6-4139-b64f-79b79c6c6d98",
  "name": "default",
  "isDefault": true,
  "brandName": "myLife AG",
  "websiteUrl": "https://mylife.de",
  "phone": "+49 30 1234567",
  "allowCoupons": true,
  "allowedPaymentMethods": [],
  "paymentSuccessUrl": null,
  "paymentCancelUrl": null,
  "paymentFailureUrl": null,
  "paymentPendingUrl": null,
  "returnUrl": null,
  "logoUrl": "https://…/logo.svg",
  "primaryColor": "#000000",
  "secondaryColor": "#FF0000",
  "privacyUrl": "https://mylife.de/datenschutz",
  "conditionsUrl": "https://mylife.de/agb",
  "createdAt": "2026-01-10T08:00:00+00:00",
  "updatedAt": "2026-06-17T12:00:00+00:00"
}
```

## Coupon-Gate

`allowCoupons` ist ein **Kanal-weites Gate**. Steht es auf `false`, sind Coupons in keinem CheckoutLink dieses Kanals einlösbar, egal was der einzelne CheckoutLink erlaubt. Ein CheckoutLink kann Coupons nur weiter **einschränken**, nie gegen den Kanal **erlauben**.

| Kanal `allowCoupons` | CheckoutLink | Einlösbar            |
| -------------------- | ------------ | -------------------- |
| `true`               | erlaubt      | ja                   |
| `true`               | verboten     | nein                 |
| `false`              | erlaubt      | nein (Kanal gewinnt) |
| `false`              | verboten     | nein                 |

Neu angelegte Kanäle haben `allowCoupons = true`.

## Zahlungsmethoden-Whitelist

`allowedPaymentMethods` wirkt als Whitelist:

* **Leeres Array** → keine kanalspezifische Einschränkung; alle Methoden mit aktivem Gateway sind erlaubt.
* **Befülltes Array** → nur die gelisteten Methoden, sofern ihr Gateway aktiv konfiguriert ist.

Beim Speichern validiert Fynn, dass jeder Wert auf ein für die Organisation aktiv konfiguriertes Payment-Gateway abbildbar ist. Die im Kontext verfügbaren Methoden liefert `GET /api/sales-channels/payment-methods/available`.

## Eigene Domains

Jeder Kanal hat genau eine **Standard-Domain** (automatisch, nicht editierbar) und optional **eine eigene Domain**. Ein einzelner CNAME genügt, das TLS-Zertifikat wird automatisch ausgestellt und erneuert. Es gibt **keinen** selbstverwalteten TXT-Nachweis.

| Methode  | Pfad                                            | Zweck                                     |
| -------- | ----------------------------------------------- | ----------------------------------------- |
| `GET`    | `/api/sales-channels/{id}/custom-domain`        | Domain + DNS-Anweisungen + Status abrufen |
| `POST`   | `/api/sales-channels/{id}/custom-domain`        | Eigene Domain hinzufügen                  |
| `POST`   | `/api/sales-channels/{id}/custom-domain/verify` | Status sofort prüfen („Verifizieren")     |
| `DELETE` | `/api/sales-channels/{id}/custom-domain`        | Eigene Domain entfernen                   |

### Domain hinzufügen

```bash theme={null}
curl -X POST "$BASE_URL/api/sales-channels/{id}/custom-domain" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "host": "shop.example.com" }'
```

Die Antwort enthält die DNS-Anweisungen und beide Status:

```json theme={null}
{
  "id": "…",
  "host": "shop.example.com",
  "status": "pending",
  "sslStatus": "pending_validation",
  "isDefault": false,
  "dnsInstructions": [
    { "type": "CNAME", "name": "shop.example.com", "value": "cname.customerfront.app" }
  ],
  "note": "Lege den CNAME-Eintrag bei deinem DNS-Anbieter an. Das TLS-Zertifikat wird automatisch ausgestellt, sobald der CNAME auflöst …"
}
```

`dnsInstructions` enthält immer den CNAME und zusätzlich etwaige Validierungs-Einträge, die du ebenfalls anlegen musst.

### Die zwei Status

Eine eigene Domain hat zwei voneinander unabhängige Status:

| Feld        | Bedeutung                     | Werte                                              |
| ----------- | ----------------------------- | -------------------------------------------------- |
| `status`    | DNS-Kontrolle / Verifizierung | `pending`, `verified`                              |
| `sslStatus` | TLS-Lebenszyklus              | `pending`, `pending_validation`, `active`, `error` |

Die Domain wird erst **produktiv** (und zur Standard-Adresse des Kanals), wenn `sslStatus = active` ist. Ab da löst Fynn Anfragen über diese Domain auf den Kanal auf.

### Verifizieren

`POST /api/sales-channels/{id}/custom-domain/verify` prüft den Status einmal synchron:

* Ist der Status `active`, wird die Domain verifiziert und zur Standard-Customerfront-Domain des Kanals befördert.
* `pending` / `pending_validation` werden ohne Fehler zurückgegeben, versuche es später erneut.
* `error` (das Zertifikat kann nicht ausgestellt werden) führt zu einer Fehlerantwort.

<Tip>
  Du musst nicht aktiv pollen: Ein wiederkehrender Reconcile-Job prüft den SSL-Status im Hintergrund und schaltet die Domain frei, sobald das Zertifikat steht. Der Verify-Endpunkt ist nur der „jetzt prüfen"-Pfad und idempotent, eine bereits aktive Domain bleibt unverändert.
</Tip>

### Entfernen

`DELETE /api/sales-channels/{id}/custom-domain` entfernt die eigene Domain und setzt die Kanal-Adresse auf die Standard-Domain zurück. Der Checkout bleibt also durchgehend erreichbar.

## Weiterleitungs-URLs und `returnUrl`

Die optionalen URLs auf dem Kanal steuern, wohin der Kunde nach dem Zahlvorgang geleitet wird. Bleibt eine URL leer, fällt der Kunde auf die Standardseite der Kundenfront (`/self-service/transaction/{status}`) zurück.

| Feld                | Auslöser                                                                      |
| ------------------- | ----------------------------------------------------------------------------- |
| `paymentSuccessUrl` | Status `booked` / `captured` (erfolgreich).                                   |
| `paymentCancelUrl`  | Kunde bricht beim Anbieter ab.                                                |
| `paymentFailureUrl` | Explizite Ablehnung durch den Anbieter.                                       |
| `paymentPendingUrl` | Status `pending` / `authorized` (zum Beispiel wartende SEPA-Lastschrift).     |
| `returnUrl`         | Nach einem API-getriebenen Payment-Method-Setup (`PaymentMethodSource::Api`). |

Startest du Payment-Method-Setups über die API, wird nach Abschluss die Kanal-`returnUrl` aufgerufen. Lässt du sie leer, kannst du pro Request dynamisch ein `redirectUrl` im PaymentMethodSetup mitgeben, das stattdessen verwendet wird.

## Webhooks

Jeder ausgehende Webhook trägt den Header `X-Sales-Channel` mit dem **technischen Namen** des Kanals, dem das auslösende Objekt zugeordnet ist (oder `default`, wenn keiner gesetzt ist). So routest du eingehende Events empfängerseitig nach Marke, ohne den Payload zu parsen.

```http theme={null}
POST /your-webhook-endpoint HTTP/1.1
X-Sales-Channel: b2b-shop
Content-Type: application/json
```

## Verwandte Themen

<CardGroup>
  <Card title="Vertriebskanäle (Anleitung)" icon="tag" href="/guide/tenant/sales-channels">
    Die Einstellungen in der Wallet, Schritt für Schritt mit Screenshots.
  </Card>

  <Card title="Kunden" icon="users" href="/guide/customers/introduction">
    Kundenverwaltung und das `salesChannel`-Feld im Kontext.
  </Card>

  <Card title="Eigene E-Mail-Domain" icon="envelope" href="/guide/notifications/custom-email-domain">
    Sendedomain pro Kanal einrichten.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guide/webhooks/introduction">
    Echtzeit-Events empfangen und nach Kanal routen.
  </Card>
</CardGroup>


# Gutscheine & Rabatte
Source: https://docs.fynn.eu/guide/discounts/introduction

Erstelle und verwalte Gutscheine und Rabatte.

Mit Gutscheinen und Rabatten kannst du deinen Kunden sowohl im [Checkout](/guide/checkout/introduction) als auch bei der [Abo-Anlage](/guide/subscriptions/introduction) Rabatte gewähren.
Du kannst Gutscheine und Rabatte für alle Produkte oder nur für bestimmte Produkte erstellen. Du kannst auch festlegen, ob ein Gutschein nur einmal oder mehrmals verwendet werden kann.

## Rabatte

Es gibt zwei Arten von Rabatten, die du erstellen kannst:

1. **Prozentualer Rabatt**: Ein prozentualer Rabatt wird auf den Gesamtbetrag angewendet.
2. **Fester Betrag**: Ein fester Betrag wird vom Einzelbetrag abgezogen.

<Warning>
  Bei Verwendung von **Fester Betrag** wird der Rabatt auf den Einzelpreis angewendet, nicht auf den Gesamtpreis.
  Beispiel: Ein Produkt kostet 10€ / Stück und der Rabatt beträgt 5€. Der Kunde zahlt nur noch 5€ / Stück.
</Warning>

### Rabatt erstellen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Öffne die Erstellen-Maske">
        Wähle **Rabatte** im Hauptmenü aus, um die Liste der Rabatte anzuzeigen. Klicke auf **Neu**.
      </Step>

      <Step title="Rabatt konfigurieren">
        Fülle die Felder aus:

        * **Name**: Der Name des Rabatts. Dieser wird dem Kunden im [Checkout](/guide/checkout/introduction) angezeigt.
        * **Code**: Der Code, den der Kunde im [Checkout](/guide/checkout/introduction) eingeben muss, um den Rabatt zu erhalten.
        * **Typ**: Der Typ des Rabatts. Wähle zwischen einem prozentualen Rabatt und einem festen Betrag.
        * **Prozentualer Rabatt**: Der prozentuale Rabatt, der auf den Gesamtbetrag angewendet wird.
        * **Fester Betrag**: Der feste Betrag, der vom Gesamtbetrag abgezogen wird.
        * **Aktiv**: Ob der Rabatt aktiv ist oder nicht.

        <Tip>
          Standardmäßig ist ein Rabatt dauerhaft gültig und kann beliebig oft im Warenkorb verwendet werden.
        </Tip>

        <Frame>
          <img alt="Rabatt erstellen" />
        </Frame>
      </Step>

      <Step title="Gültigkeit festlegen (optional)">
        Du kannst die Gültigkeit des Rabatts festlegen:

        * **Dauerhaft**: Der Rabatt ist bis zur Beendigung des Abonnements gültig.
        * **Einmalig zu Beginn**: Der Rabatt wird einmalig bei der ersten Rechnung gewährt.
        * **Begrenzt auf x Abrechnungsperioden**: Der Rabatt wird für eine bestimmte Anzahl von Abrechnungsperioden gewährt.

        Folgende Optionen sind ebenfalls verfügbar:

        * **Anzahl Abrechnungsperioden**: Die Anzahl der Abrechnungsperioden, für die der Rabatt gültig ist (nur bei "Begrenzt auf x Abrechnungsperioden").
        * **Maximale Einlösungen**: Die maximale Anzahl von Einlösungen des Rabatts - nur für den Warenkorb relevant.
        * **Maximale Einlösungen pro Kunde**: Die maximale Anzahl von Einlösungen des Rabatts pro Kunde - nur für den Warenkorb relevant.
        * **Gültig bis**: Das Datum, bis zu dem der Rabatt im Warenkorb gültig ist.

        <Tip>
          Die Anzahl der Einlösungen und "Gültig bis" sind nur für den Warenkorb relevant. Wenn du den Rabatt für die Abo-Anlage verwenden möchtest, kann dieser beliebig oft verwendet werden.
        </Tip>

        <Frame>
          <img alt="Rabatt Gültigkeit" />
        </Frame>

        <Info>
          Abrechnungsperioden sind die Zeiträume, in denen ein Kunde für ein Abonnement in Rechnung gestellt wird. Die Abrechnungsperioden können täglich, wöchentlich, monatlich oder jährlich sein.
        </Info>
      </Step>

      <Step title="Produkt Einschränkungen festlegen (optional)">
        Du kannst den Rabatt auf bestimmte Produkte beschränken. Hierfür kannst du unter "Gültig für Produkte" die Produkte auswählen, für die der Rabatt gültig sein soll.
        Unter "Ausgeschlossene Produkte" kannst du Produkte auswählen, für die der Rabatt nicht gültig sein soll. Beide Felder sind nicht gleichzeitig nutzbar.

        <Frame>
          <img alt="Rabatt Produkt Einschränkungen" />
        </Frame>
      </Step>

      <Step title="Rabatt erstellen">
        Klicke auf **Gutschein erstellen** um den Rabatt zu erstellen.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Rabatt erstellen](/api-reference/coupon/create-a-coupon) Endpunkt.

    ```bash theme={null}
    POST /coupons
    ```

    Alternativ kannst du die [Rabatte abrufen](/api-reference/coupon/get-all-coupons), um die Liste der Rabatte zu erhalten.
  </Tab>
</Tabs>

## Rabatt anpassen

<Tabs>
  <Tab title="Web-App verwenden">
    Du kannst einen Rabatt bearbeiten, indem du auf den Rabatt in der Liste klickst und die Werte anpasst. Klicke auf **Speichern**, um die Änderungen zu speichern.

    Hierbei sind alle Felder, die beim Erstellen eines Rabatts konfiguriert werden können, auch beim Bearbeiten verfügbar.
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Rabatt aktualisieren](/api-reference/coupon/update-a-coupon) Endpunkt.

    ```bash theme={null}
    PUT /coupons/{id}
    ```
  </Tab>
</Tabs>

## Rabatt löschen

<Tabs>
  <Tab title="Web-App verwenden">
    Du kannst einen Rabatt löschen, indem du in der Liste auf die drei Punkte neben dem Rabatt klickst und **Löschen** auswählst. Bestätige die Aktion, um den Rabatt zu löschen.

    <Tip>
      Ist der Rabatt bereits in einem Abonnement oder Warenkorb verwendet, kann dieser nicht gelöscht sondern nur deaktiviert werden.
    </Tip>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Rabatt löschen](/api-reference/coupon/delete-a-coupon) Endpunkt.

    ```bash theme={null}
    DELETE /coupons/{id}
    ```

    Alternativ kannst du die [Rabatte abrufen](/api-reference/coupon/get-all-coupons).
  </Tab>
</Tabs>

## Gutschein-Codes

Jeder Rabatt kann über den **Code** im [Checkout](/guide/checkout/introduction) eingelöst werden.
Aktuell ist es nicht möglich mehrere Gutschein-Codes für den selben Rabatt zu erstellen.

## Rabatt im Abonnement verwenden

Bestehende Rabatte können bei der Abonnement-Erstellung verwendet werden, alternativ kann für dieses Abonnement ein individueller Rabatt erstellt werden.
Um einen Rabatt im Abonnement zu verwenden, lese bitte den [Guide zur Abonnement-Erstellung](/guide/subscriptions/introduction).

## Rabatte und MRR (Monthly Recurring Revenue)

Bei der Berechnung des MRR (Monthly Recurring Revenue) werden **ausschließlich lebenslange Rabatte** berücksichtigt. Einmalige und für bestimmte Zyklen angegebene Rabatte werden nicht in die Berechnung einbezogen.


# Mahnwesen
Source: https://docs.fynn.eu/guide/dunning/introduction

Automatisiertes Mahnwesen für Rechnungen

Mit Hilfe des Mahnwesens können automatisiert Mahnungen und Zahlungserinnerungen für Rechnungen erstellt werden.
Das Mahnwesen kann für alle Rechnungen oder nur für ausgewählte Rechnungen aktiviert werden.

<Tip>
  Du kannst pro Kunde eine eigene **Mahnwesen-E-Mail** hinterlegen, damit Zahlungserinnerungen und Mahnungen an einen dedizierten Ansprechpartner gesendet werden, z.B. an die Forderungsmanagement-Abteilung statt an die Buchhaltung.
  Siehe [E-Mail-Adressen verwalten](/guide/customers/email-management) für Details.
</Tip>

## Mahnwesen einrichten

Das Mahnwesen kann mit einfachen Regeln eingerichtet werden.
Grundsätzlich wird unabhängig von der Art jeweils ein PDF Dokument erstellt und per E-Mail an den Kunden versendet.

Die E-Mail Vorlagen und das erstellte PDF Dokument können je Stufe individuell angepasst werden.

### Zahlungserinnerungen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Einstellungen öffnen">
        Öffne die Einstellungen und wähle den Reiter ["Mahnwesen"](https://app.fynn.eu/settings/payment-failures).
      </Step>

      <Step title="Stufe einrichten">
        Wähle eines der vorgegebenen Stufen und den Typ der Stufe aus.

        <Frame>
          <img alt="Mahnwesen Stufen" />
        </Frame>
      </Step>

      <Step title="Original-Rechnungskopie">
        Wähle aus ob die Original-Rechnung als Kopie an die E-Mail angehängt werden soll.

        <Frame>
          <img alt="Original-Rechnungskopie" />
        </Frame>
      </Step>

      <Step title="Tage überfällig konfigurieren">
        Passe die Anzahl der Tage an, die die Rechnung überfällig sein muss, damit die Mahnstufe ausgelöst wird.

        <Tip>
          Ist bereits eine Mahnstufe ausgelöst, wird die Anzahl der Tage ab dem Erstellungsdatum des Mahndokuments der letzten Mahnstufe berechnet.
          Die Zahlungsfrist der Mahnstufe ist dabei nicht relevant.
        </Tip>

        <Frame>
          <img alt="Tage überfällig" />
        </Frame>
      </Step>

      <Step title="Zahlungsfrist">
        Passe die Zahlungsfrist an. Diese wird für die Berechnung des Fälligkeitsdatums der Mahnstufe verwendet.
        Die Zahlungsfrist wird auf das Datum der Ausführung der Mahnstufe addiert.

        <Frame>
          <img alt="Zahlungsfrist" />
        </Frame>
      </Step>

      <Step title="E-Mail Vorlage anpassen">
        Die E-Mail Vorlage kann nach Belieben angepasst werden. Generiere eine Vorschau indem du auf "Test E-Mail versenden" klickst.
        Die E-Mail kann zum jetzigen Zeitpunkt nur Text enthalten.

        **Folgende Platzhalter sind verfügbar**

        * `{{ referencedInvoiceNumber }}` - Rechnungsnummer
        * `{{ referencedInvoiceDate }}` - Rechnungsdatum
        * `{{ totalGrossAmount }}` - Rechnungsbetrag (brutto) (ggfs. inkl. Mahngebühren)
        * `{{ dueDate }}` - Fälligkeitsdatum der Zahlungserinnerung / Mahnung
        * `{{ tenant.name }}` - Name der Organisation aus den [allgemeinen Einstellungen](https://app.fynn.eu/settings)

        <Frame>
          <img alt="E-Mail Vorlage" />
        </Frame>
      </Step>

      <Step title="PDF Vorlage anpassen">
        Passe die PDF Vorlage nach Belieben an. Generiere eine Vorschau indem du auf "Test PDF Dokument erstellen" klickst.

        <Frame>
          <img alt="PDF Vorlage" />
        </Frame>
      </Step>

      <Step title="Stufe aktivieren">
        Die Mahnstufe kann nun über den Schalter "Aktiv" aktiviert oder deaktiviert werden.
      </Step>

      <Step title="Stufe speichern">
        Speichere nun die vorgenommenen Einstellungen, indem du auf "Änderungen speichern" klickst.
      </Step>

      <Step title="Mahnstufe erfolgreich eingerichtet 🎉">
        Die Mahnstufe wurde erfolgreich eingerichtet und wird automatisiert für **bestehende und zukünftige** Rechnungen ausgelöst, die die definierten Kriterien erfüllen.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Mahnstufe aktualisieren](/api-reference/overduerule/update-overdue-rule) Endpunkt.

    ```bash theme={null}
    PUT /dunning/overdue-rules/{id}
    ```

    Alternativ kannst du die [Mahnstufen abrufen](/api-reference/overduerule/get-overdue-rules).
  </Tab>
</Tabs>

### Mahnungen

Die Einrichtung der Mahnstufen erfolgt analog zu den Zahlungserinnerungen. Zusätzlich können Mahngebühren erhoben und ein Brief-Versand konfiguriert werden.

#### Mahngebühren

Mahngebühren können pro Mahnstufe konfiguriert werden. Die Mahngebühren werden auf den Rechnungsbetrag (brutto) aufgeschlagen.

<Info>
  Zum jetzigen Zeitpunkt werden die Mahngebühren in der Buchhaltungsexporten nicht berücksichtigt.
</Info>

#### Brief-Versand

Der Brief-Versand kann pro Mahnstufe konfiguriert werden.
Hierbei wird das Mahn-PDF Dokument über unseren Partner für den Brief-Versand in Farbe einseitig gedruckt und versendet.

Die Preise für den Brief-Versand sind der Preisliste zu entnehmen.

## Mahnwesen aussetzen

Das Aussetzen des Mahnwesen kann auf 3 Ebenen eingerichtet werden:

1. Global
2. Für einzelne Kunden
3. Für einzelne Rechnungen

Wird das Mahnwesen wieder reaktiviert, werden alle Rechnungen, die sich in der Zwischenzeit überfällig geworden sind, berücksichtigt.
Hierbei greift die nächste Mahnstufe, die auf Basis des aktuellen Rechnungsstatus berechnet wird.

<Tip>
  Für einzelne Rechnungen kannst du einen Mahnstopp mit Enddatum setzen ("Mahnstopp bis"). Bis zu diesem Tag ruht das Mahnwesen, danach wird es automatisch fortgesetzt. Ohne Datum bleibt der Mahnstopp so lange bestehen, bis du ihn wieder aufhebst.

  Im Rechnungs-Export siehst du für jede Rechnung, ob ein Mahnstopp aktiv ist und bis wann er gilt. So erkennst du in deiner Auswertung überfälliger Rechnungen sofort, welche pausiert sind.
</Tip>

### Global

Um das Mahnwesen global auszusetzen, kann dies in den Einstellungen (Einstellungen > Reiter "Mahnwesen") an den jeweiligen Mahnstufen konfiguriert werden.
Soll das Mahnwesen vollständig ausgesetzt werden, müssen alle Mahnstufen deaktiviert werden.

### Für einzelne Kunden

In den Kundenstammdaten kann das Mahnwesen für den jeweiligen Kunden ausgesetzt werden.

<Steps>
  <Step title="Kundenstammdaten öffnen">
    Öffne die Kundenstammdaten des Kunden, für den das Mahnwesen ausgesetzt werden soll.
  </Step>

  <Step title="Reiter &#x22;Einstellungen&#x22; öffnen">
    Setze das Mahnwesen für den Kunden aus, indem du den Schalter "Mahnwesen deaktivieren" aktivierst.
    Zusätzlich ist es möglich für einzelne Kunden die Mahngebühren über die Schalter "Gebühren anwenden" zu deaktivieren.

    <Frame>
      <img alt="Kundenstammdaten Einstellungen" />
    </Frame>
  </Step>

  <Step title="Änderungen speichern">
    Speichere die Änderungen, indem du auf "Speichern" klickst.
  </Step>
</Steps>

### Für einzelne Rechnungen

In den Rechnungsdetails kann das Mahnwesen für die jeweilige Rechnung ausgesetzt werden.

<Steps>
  <Step title="Rechnungsdetails öffnen">
    Öffne die Rechnungsdetails der Rechnung, für die das Mahnwesen ausgesetzt werden soll.
  </Step>

  <Step title="Mahnwesen pausieren">
    Setze das Mahnwesen für die Rechnung aus, indem du unterhalb der Rechnungsdetails, im Bereich "Mahnwesen"
    den Button "Pausieren" auswählst.

    Im folgenden Dialog kannst du optional unter "Pausieren bis" ein Datum wählen. Bis zu diesem Tag ruht das Mahnwesen, am Folgetag wird es automatisch fortgesetzt. Ohne Datum bleibt der Mahnstopp bestehen, bis du ihn wieder aufhebst.

    <Tip>
      Zu diesem Zeitpunkt offene Zahlungserinnerungen oder Mahnungen bleiben weiterhin bestehen.
    </Tip>

    <Frame>
      <img alt="Rechnungsdetails Einstellungen" />
    </Frame>
  </Step>

  <Step title="Mahnwesen reaktivieren">
    Um das Mahnwesen für die Rechnung wieder zu aktivieren, klicke auf den Button "Fortsetzen".

    Anschließend wird die nächste gültige Mahnstufe für die Rechnung ermittelt und das Mahnwesen entsprechend fortgesetzt.

    <Frame>
      <img alt="Rechnungsdetails Einstellungen" />
    </Frame>
  </Step>
</Steps>

## Zahlungseingang verbuchen

## Beispiele

### Standard

**Folgendes Regelwerk ist eingerichtet**

* Die **1. Zahlungserinnerung** soll nach 14 Tagen erfolgen.
* Die **2. Zahlungserinnerung** soll nach 7 Tagen erfolgen.
* Die **3. Zahlungserinnerung** soll nach 7 Tagen erfolgen.
* Die **1. Mahnung** soll nach 7 Tagen erfolgen.

**Folgender Ablauf ist gegeben**

* Die Rechnung ist am 10.05. fällig.
* Die <b>1. Zahlungserinnerung</b> wird am 24.05. erstellt.
* Die <b>2. Zahlungserinnerung</b> wird am 31.05. erstellt.
* Die **3. Zahlungserinnerung** wird am 07.06. erstellt.
* Die **1. Mahnung** wird am 14.06. erstellt.

### Ausgesetztes Mahnwesen

**Folgendes Regelwerk ist eingerichtet**

* Die **1. Zahlungserinnerung** soll nach 14 Tagen erfolgen.
* Die **2. Zahlungserinnerung** soll nach 7 Tagen erfolgen.
* Die **3. Zahlungserinnerung** soll nach 7 Tagen erfolgen.

**Folgender Ablauf ist gegeben**

* Die Rechnung ist am 10.05. fällig.
* Die <b>1. Zahlungserinnerung</b> wird am 24.05. erstellt.
* Das Mahnwesen wird am 25.05. deaktiviert.
* Das Mahnwesen wird am 01.06. reaktiviert.
* Die <b>2. Zahlungserinnerung</b> wird am nach Reaktivierung am 01.06. erstellt, da die vorherige Zahlungserinnerung bereits mehr als 7 Tage überfällig ist.
* Die **3. Zahlungserinnerung** wird am 08.06. erstellt, da dann erst die 2. Zahlungserinnerung mehr als 7 Tage überfällig ist.


# Features
Source: https://docs.fynn.eu/guide/entitlements/introduction

Erstelle und verwalte Features für deine Abo-Produkte.

# Übersicht

Die Features Integration ermöglicht es, dynamische Feature-Sets für deine Abonnement-Produkte zu erstellen und zu verwalten. Diese "Features" sind Leistungsmerkmale, die dein Produkt oder Service auszeichnen. Sobald ein Abonnement mit einem solchen Produkt erstellt wird – sei es über einen Checkout-Link oder manuell – werden die konfigurierten Features mit den entsprechenden Werten ins Abonnement übertragen.

### Use-Cases

* **SaaS-Lösungen**: Stelle für deine Kunden Feature-Sets wie Benutzeranzahl (Quantity), Funktions-Switches (z. B. "White Labeling aktiviert"), Custom-SLAs (Basic, Silber, Gold) oder Mengen-Ranges (z. B. "5 GB Speicherplatz") bereit.
* **Hosting- oder Server-Produkte**: Definiere RAM, CPU-Kerne, IP-Adressen als Features für Serverangebote.
* **Spezielle Zusatzfunktionen**: Ergänze individuelle Features (z. B. eine persönliche Onboarding-Session), um Kundenbedürfnisse flexibel zu erfüllen.

## Feature-Typen und Status

Features sind konfigurierbare Leistungsmerkmale für deine Abos, die in unterschiedlichen Typen erstellt werden können:

* **Switch**: Ein-/Ausschalten bestimmter Funktionalitäten.
* **Quantity**: Auswahl vordefinierter Mengen (z. B. "5 User", "10 User").
* **Custom**: Auswahl aus vorgegebenen Textwerten (z. B. "SLA Basic", "SLA Silber", "SLA Gold").
* **Range**: Manuelle Eingabe eines Wertes innerhalb eines bestimmten Rahmens, optional "unlimitiert" auf einer oder beiden Seiten.

Jedes Feature hat zudem einen Status:

* **Entwurf (Draft)**: Das Feature kann Produkten zugeordnet werden, wird aber noch nicht in Abos übernommen.
* **Aktiv (Active)**: Das Feature wird beim Erstellen eines neuen Abos übernommen.
* **Archiviert (Archived)**: Das Feature ist nicht mehr für neue Abos verfügbar, bleibt aber in bestehenden Abos unverändert.

<Tip>**Tipp:** Mit diesen Status kannst du Features vorab planen, testen und später aktivieren, ohne laufende Abos zu beeinflussen.</Tip>

## Beispiel für den Einsatz von Features

Stelle dir vor, du betreibst eine SaaS-Lösung mit dem Produkt "Professional". Dieses Produkt hat standardmäßig das Switch-Feature "White Labeling".

Für den Preis "jährlich" fügst du ein Custom-Feature "SLA Gold" hinzu.
Bucht ein Kunde das Produkt "Professional" mit dem Preis "jährlich", erhält er **automatisch** beide Features: White Labeling vom Produkt und SLA Gold vom Preis.

## Erstellen eines neuen Features

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Feature Übersicht öffnen">
        Wähle **Features** im Hauptmenü aus, um die Liste der Features anzuzeigen. Klicke auf **Neu**.
      </Step>

      <Step title="Feature konfigurieren">
        Fülle die Felder aus:

        * **Name**: Der Name des Features, z. B. "White Labeling". Dieser wird intern angezeigt und kann in Zukunft ggfs. auch im Kundenbereich sichtbar sein.
        * **Typ**: Wähle zwischen Switch, Quantity, Custom oder Range. Je nach Typ stehen weitere Einstellungen zur Verfügung.
        * **Beschreibung**: Eine kurze Beschreibung des Features, dies ist zur einfacheren internen Zuordnung gedacht.
        * **Status**: Wähle zwischen Entwurf, Aktiv oder Archiviert.
        * **Einheit**: Eine optionale Einheit, z. B. "User", "GB", "SLA", die bei Quantity oder Range verwendet wird und eine bessere Lesbarkeit und Verständlichkeit ermöglicht.
        * **Optionen**: Je nach Typ stehen weitere Einstellungen zur Verfügung, z. B. für Quantity die Auswahl der Mengen, für Range die Definition des Bereichs oder für Custom die Auswahl der Werte.
        * **Gültig ab**: Ein optionales Datum, ab dem das Feature aktiv ist und in neuen Abos übernommen wird. Für Bestandsabos ist dies nicht relevant.
        * **Gültig bis**: Ein optionales Datum, bis zu dem das Feature aktiv ist und in neuen Abos übernommen wird. Für Bestandsabos ist dies nicht relevant.
        * **Technische ID**: Eine optionale technische ID, die bspw. das Feature in deinem System identifiziert, z. B. "global.white-labeling".

        <Frame>
          <img alt="Feature erstellen" />
        </Frame>
      </Step>

      <Step title="Feature speichern">
        Klicke auf **Feature erstellen**, um das Feature zu erstellen.

        Das Feature ist nun zur Zuordnung an Produkte und Preise bereit.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature erstellen](/api-reference/feature/create-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlements/features
    ```

    Alternativ kannst du die [Features abrufen](/api-reference/features/get-features), um die Liste der Features zu erhalten.
  </Tab>
</Tabs>

## Features zuordnen

Durch die Zuordnung von Features zu Produkten oder spezifischen Preisen stellst du sicher, dass bei der Erstellung eines Abonnements automatisch die relevanten Leistungsmerkmale übernommen werden.

* Features am **Produkt** sind immer gegeben.
* Durch Features am **Preis** können zusätzliche oder abweichende Eigenschaften ergänzt werden. Dies ermöglicht es, für jährliche Tarife z. B. zusätzliche Features zu definieren.
* Überschneidet sich ein Feature am Produkt und am Preis, gilt die Definition vom Preis.

Zusätzlich lassen sich Start- und Enddaten für Features festlegen, um Releases oder zeitlich begrenzte Aktionen vorzubereiten.

<Frame>
  <img alt="Liste der Feature-Zuordnung" />
</Frame>

### Hinzufügen eines Features zu einem Produkt

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Produkt bearbeiten">
        Navigiere zu **Produkte** und wähle das gewünschte Produkt aus.
      </Step>

      <Step title="Feature zum Produkt hinzufügen">
        Wähle nun das gewünschte Feature aus der Liste aus, setze den Wert und ggfs. die Gültigkeit.

        <Frame>
          <img alt="Feature zum Produkt hinzufügen" />
        </Frame>
      </Step>

      <Step title="Feature speichern">
        Klicke auf **Speichern**, um das Feature dem Produkt zuzuweisen.
        Sollte das Feature zeitlich nicht eingeschränkt sein, wird dieses ab sofort in allen neuen Abos mit diesem Produkt übernommen.

        <Tip>
          Ist das Feature zeitlich eingeschränkt, wird es nur in neuen Abos übernommen, die in diesem Zeitraum erstellt werden.
        </Tip>

        <Info>
          Das Feature muss aktiv sein, um in neuen Abos übernommen zu werden. Es darf nicht archiviert oder im Entwurf sein.
        </Info>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature zum Produkt hinzufügen](/api-reference/feature/assign-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlement/feature-assignments
    ```
  </Tab>
</Tabs>

### Hinzufügen eines Features zu einem Preis (optional)

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Produkt bearbeiten">
        Navigiere zu **Produkte** und wähle das gewünschte Produkt aus.
      </Step>

      <Step title="Preis bearbeiten">
        Wähle den gewünschten Preis aus und klicke auf **Bearbeiten**.
      </Step>

      <Step title="Feature zum Preis hinzufügen">
        Wähle nun das gewünschte Feature aus der Liste aus, setze den Wert und ggfs. die Gültigkeit.

        <Frame>
          <img alt="Feature zum Preis hinzufügen" />
        </Frame>
      </Step>

      <Step title="Feature speichern">
        Klicke auf **Speichern**, um das Feature dem Preis zuzuweisen.
        Sollte das Feature zeitlich nicht eingeschränkt sein, wird dieses ab sofort in allen neuen Abos mit diesem Produkt & Preis übernommen.

        <Tip>
          Ist das Feature zeitlich eingeschränkt, wird es nur in neuen Abos übernommen, die in diesem Zeitraum erstellt werden.
        </Tip>

        <Info>
          Das Feature muss aktiv sein, um in neuen Abos übernommen zu werden. Es darf nicht archiviert oder im Entwurf sein.
        </Info>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature zum Preis hinzufügen](/api-reference/feature/assign-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlement/feature-assignments
    ```
  </Tab>
</Tabs>

## Abonnements und Features

### Anlegen eines neuen Abonnements mit Features

Beim Erstellen eines neuen Abonnements oder Hinzufügen eines neuen Produktes, über die Web-App oder API werden automatisch alle Features des Produkts und des Preises übernommen.

<Note>
  Die Features werden nur beim Erstellen eines Abonnements übernommen. Änderungen an den Features im Produkt oder Preis wirken sich nicht auf bestehende Abos aus.
</Note>

### Hinzufügen individueller Features

Im Abonnement kannst du alle übernommenen Features einsehen, aktivieren/deaktivieren oder weitere Features hinzufügen, die nicht an ein Produkt oder einen Preis gebunden sind.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Features im Abo anpassen">
        1. Öffne das gewünschte Abo.
        2. Navigiere zum Reiter **Features**.
        3. Hier siehst du alle Features, ihre Herkunft und ihren Status.
        4. Klicke auf **Neues Feature hinzufügen**, um ein individuelles Feature hinzuzufügen.
        5. Speichere die Änderungen.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Feature zum Produkt hinzufügen](/api-reference/feature/assign-feature) Endpunkt.

    ```bash theme={null}
    POST /entitlement/feature-assignments
    ```
  </Tab>
</Tabs>

### Abrufen von Features in einem Abonnement

Um die Features eines Abonnements abzurufen, gibt es verschiedene Möglichkeiten:

#### Webhook abonnieren

Wir empfehlen die Abonnierung des `entitlement.state.updated` Webhooks, um bei Änderungen in den Features informiert zu werden.
Hierbei wird beim Hinzufügen, Entfernen eines Features (manuell oder durch Produkt-Änderung) am Abo ein Webhook ausgelöst.
Läuft ein Feature ab, oder wird es durch das "gültig ab" oder "gültig bis" Datum aktiviert/deaktiviert, wird ebenfalls ein Webhook ausgelöst.

Beispiel Payload:

```json theme={null}
{
    "event": {
      "id": "ad9f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
      "type": "entitlement.state.updated",
      "version": "v1",
      "createdAt": "2022-01-01T12:00:00Z"
    },
    "data": {
        "customer": {
            "id": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
            "customerNumber": "CUS-1234",
            [...]
        },
        "subscription": {
          "id": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
          "number": "SUB-1234",
          [...]
        },
        "entitlements": [
            {
                "entitlementId": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
                "featureId": "included-users",
                "featureName": "Included Users",
                "value": "5"
            },
            {
                "entitlementId": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
                "featureId": "addon-b",
                "featureName": "Addon B",
                "value": "true"
            },
            {
                "entitlementId": "ad8f8b8b-8b8b-8b8b-8b8b-8b8b8b8b8b8b",
                "featureId": "sla-level",
                "featureName": "SLA Level",
                "value": "gold"
            }
        ]
    }
}
```

#### API-Endpunkt abrufen

Alternativ kannst du die Features eines Abonnements über den [Abonnement-Endpunkt](/api-reference/entitlement/get-available-features) abrufen.

<Info>
  Der Endpunkt ist auf 240 Anfragen pro Minute, pro Organisation begrenzt. Wir empfehlen daher die Verwendung des Webhooks.
</Info>

## Entitlement Status

Jedes Entitlement in einem Abonnement hat einen berechneten Status, der den aktuellen Zustand anzeigt:

* **Active**: Das Entitlement ist aktiv und liegt innerhalb des Gültigkeitszeitraums. Der Kunde kann das Feature nutzen.
* **Pending**: Das Entitlement ist aktiviert, aber das `validFrom`-Datum liegt in der Zukunft. Das Feature wird automatisch aktiv, sobald das Datum erreicht ist.
* **Disabled**: Das Entitlement wurde manuell deaktiviert.
* **Expired**: Das `validUntil`-Datum ist abgelaufen. Das Entitlement war aktiv, ist aber nicht mehr gültig.

<Note>
  Der Status wird automatisch basierend auf dem `active`-Flag und den Gültigkeitsdaten (`validFrom`, `validUntil`) berechnet. Bei Änderungen wird ein `entitlement.state.updated` Webhook ausgelöst.
</Note>

### Beispiel API-Response

```json theme={null}
{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "feature": {
        "id": "white-labeling",
        "name": "White Labeling"
    },
    "value": "true",
    "validFrom": "2026-03-01T00:00:00Z",
    "validUntil": null,
    "active": true,
    "status": "pending"
}
```

In diesem Beispiel ist das Entitlement aktiviert (`active: true`), aber da `validFrom` in der Zukunft liegt, ist der Status `pending`.

## Abrufen von Kunden-Entitlements

Um die Entitlements eines Kunden abzurufen, muss sich der Kunde bspw. über [OAuth2](/guide/oauth2/introduction) oder einen generierten Access Token authentifizieren.

Der Abruf der aktuell aktiven Entitlements erfolgt anschließend über `https://coreapi.io/customer-entitlements` mit folgender Ausgabe:

```json theme={null}
{
  "subscriptionEntitlements": {
    "<subscriptionId>": [
        "my-feature1",
        "my-feature2",
        "my-feature3",
        "my-feature4"
    ]
  },
  "entitlements": [
    "my-feature1",
    "my-feature2",
    "my-feature3",
    "my-feature4"
  ]
}
```

Hierbei werden unter `entitlements` alle Entitlements der Abonnements zusammengeführt.

## Referenz zur API-Dokumentation

Eine ausführliche Referenz aller Endpunkte, Parameter und Rückgaben findest du in unserer [API-Dokumentation Features](/api-reference/feature) und [API-Dokumentation Entitlements](/api-reference/entitlement).

<Check>Mit der Features Integration kannst du flexibel und skalierbar die Funktionsumfänge deiner Produkte gestalten und dynamisch an deine Kunden ausliefern. Durch die Kombination aus Produkt- und Preis-Features sowie der individuellen Anpassbarkeit im Abonnement selbst stehen dir alle Möglichkeiten offen, um dein Angebot optimal auf die Bedürfnisse deiner Kunden abzustimmen.</Check>

## Webhooks

Folgende Webhooks sind für die Features-Integration verfügbar:

* `feature.created` - Ein neues Feature wurde erstellt.
* `feature.updated` - Ein Feature wurde aktualisiert.
* `feature.archived` - Ein Feature wurde archiviert.
* `entitlement.state.updated` - Die aktuell gültigen Features für ein Abonnement wurden aktualisiert (z.B. durch: eine Änderung des Abonnements; der Features; ein Feature wurde durch "gültig ab" / "gültig bis" hinzugefügt oder entfernt; ein Produkt wurde gekündigt / angepasst und entsprechend dessen Features). Siehe [Abrufen von Features in einem Abonnement](#webhook-abonnieren).


# Fynn Functions
Source: https://docs.fynn.eu/guide/functions/index

Mit Fynn Functions kannst du das Verhalten innerhalb von Fynn anpassen.

Fynn Functions erlaubt es den Entwicklern das Verhalten der Backend Logik zu erweitern.
Hier erfährst du wie du Fynn Functions einrichtest und verwendest.

<Note>Diese Erweiterung befindet sich aktuell in einer geschlossenen Beta-Phase. Bitte kontaktiere uns, um Zugang zu erhalten.</Note>

## Wie funktioniert Fynn Functions?

Fynn Functions erlaubt es dir, eigene Funktionen zu schreiben, die auf Ereignisse in Fynn reagieren.

Hierfür stellen wir verschiedene [Erweiterungs-Punkte](#erweiterungs-punkte) zur Verfügung, die du nutzen kannst, um eigene Logik zu schreiben.
Sofern für einen Erweiterungs-Punkt eine oder mehrere Funktionen registriert sind, wird diese bei dem entsprechenden Ereignis ausgeführt.
Hierbei wird ein Kontext-Objekt übergeben, das Informationen zum Ereignis enthält, dies kann bspw. ein Warenkorb sein.
Innerhalb der Funktion kannst du dann beliebige Aktionen ausführen, wie bspw. eine externe API aufrufen.
Jede Funktion muss am Ende eine oder mehrere vordefinierte [Operationen](#operationen) zurück geben, die anschließend von Fynn ausgeführt werden.

<Tip>
  Jeder Erweiterungs-Punkt hat unterschiedliche Kontext-Objekte und Operationen, die du verwenden kannst.
</Tip>

## Laufzeiten

Jede Funktion wird in einer isolierten Umgebung ausgeführt, die auf 5 Sekunden begrenzt ist. Bitte beachte, dass sich die Laufzeit einer Funktion direkt auf die Antwortzeit von Fynn auswirkt.

## Funktionalitäten in Fynn Functions

Innerhalb von Fynn Functions kannst du alle JavaScript Funktionen verwenden, die auch im Browser verfügbar sind.

## Erweiterungs-Punkte

Fynn Functions unterstützt aktuell folgende Erweiterungs-Punkte:

* [Checkout](#checkout): `checkout.cart.delivery`, `checkout.cart.cart_item_option`

### Lieferkosten hinzufügen

Der `checkout.cart.delivery` Erweiterungs-Punkt kann dazu verwendet werden, um Lieferkosten zum Warenkorb hinzuzufügen.
Ist der Preis der Lieferkosten einmalig, wird dieser nur in der 1. Rechnung berechnet und ist nicht wiederkehrend.
Andernfalls wird der Preis der Lieferkosten in jeder Rechnung berechnet.

#### Kontext-Objekt

<ResponseField name="context" type="DeliveryContext">
  <Expandable title="properties">
    <ResponseField name="cart" type="CartPublic">
      Der aktuelle Warenkorb des Benutzers
    </ResponseField>

    <ResponseField name="deliveryCountryCode" type="string">
      Der Ländercode des Lieferlandes, hierbei wird die Rechnungs- und Lieferadresse des Warenkorbs berücksichtigt.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Operationen

<ResponseField name="checkout:add_delivery" type="AddDelivery">
  <Expandable title="properties">
    <ResponseField name="product" type="string">
      Die Produkt-ID die als Lieferkosten hinzugefügt werden soll.
    </ResponseField>

    <ResponseField name="pricePlan" type="string">
      Der Preisplan der für die Lieferkosten verwendet werden soll. Wird keiner angegeben, wird der 1. Preis im Produkt verwendet.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Beispiel

```typescript theme={null}
function run (input) {
    const countryCode = input?.deliveryCountryCode;
    const itemsCount = input?.cart?.items.length;

  if (itemsCount === 0) return [];

    if (countryCode === 'DE') {
        return [{
            __type: 'checkout:add_delivery',
            product: '14937550-26d0-454a-b4d4-64eabac67663'
        }];
    }

    if (countryCode === 'CH') {
        return [{
            __type: 'checkout:add_delivery',
            product: '5a7f267a-087b-4bdf-a620-79a4e2942545'
        }];
    }

    // more custom logic, e.g. by zip, best price, etc.

    return [];
}
```

### Produkt-Optionen hinzufügen

Der `checkout.cart.cart_item_option` Erweiterungs-Punkt kann dazu verwendet werden, um Auswahl-Optionen im Warenkorb am Produkt anzuzeigen.

<Frame>
  <img alt="Checkout Optionen" />
</Frame>

#### Kontext-Objekt

<ResponseField name="product" type="CartItemProductInput">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Die ID des Produktes
    </ResponseField>

    <ResponseField name="number" type="string">
      Die Produktnummer, sofern diese angegeben ist. Andernfalls ist diese `null`.
    </ResponseField>

    <ResponseField name="customFields" type="array">
      Werte der Benutzerdefinierten Attribute des Produktes.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="context" type="CartItemInput">
  <Expandable title="properties">
    <ResponseField name="cartItem" type="CartPublicItem">
      Das aktuelle Produkt / Warenkorb-Item im Warenkorb
    </ResponseField>

    <ResponseField name="product" type="CartItemProductInput">
      Die aktuelle Produkt-ID
    </ResponseField>
  </Expandable>
</ResponseField>

#### Operationen

<ResponseField name="checkout:add_cart_item_option_set" type="AddCartItemOptionSet">
  <Expandable title="properties">
    <ResponseField name="product" type="string">
      Das Produkt für das die Optionen hinzugefügt werden sollen.
    </ResponseField>

    <ResponseField name="name" type="string">
      Der Name der Optionsauswahl, welcher im Webhook verfügbar ist.
    </ResponseField>

    <ResponseField name="label" type="string">
      Der Name der Optionsauswahl, welcher im Checkout angezeigt wird.
    </ResponseField>

    <ResponseField name="options" type="array">
      Die Optionen die zur Auswahl stehen.
    </ResponseField>
  </Expandable>
</ResponseField>

Alternativ können Produkt-Optionen auf Basis eines [Benutzerdefiniertes Attributes](/guide/tenant/custom-fields) im Produkt hinzugefügt werden.

<ResponseField name="checkout:add_custom_field_list:as_option_set" type="AddCustomFieldListAsOptionSet">
  <Expandable title="properties">
    <ResponseField name="name" type="string">
      Der Name der Optionsauswahl, welcher im Webhook verfügbar ist.
    </ResponseField>

    <ResponseField name="label" type="string">
      Der Name der Optionsauswahl, welcher im Checkout angezeigt wird.
    </ResponseField>

    <ResponseField name="customField" type="string">
      Das Feld welches im Produkt als [Benutzerdefiniertes Attribut](/guide/tenant/custom-fields) (Typ: Liste) verfügbar sein muss,
      um dessen Listen-Optionen anzuzeigen.
    </ResponseField>

    <ResponseField name="preselectRegex" type="string">
      Regex, um eine Listen-Option als Standard vorauszuwählen. Bspw. `/.* \(Aktuell\)/i` (muss (Aktuell) beinhalten).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField type="AddCartItemOption">
  <Expandable title="properties">
    <ResponseField name="preselected" type="boolean">
      Ob die Option vorausgewählt ist.
    </ResponseField>

    <ResponseField name="label" type="string">
      Der Name der Option, welcher im Checkout angezeigt wird.
    </ResponseField>

    <ResponseField name="value" type="string">
      Der Wert der Option, welcher im Webhook verfügbar ist.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Beispiel

```typescript theme={null}
function run(input) {
  return [
    {
      __type: 'checkout:add_cart_item_option_set',
      product: '0ba377f0-d9e9-4338-a107-9209a6e0f1fb',
      name: 'ab Ausgabe',
      label: 'ab Ausgabe',
      options: [
        {
          label: 'Nr. 24',
          value: '24'
        },
        {
          label: 'Nr. 25',
          value: '25',
          preselected: true,
        },
        {
          label: 'Nr. 26',
          value: '26'
        },
      ]
    }
  ];
}
```

## Funktion registrieren

Um eine Funktion zu registrieren, erstelle ein Support-Ticket um den Zugang zu Fynn Functions zu erhalten.

## Globale Kontext-Objekte

```typescript theme={null}
export type CartItemProduct

export type CartPublicCustomerAddress = {
  id: string;
  firstName?: string;
  lastName?: string;
  companyName?: string;
  street: string;
  houseNumber?: string;
  zip: string;
  city: string;
  addition?: string;
  countryCode: string;
  costCentre?: string;
  vatId?: string;
}

export type CartPublicItem = {
  name: string;
  description?: string;
  quantity: number;
  type: 'product' | 'plan' | 'delivery';
  id: string;
  product: {
      id: string;
      number: string | null;
      customFields: Record<string, any>;
  },
  periods?: {
    contractPeriod: string;
    cancellationPeriod: string;
  }[],
  quantityDetails: {
    aggregationType: 'count' | 'count_unique' | 'max' | 'sum' | 'average' | 'last_value';
    unit: string;
    description?: string;
    quantityEditable: boolean;
  },
  price: {
    currencyCode: string;
    taxRate?: number;
    totalNetAmount: number;
    type: 'recurring' | 'instant_metered' | 'metered';
    calculationType: 'flat_fee' | 'per_unit' | 'tiered' | 'volume' | 'stair_step' | 'percentage';
    payInAdvance: boolean;
    freeUnits?: number;
    price: {
      amount?: number;
      items?: {
        from: number;
        to?: number;
        amount: number;
        flatAmount: number;
      },
      percentage?: number;
      fixedAmount?: number;
    };
    recurring?: {
      interval: 'day' | 'week' | 'month' | 'year';
      intervalCount?: number;
      trialPeriodDays?: number;
      recurringAmount?: number;
    }
  },
  optionSets: CartPublicItemOptionSet[];
}

export type CartPublicItemOptionSet = {
  label: string;
  name: string;
  options: CartPublicItemOption[];
}

export type CartPublicItemOption = {
  label: string;
  value: string | number | boolean;
  preselected: boolean;
  product?: string | null;
  pricePlan?: string | null;
}

export type CartDiscountDetails = {
  discount: {
    code: string;
    name: string;
    type: 'percentage' | 'fixed_amount';
    percentage?: number;
    fixedAmount?: string;
    frequency: 'once' | 'limited' | 'lifetime';
    frequencyInterval?: number;
  };
  totalAmount: string;
  totalNetBeforeDiscount: string;
};

export type CartPublicPrice = {
  amountDue: number;
  currencyCode: string;
  netAmount?: number;
  taxes?: {
    netAmount: number;
    taxAmount: number;
    rate: number;
  }[];
  discountDetails?: CartDiscountDetails;
}

export type CartPublicSettings = {
  allowCoupons: boolean;
  forceCompany: boolean;
  backButton?: {
    label?: string;
    url: string;
  };
  showDeliveryAddress: boolean;
}

export type CartPublic = {
  id: string;
  customer?: string;
  email?: string;
  invoiceAddress?: CartPublicCustomerAddress;
  deliveryAddress?: CartPublicCustomerAddress;
  items: CartPublicItem[];
  price: CartPublicPrice;
  completionDetails?: {
    invoice: {
      number: string;
      downloadLink: string;
      amount: string;
    } | null,
    payment: {
      reference: string | null;
      method: string;
      bankAccount?: {
        iban: string;
        bic: string;
        bankName: string;
        accountHolder: string;
        reference: string;
      },
      qrCode?: string;
    },
    subscription?: {
      number: string;
    },
    confirmationMessage?: string;
    backToProviderUrl?: string | null;
  },
  settings: CartPublicSettings;
}
```


# Belegvorlagen & Platzhalter
Source: https://docs.fynn.eu/guide/invoices/document-templates

Alle verfügbaren Platzhalter für PDF-Belegvorlagen nach Dokumenttyp

Fynn generiert PDFs für verschiedene Belegtypen. Jede Vorlage unterstützt Platzhalter, die beim Erstellen des Dokuments automatisch durch die tatsächlichen Werte ersetzt werden.

## Dokumenttypen

Fynn unterstützt folgende Belegtypen mit eigenen PDF-Vorlagen:

| Dokumenttyp               | Beschreibung                           | Verfügbare Platzhalter          |
| ------------------------- | -------------------------------------- | ------------------------------- |
| **Rechnung**              | Standardrechnung                       | Beleg, Organisation, Abonnement |
| **Gutschrift**            | Gutschrift / Erstattung                | Beleg, Organisation, Abonnement |
| **Storno**                | Stornierung einer Rechnung             | Beleg, Organisation, Abonnement |
| **Mahnung**               | Mahnschreiben                          | Mahnung, Organisation           |
| **Kündigungsbestätigung** | Bestätigung einer Abonnement-Kündigung | Abonnement, Organisation        |

<Info>
  Rechnungen, Gutschriften und Stornos verwenden dieselben Platzhalter — sie basieren alle auf dem Belegmodell. Die Referenzfelder (z.B. `referencedInvoiceNumber`) sind nur bei Gutschriften und Stornos gefüllt.
</Info>

## Vorlagen bearbeiten

<Steps>
  <Step title="Einstellungen öffnen">
    Gehe zu [Einstellungen > Belege](https://app.fynn.eu/settings/invoices) und scrolle zu **Vorlagen**.
  </Step>

  <Step title="Vorlage auswählen">
    Klicke auf **Bearbeiten** bei der gewünschten Vorlage (Rechnung, Storno, Gutschrift oder Mahnung) und wähle die Sprache.
  </Step>

  <Step title="Platzhalter einfügen">
    Verwende die unten aufgeführten Platzhalter in den Feldern Titel, Einleitung, Abschlusstext und Informationsfelder. Platzhalter werden in doppelten geschweiften Klammern geschrieben: `{{ platzhalter }}`.
  </Step>
</Steps>

## Platzhalter nach Kategorie

### Beleginformationen

Verfügbar für: **Rechnung**, **Gutschrift**, **Storno**

| Platzhalter        | Beschreibung          | Beispielwert              |
| ------------------ | --------------------- | ------------------------- |
| `documentNumber`   | Belegnummer           | `RE-2026-0001`            |
| `documentDate`     | Belegdatum            | `15.02.2026`              |
| `totalGrossAmount` | Gesamtbetrag (brutto) | `119,00 €`                |
| `dueDate`          | Fälligkeitsdatum      | `01.03.2026`              |
| `dueDateInDays`    | Tage bis Fälligkeit   | `14`                      |
| `servicePeriod`    | Leistungszeitraum     | `01.02.2026 - 28.02.2026` |
| `customerNumber`   | Kundennummer          | `KD-10042`                |
| `dunningLevel`     | Mahnstufe             | `1`                       |

### Referenz-Beleg

Verfügbar für: **Gutschrift**, **Storno** (Felder der ursprünglichen Rechnung)

| Platzhalter                         | Beschreibung                           | Beispielwert   |
| ----------------------------------- | -------------------------------------- | -------------- |
| `referencedInvoiceNumber`           | Nummer der Ursprungsrechnung           | `RE-2026-0001` |
| `referencedInvoiceDate`             | Datum der Ursprungsrechnung            | `01.02.2026`   |
| `referencedInvoiceDueDate`          | Fälligkeitsdatum der Ursprungsrechnung | `15.02.2026`   |
| `referencedInvoiceTotalGrossAmount` | Bruttobetrag der Ursprungsrechnung     | `119,00 €`     |

### Zahlungsmethode

Verfügbar für: **Rechnung**, **Gutschrift**, **Storno**

| Platzhalter                 | Beschreibung                    | Beispielwert       |
| --------------------------- | ------------------------------- | ------------------ |
| `paymentMethod.displayName` | Anzeigename der Zahlungsmethode | `SEPA-Lastschrift` |
| `paymentMethod.type`        | Typ der Zahlungsmethode         | `sepa_debit`       |
| `paymentMethod.gatewayName` | Name des Payment-Gateways       | `stripe`           |
| `paymentMethod.name`        | Interner Name                   | `SEPA Hauptkonto`  |

### SEPA-Lastschrift

Verfügbar für: **Rechnung**, **Gutschrift**, **Storno** (nur bei SEPA-Zahlungsmethode)

| Platzhalter                                               | Beschreibung                            | Beispielwert                  |
| --------------------------------------------------------- | --------------------------------------- | ----------------------------- |
| `isSepa`                                                  | Ist SEPA-Lastschrift aktiv              | `true` / `false`              |
| `sepa.iban`                                               | IBAN des Kunden                         | `DE89 3704 0044 0532 0130 00` |
| `sepa.bic`                                                | BIC des Kunden                          | `COBADEFFXXX`                 |
| `sepa.accountHolder`                                      | Kontoinhaber                            | `Max Mustermann`              |
| `sepa.mandateReference`                                   | SEPA-Mandatsreferenz                    | `MNDT-2026-00001`             |
| `sepa.creditorId`                                         | Gläubiger-ID                            | `DE98ZZZ09999999999`          |
| `sepa.bankName`                                           | Bankname                                | `Commerzbank`                 |
| `sepa.amount`                                             | Einzugsbetrag                           | `119,00 €`                    |
| `paymentMethod.sepa.mandateReferenceNumber`               | Mandatsreferenznummer                   | `MNDT-2026-00001`             |
| `paymentMethod.sepa.mandateReferenceSigningDate`          | Mandats-Unterschriftsdatum              | `2025-01-15`                  |
| `paymentMethod.sepa.mandateReferenceSigningDateFormatted` | Mandats-Unterschriftsdatum (formatiert) | `15.01.2025`                  |
| `paymentMethod.sepa.iban`                                 | IBAN (formatiert)                       | `DE89 3704 0044 0532 0130 00` |
| `paymentMethod.sepa.bic`                                  | BIC                                     | `COBADEFFXXX`                 |
| `paymentMethod.sepa.bankName`                             | Bankname                                | `Commerzbank`                 |
| `paymentMethod.sepa.accountHolder`                        | Kontoinhaber                            | `Max Mustermann`              |
| `paymentMethod.sepa.isFirstSepaDebit`                     | Ersteinzug                              | `true` / `false`              |
| `paymentMethod.sepa.creditorIdentificationNumber`         | Gläubiger-ID                            | `DE98ZZZ09999999999`          |

### Überweisung

Verfügbar für: **Rechnung**, **Gutschrift**, **Storno** (nur bei Überweisung)

| Platzhalter                     | Beschreibung          | Beispielwert             |
| ------------------------------- | --------------------- | ------------------------ |
| `isBankTransfer`                | Ist Überweisung aktiv | `true` / `false`         |
| `bankTransfer.iban`             | IBAN des Empfängers   | `DE89370400440532013000` |
| `bankTransfer.bic`              | BIC des Empfängers    | `COBADEFFXXX`            |
| `bankTransfer.accountHolder`    | Kontoinhaber          | `Fynn GmbH`              |
| `bankTransfer.bankName`         | Bankname              | `Commerzbank`            |
| `bankTransfer.amount`           | Überweisungsbetrag    | `119,00 €`               |
| `bankTransfer.usageDescription` | Verwendungszweck      | `RE-2026-0001`           |

### Kundeninformationen

Verfügbar für: **Rechnung**, **Gutschrift**, **Storno**

| Platzhalter          | Beschreibung | Beispielwert |
| -------------------- | ------------ | ------------ |
| `customer.firstName` | Vorname      | `Max`        |
| `customer.lastName`  | Nachname     | `Mustermann` |

### Organisationsinformationen

Verfügbar für: **alle Dokumenttypen**

| Platzhalter                   | Beschreibung           | Beispielwert             |
| ----------------------------- | ---------------------- | ------------------------ |
| `tenant.name`                 | Handelsname            | `Fynn`                   |
| `tenant.legalCompanyName`     | Rechtlicher Firmenname | `Fynn GmbH`              |
| `tenant.street`               | Straße                 | `Barthelstr.`            |
| `tenant.housenumber`          | Hausnummer             | `4`                      |
| `tenant.zip`                  | Postleitzahl           | `50823`                  |
| `tenant.city`                 | Stadt                  | `Köln`                   |
| `tenant.countryCode`          | Ländercode             | `DE`                     |
| `tenant.email`                | E-Mail-Adresse         | `hi@fynn.eu`             |
| `tenant.phone`                | Telefonnummer          | `0221 29246377`          |
| `tenant.vatId`                | USt-IdNr.              | `DE123456789`            |
| `tenant.website`              | Website                | `https://fynn.eu`        |
| `tenant.ceo`                  | Geschäftsführer        | `Giuliano Schindler`     |
| `tenant.bankAccount.iban`     | IBAN                   | `DE89370400440532013000` |
| `tenant.bankAccount.bic`      | BIC                    | `COBADEFFXXX`            |
| `tenant.bankAccount.bankName` | Bankname               | `Commerzbank`            |

### Abonnementinformationen

Verfügbar für: **Rechnung**, **Gutschrift**, **Storno**, **Kündigungsbestätigung**

| Platzhalter                       | Beschreibung                                          | Beispielwert      |
| --------------------------------- | ----------------------------------------------------- | ----------------- |
| `customerNumber`                  | Kundennummer                                          | `KD-10042`        |
| `subscription.number`             | Abonnementnummer(n)                                   | `SUB-2026-00001`  |
| `subscription.name`               | Abonnementname(n)                                     | `Enterprise Plan` |
| `subscription.poNumber`           | Bestellnummer(n) (PO)                                 | `PO-12345`        |
| `subscription.customFields.<key>` | Wert eines benutzerdefinierten Feldes des Abonnements | `LS-2024-001`     |

<Info>
  Bei Rechnungen mit **mehreren Abonnements** werden die Werte mit Komma getrennt zusammengefasst (z.B. `SUB-001, SUB-002`). Bei manuell erstellten Rechnungen ohne Abonnement-Bezug werden die Platzhalter als leere Zeichenkette aufgelöst.
</Info>

### Mahnungsinformationen

Verfügbar für: **Mahnung**

| Platzhalter                         | Beschreibung                                                        | Beispielwert   |
| ----------------------------------- | ------------------------------------------------------------------- | -------------- |
| `documentNumber`                    | Mahnnummer                                                          | `MH-2026-0001` |
| `documentDate`                      | Datum der Mahnung                                                   | `15.03.2026`   |
| `referencedInvoiceNumber`           | Nummer der gemahnten Rechnung                                       | `RE-2026-0001` |
| `referencedInvoiceDate`             | Datum der gemahnten Rechnung                                        | `01.02.2026`   |
| `referencedInvoiceDueDate`          | Fälligkeitsdatum der gemahnten Rechnung                             | `15.02.2026`   |
| `referencedInvoiceTotalGrossAmount` | Offener Restbetrag der gemahnten Rechnung (abzüglich Teilzahlungen) | `119,00 €`     |
| `totalGrossAmount`                  | Offener Restbetrag inkl. Mahngebühren                               | `129,00 €`     |
| `dueDate`                           | Fälligkeitsdatum der Mahnung                                        | `29.03.2026`   |
| `customerNumber`                    | Kundennummer                                                        | `KD-10042`     |
| `dueDateInDays`                     | Tage bis Fälligkeit                                                 | `14`           |
| `dunningLevel`                      | Mahnstufe                                                           | `2`            |

### Angebotsinformationen

Verfügbar für: **Angebote**

| Platzhalter    | Beschreibung   | Beispielwert       |
| -------------- | -------------- | ------------------ |
| `offer.number` | Angebotsnummer | `AG-2026-0001`     |
| `offer.name`   | Angebotsname   | `Enterprise Paket` |

## Platzhalter-Format

Platzhalter können in verschiedenen Formaten verwendet werden:

```
{{ documentNumber }}
{{ $documentNumber }}
{{documentNumber}}
{{$documentNumber}}
```

<Note>
  Alle Datumsangaben werden im Format `dd.mm.yyyy` (z.B. `15.02.2026`) ausgegeben. Geldbeträge werden im deutschen Format mit Währungssymbol formatiert (z.B. `119,00 €`).
</Note>

## Platzhalter per API abrufen

Du kannst die verfügbaren Platzhalter auch programmatisch abrufen:

```
GET /ui/document-placeholder?contexts=invoice,tenant,subscription
```

Mögliche Kontexte: `invoice`, `dunning`, `tenant`, `subscription`

## Positionsgruppen-Format

Der Name der Positionsgruppen auf Rechnungen kann unter [Einstellungen > Abrechnung](https://app.fynn.eu/settings/billing) konfiguriert werden. Das Format unterstützt Variablen und Bedingungen.

### Verfügbare Variablen

| Variable                          | Beschreibung             | Beispielwert      |
| --------------------------------- | ------------------------ | ----------------- |
| `subscription.name`               | Abonnementname           | `Enterprise Plan` |
| `subscription.number`             | Abonnementnummer         | `SUB-001`         |
| `subscription.poNumber`           | Bestellnummer (PO)       | `PO-12345`        |
| `subscription.customFields.<key>` | Benutzerdefiniertes Feld | `LS-2024-001`     |

### Standardformat

```
{{ subscription.name }}{% if subscription.poNumber %} - PO Number: {{ subscription.poNumber }}{% endif %}
```

Ergebnis: `Enterprise Plan - PO Number: PO-12345` (oder nur `Enterprise Plan`, wenn keine PO-Nummer vorhanden ist).

### Beispiel mit benutzerdefiniertem Feld

```
{{ subscription.name }}{% if subscription.customFields.lieferscheinNummer is defined and subscription.customFields.lieferscheinNummer %} (LS: {{ subscription.customFields.lieferscheinNummer }}){% endif %}
```

Ergebnis: `Enterprise Plan (LS: LS-2024-001)` — oder nur `Enterprise Plan`, wenn das Feld nicht vorhanden ist.

<Warning>
  Benutzerdefinierte Felder müssen mit `is defined and` geprüft werden, da die Schlüssel nicht bei jedem Abonnement vorhanden sind. Direkte Eigenschaften wie `poNumber` können einfach mit `{% if subscription.poNumber %}` geprüft werden.
</Warning>

## Custom PDF Rendering

Wenn du vollständige Kontrolle über das PDF-Layout benötigst, kannst du mit [Custom PDF Rendering](/integrations/custom-pdf-rendering) deine eigene PDF-Engine verwenden. Alle oben aufgeführten Platzhalter stehen auch im Webhook-Payload zur Verfügung.


# e-Rechnung
Source: https://docs.fynn.eu/guide/invoices/e-invoicing

Erstelle und verwalte deine Rechnungen

## Was ist eine e-Rechnung?

Eine e-Rechnung ist eine elektronische Rechnung, die digital erstellt, versendet und empfangen wird.
Sie ersetzt die klassische Papierrechnung und ist in der Regel in einem standardisierten Format wie z. B. XRechnung oder ZUGFeRD erstellt.
Dies ermöglicht einen automatisierten Empfang und Verarbeitung der Rechnung, was die Rechnungsstellung effizienter und kostengünstiger macht.

Die e-Rechnung ist ab dem 01.01.2025 für deutsche Unternehmen im Empfang verpflichtend.

## Support für e-Rechnungen

Fynn ist **vollständig kompatibel mit dem e-Rechnungsstandard** in Deutschland und Europa, was bedeutet, dass du e-Rechnungen direkt aus Fynn heraus im PDF und XML Format erstellen und versenden kannst.

## Aktivierung der e-Rechnung

Alle Rechnungen, Stornos und Gutschriften werden **automatisch** im PDF und XML Format (ZUGFeRD) erstellt und versendet und sind somit gültige e-Rechnungen.

### Einstellungen

Du hast die Möglichkeit, den elektronischen Rechnungstyp für den Kunden zu aktivieren.
Dies ist insbesondere für Behörden und öffentliche Einrichtungen relevant.

<Check>
  Standardmäßig ist die elektronische Rechnung (ZUGFeRD) für den Kunden aktiviert.
</Check>

Hier kannst du folgende Optionen auswählen:

* "ZUGFeRD" (Standard)
* "XRechnung"

<Frame>
  <img alt="Elektronische Rechnung" />
</Frame>

### Öffentliche Auftraggeber

Um Rechnungen bspw. an öffentliche Auftraggeber zu senden, kannst du dies in den Kunden-Einstellungen aktivieren:

<Steps>
  <Step title="Kunden-Einstellungen">
    Gehe zu einem Kunden und wähle unter "elektronische Rechnung" das entsprechende Format aus (x-Rechnung bspw.).

    <Frame>
      <img alt="Elektronische Rechnung" />
    </Frame>
  </Step>

  <Step title="Leitweg-ID hinterlegen">
    Hinterlege die Leitweg-ID des Kunden. Diese wird benötigt, um die Rechnung an den öffentlichen Auftraggeber zu senden.
  </Step>

  <Step title="Einstellungen speichern">
    Speichere die Einstellungen und erstelle die Rechnung. Diese wird automatisch im gewünschten Format erstellt.

    <Info>
      Die Rechnung wird im entsprechenden XML Format erstellt, allerdings nicht digital über bspw. Peppol versendet. Dieses Feature ist in Planung.
    </Info>
  </Step>
</Steps>


# Exporte
Source: https://docs.fynn.eu/guide/invoices/exports

Exportiere Rechnungen und offene Posten

## OPOS-Liste exportieren

Mit der OPOS-Liste kannst du offene Posten (offene Rechnungen) im CSV-Format exportieren, um sie beispielsweise für die Buchhaltung zu verwenden.

Hierfür navigiere zu `Belege` > `Rechnungen` und klicke auf `Exportieren`.

<Frame>
  <img alt="OPOS-Liste exportieren" />
</Frame>

## Tabellenansicht exportieren

Die Tabelle kann nun vollständig an die eigenen Bedürfnisse angepasst werden und die aktuelle Tabellenansicht als CSV exportiert werden.

Zum Export klicke auf `Exportieren` und wähle dort "Tabellenansicht" aus.

<Frame>
  <img alt="Rechnungs-Liste" />
</Frame>

## Rechnungs-Liste filtern

Die Rechnungs‑, Zahlungs‑ und Abonnement‑Listen verfügen über einen leistungsfähigen Filterbereich (z.B. für Text-, Datums- und Betragsfilter).

Eine allgemeine Einführung findest du unter [Listen und Tabellen](/guide/list-views).
Konkrete Beispiele für Rechnungen, Zahlungen und Abos findest du unter [Filter für Rechnungen, Zahlungen und Abos](/guide/invoices/list-filters).


# Übersicht
Source: https://docs.fynn.eu/guide/invoices/introduction

Erstelle und verwalte deine Rechnungen

Über das Rechnungsmodul von Fynn kannst du alle deine Rechnungen verwalten, neue Rechnungen erstellen und bestehende Rechnungen bearbeiten. Diese Seite gibt dir einen Überblick über die wichtigsten Funktionen.

## Rechnungen erstellen

### Manuelle Rechnungserstellung

Du kannst jederzeit manuell eine neue Rechnung erstellen:

1. Klicke auf das `+` oben rechts
2. Wähle "Rechnung" aus
3. Wähle den Kunden aus
4. Füge Rechnungspositionen hinzu
5. Klicke auf `Entwurf erstellen` oder `Finalisieren und versenden`

<Frame>
  <img alt="Manuelle Rechnungserstellung" />
</Frame>

### Automatische Rechnungserstellung

Rechnungen für Abonnements werden automatisch zum konfigurierten Zeitpunkt erstellt. Die Rechnungsstellung erfolgt dabei:

* Zum Beginn einer neuen Abrechnungsperiode
* Bei Änderungen des Abonnements (anteilige Berechnung)
* Bei zusätzlichen Gebühren oder Gutschriften

### Finalisieren und versenden

Nachdem du eine Rechnung erstellt hast, kannst du sie finalisieren und an den Kunden senden.

Dabei passiert Folgendes:

* Die Rechnung wird als PDF und / oder e-Rechnungs-XML generiert
* Der Kunde erhält eine E-Mail mit der Rechnung als Anhang, sofern die Benachrichtigungseinstellungen aktiviert sind
* Passende Buchungssätze werden automatisch erstellt
* Die Rechnung wird im Status `Offen` markiert
* Der Zahlungseinzug wird angestoßen
* Die Rechnung wird bei Bedarf an die [BCC-Empfänger gesendet](/guide/accounting/introduction#zusaezliche-rechnungs-empfaenger)

## Benachrichtigungen

### Rechnung erneut per E-Mail senden

Du kannst eine Rechnung jederzeit erneut per E-Mail an deinen Kunden senden:

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Rechnung öffnen">
        Navigiere zur gewünschten Rechnung in der Rechnungsübersicht
      </Step>

      <Step title="Aktion auswählen">
        Klicke auf `Aktionen` > `Erneut versenden`
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Rechnung erneut senden](/api-reference/invoice/resend-invoice) Endpunkt.

    ```bash theme={null}
    PUT /invoices/{id}/resend
    ```
  </Tab>
</Tabs>

Die E-Mail wird dann mit der Rechnung als PDF-Anhang an die hinterlegte E-Mail-Adresse des Kunden gesendet.

## Verlaufsprotokoll

Jede Änderung an einer Rechnung wird im Verlaufsprotokoll dokumentiert. Du findest das Protokoll direkt in der Detailansicht einer Rechnung in dem Bereich "Verlauf". Dort siehst du:

* Wer die Änderung vorgenommen hat
* Was geändert wurde
* Wann die Änderung erfolgte

## Zahlungen

Für Rechnungen können Zahlungen manuell hinzugefügt oder erneut angestoßen werden. Weitere Details findest du unter [Zahlungen verwalten](/guide/payments/manage-payments).

## Zahlungserinnerungen / Mahnungen

<Frame>
  <img alt="Mahnwesen Übersicht" />
</Frame>

In der Mahnwesen-Übersicht siehst du:

* Die aktuelle Mahnstufe
* Das Datum der letzten Erinnerung
* Möglichkeit zum Pausieren des Mahnwesens
* Zugriff auf die Details des Mahnprozesses

<Note>
  Du kannst das Mahnwesen für einzelne Rechnungen pausieren. Dies ist nützlich, wenn du beispielsweise:

  * Mit dem Kunden eine Ratenzahlung vereinbart hast
  * Eine Zahlungsfrist verlängert wurde
  * Auf eine ausstehende Gutschrift gewartet wird

  Wenn du das Mahnwesen später wieder aktivierst, wird automatisch die nächste zutreffende Mahnstufe angewendet.

  **Beispiel:**

  1. Eine Rechnung ist seit 10 Tagen überfällig und in Mahnstufe 1
  2. Du pausierst das Mahnwesen für 14 Tage wegen Ratenzahlungsvereinbarung
  3. Nach Aktivierung (Tag 24) greift automatisch Mahnstufe 2, da die Frist für Mahnstufe 1 (z.B. 7 Tage) bereits überschritten ist
</Note>

Weitere Details findest du unter [Zahlungsausfälle](/guide/dunning/introduction).

## Rechnungen stornieren

<Info>
  Eine Rechnung kann nur storniert werden, wenn:

  * Noch keine Zahlung eingegangen ist
  * Bei Inhouse-SEPA: Die SEPA-Datei noch nicht als "hochgeladen" markiert wurde
</Info>

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Rechnung öffnen">
        Navigiere zur gewünschten Rechnung in der Rechnungsübersicht
      </Step>

      <Step title="Stornierung ausführen">
        Klicke auf `Stornieren`
      </Step>

      <Step title="Stornierung bestätigen">
        Wähle eine der folgenden Optionen:

        * `Ja, stornieren`: Die Rechnung wird einfach storniert
        * `Ja, stornieren und duplizieren`: Die Rechnung wird storniert und eine neue Rechnung mit den gleichen Positionen wird erstellt
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Rechnung stornieren](/api-reference/invoice/cancel-invoice) Endpunkt.

    ```bash theme={null}
    POST /invoices/{id}/cancel
    ```
  </Tab>
</Tabs>

Bei der Stornierung passiert Folgendes:

* Eine Stornorechnung wird erstellt, die die ursprüngliche Rechnung ausgleicht
* Falls [Buchungen](/guide/accounting/introduction) aktiviert sind, werden entsprechende Storno-Buchungen (z.B. PRAP) automatisch ausgeführt
* Der Kunde erhält eine Benachrichtigung per E-Mail, wenn dies in den [Benachrichtigungseinstellungen](/guide/notifications/introduction) aktiviert ist

## Rechnung schließen

Um Rechnungen aus der Übersicht zu entfernen, kannst du sie schließen. Dies ist nützlich, wenn du Rechnungen archivieren möchtest, die nicht mehr relevant sind und noch nicht an den Kunden gesendet wurden.

Voraussetzung für das Schließen einer Rechnung:

* Die Rechnung ist im Status `Entwurf` oder `Freigabe ausstehend`

Auswirkungen des Schließens:

* Die Rechnung wird in der Übersicht ausgeblendet
* Die Rechnung kann nicht mehr bearbeitet werden
* Die Rechnungsbeträge werden nicht in den Statistiken und Auswertungen berücksichtigt
* Die Rechnung wird im Verlaufsprotokoll als "geschlossen" protokolliert

<Tip>
  Der Kunde wird nicht über das Schließen der Rechnung informiert.
</Tip>

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Rechnung öffnen">
        Navigiere zur gewünschten Rechnung in der Rechnungsübersicht
      </Step>

      <Step title="Rechnung schließen">
        Klicke auf `Aktionen` > `Rechnung schließen`
      </Step>

      <Step title="Schließen bestätigen">
        Bestätige die Schließung der Rechnung mit `Ja, schließen`. Optional kannst du eine Notiz hinzufügen, die im Verlauf protokolliert wird.

        <Frame>
          <img alt="Rechnung schließen" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Rechnung schließen](/api-reference/invoice/close-invoice) Endpunkt.

    ```bash theme={null}
    POST /invoices/{id}/close
    ```
  </Tab>
</Tabs>

## Gutschrift erstellen

Gutschriften können für Rechnungen erstellt werden, um den Rechnungsbetrag zu reduzieren. Dies ist nützlich, wenn beispielsweise:

* Ein Rabatt nachträglich gewährt wird
* Der Rechnungsbetrag korrigiert werden muss
* Ein Produkt zurückgegeben wurde

Um eine Gutschrift zu erstellen, muss für eine Rechnung bereits eine Zahlung erfasst worden sein.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Rechnung öffnen">
        Navigiere zur gewünschten Rechnung in der Rechnungsübersicht
      </Step>

      <Step title="Gutschrift erstellen">
        Klicke auf `Aktionen` > `Gutschrift erstellen`
      </Step>

      <Step title="Gutschrift bestätigen">
        Wähle die Positionen und die Menge aus, die gutgeschrieben werden sollen. Zudem kannst du einen individuellen Text für die Gutschrift hinterlegen,
        der auf der Gutschrift unterhalb der Positionen und oberhalb des allgemeinen "Abschluss"-Textes angezeigt wird.

        Der "Abschluss" - Text kann unter "Einstellungen" > "Belege" > "Vorlagen" > "Gutschriften" angepasst werden.

        <Frame>
          <img alt="Gutschrift erstellen" />
        </Frame>
      </Step>

      <Step title="Gutschrift erstellt">
        Die Gutschrift wurde erstellt und die Rechnungsbeträge wurden automatisch angepasst. Die Gutschrift wird im Status `Offen` markiert.

        Anschließend wird:

        * der Kunde über die Gutschrift informiert (sofern in den [Benachrichtigungseinstellungen](/guide/notifications/introduction) aktiviert)
        * die Gutschrift im Verlaufsprotokoll dokumentiert
        * die Buchungssätze automatisch erstellt

        <Info>
          Die Menge der gutgeschriebenen Positionen wird von der Rechnung abgezogen. Die Menge kann also nicht noch einmal gutgeschrieben werden.
        </Info>
      </Step>

      <Step title="Betrag erfassen">
        Um die Gutschrift als `Bezahlt` zu markieren, kannst du eine Zahlung hinzufügen, die dem gutgeschriebenen Betrag entspricht. Der Betrag muss positiv sein.

        Siehe hierzu [Zahlungen verwalten](/guide/payments/manage-payments).
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Gutschrift erstellen](/api-reference/invoice/create-credit-note) Endpunkt.

    ```bash theme={null}
    POST /invoices/{id}/credit-note
    ```
  </Tab>
</Tabs>


# Korrigieren
Source: https://docs.fynn.eu/guide/invoices/invoice-actions

Storniere, erstatte oder korrigiere Rechnungen mit den passenden Aktionen

Wenn du eine Rechnung korrigieren oder anpassen musst, stehen dir verschiedene Aktionen zur Verfügung. Diese Aktionen sind abhängig vom Status der Rechnung und werden automatisch gefiltert, sodass nur die passenden Optionen angezeigt werden.

## Übersicht der Aktionen

Die verfügbaren Aktionen werden dynamisch basierend auf dem Rechnungsstatus ermittelt. Nicht alle Aktionen sind für jede Rechnung verfügbar.

<Info>
  Um eine Aktion auszuführen, klicke auf "Korrigieren" in der Rechnungsdetailansicht. Das System zeigt dir dann alle verfügbaren Aktionen für diese spezifische Rechnung an.
</Info>

## Beleg stornieren

**Wann verfügbar**: Nur für unbezahlte Rechnungen

**Was passiert**:

* Die Rechnung wird storniert und als "nie existiert" behandelt
* Ein Stornobeleg wird erstellt
* Falls Guthaben verwendet wurde, wird dieses automatisch zurückgebucht
* Keine Auszahlung erfolgt, da keine Zahlung eingegangen ist

**Wann verwenden**:

* Die Rechnung wurde fälschlicherweise erstellt
* Noch keine Zahlung wurde geleistet

<Warning>
  Eine Stornierung kann nur durchgeführt werden, wenn noch keine Zahlung eingegangen ist. Bei bereits bezahlten Rechnungen musst du eine andere Aktion wählen.
</Warning>

## Rückerstattung

**Wann verfügbar**: Nur für bezahlte oder teilweise bezahlte Rechnungen

**Was passiert**:

* Eine Gutschrift wird erstellt
* Der Kunde erhält eine Rückerstattung (Auszahlung)
* Die Gutschrift wird als neue Verbindlichkeit behandelt
* Das ursprünglich verwendete Guthaben (falls vorhanden) wird **nicht** zurückgebucht

**Wann verwenden**:

* Der Kunde hat bereits bezahlt und soll sein Geld zurückerhalten
* Ein Produkt wurde zurückgegeben
* Ein Service wurde nicht erbracht und der Kunde soll entschädigt werden

<Note>
  Bei einer Rückerstattung wird das ursprünglich verwendete Guthaben nicht zurückgebucht, da die Gutschrift ein neuer, separater Beleg ist. Die ursprüngliche Rechnung bleibt als abgeschlossene Transaktion bestehen.
</Note>

## Gutschrift für zukünftige Rechnungen

**Wann verfügbar**: Nur für bezahlte oder teilweise bezahlte Rechnungen

**Was passiert**:

* Eine Gutschrift wird erstellt
* Der Gutschriftsbetrag wird dem **Kundenguthaben** hinzugefügt
* Das Guthaben kann automatisch auf zukünftige Rechnungen angewendet werden
* **Keine Auszahlung** erfolgt

**Wann verwenden**:

* Du möchtest dem Kunden einen Rabatt gewähren, der auf zukünftige Rechnungen angewendet wird
* Der Kunde soll eine Gutschrift erhalten, die er später nutzen kann
* Du möchtest dem Kunden Guthaben geben, ohne Geld auszuzahlen

<Note>
  Das hinzugefügte Guthaben wird automatisch auf zukünftige Rechnungen angewendet, sobald diese finalisiert werden. Der Kunde muss dann weniger bezahlen.
</Note>

## Skonto gewähren

**Wann verfügbar**: Nur für finalisierte, teilweise bezahlte Rechnungen

**Was passiert**:

* Eine Anpassung wird auf der Rechnung erstellt
* Der offene Rechnungsbetrag wird reduziert
* Der Kunde muss weniger bezahlen

**Wann verwenden**:

* Du möchtest einen Skonto-Rabatt gewähren (z.B. bei schneller Zahlung)
* Ein Rabatt soll direkt auf die Rechnung angewendet werden

<Info>
  Skonto wird direkt als Anpassung auf der Rechnung erstellt und reduziert den zu zahlenden Betrag.
</Info>

## Gutschrift korrigieren

**Wann verfügbar**: Nur in speziellen Fällen, wenn eine Gutschrift nach einer Stornierung existiert

**Was passiert**:

* Eine Korrektur-Rechnung für die Gutschrift wird erstellt
* Die Gutschrift und die neue Rechnung werden gegenseitig angepasst
* Beide Belege werden als bezahlt markiert
* **Keine Auszahlung** erfolgt

**Wann verwenden**:

* Eine Gutschrift wurde erstellt, aber sollte eigentlich nicht existieren
* Die Gutschrift soll durch eine Rechnung ausgeglichen werden

<Warning>
  Diese Aktion ist ein Edge Case und wird nur in speziellen Situationen angezeigt, beispielsweise wenn nach einer Stornierung eine Gutschrift verbleibt.
</Warning>

## Beleg abschreiben

**Wann verfügbar**: Nur für unbezahlte Rechnungen

**Was passiert**:

* Der Beleg erhält den Status "Abgeschrieben"
* Eine Buchung "Forderungsverlust aus Insolvenz" oder "Forderungsverlust aus Verjährung" wird auf das konfigurierte Konto gebucht: Forderungsverluste 19 % USt (SKR03: 2406, SKR04: 6936), Forderungsverluste 7 % USt (SKR03: 2401, SKR04: 6931) oder Forderungsverluste ohne USt. (SKR03: 2400, SKR04: 6930)
* Die Kontonummern sind in den Buchungskonten-Einstellungen anpassbar
* Bei Abschreibung wegen Insolvenz wird der Kunde in der App als insolvent markiert und offene Zahlungsanforderungen werden gestoppt
* Der Kunde wird nicht per E-Mail benachrichtigt

**Wann verwenden**:

* Eine Forderung ist endgültig uneinbringlich, weil der Kunde zahlungsunfähig ist (Insolvenz) oder die Forderung verjährt ist (Verjährung)

<Warning>
  Für diese Aktion benötigst du die Berechtigung "Rechnungen abschreiben", die einem Benutzer über die Rollenverwaltung zugewiesen werden kann.
</Warning>

<Info>
  Rechnungen mit deutschen Umsatzsteuer-Anteilen werden auf das passende DATEV-Automatikkonto gebucht: Forderungen mit 19 % USt auf das Konto Forderungsverluste, Forderungen mit 7 % USt auf das Konto Forderungsverluste 7 % USt. DATEV korrigiert die Umsatzsteuer nach § 17 UStG automatisch. Rechnungen ohne deutsche Umsatzsteuer, z. B. aus Drittland-Umsätzen oder Reverse-Charge-Leistungen, werden auf das Konto Forderungsverluste ohne USt. gebucht.
</Info>

## Aktionen im Vergleich

| Aktion                                   | Auszahlung? | Guthaben-Impact             | Debitoren-Saldo   | Verfügbar für                               |
| ---------------------------------------- | ----------- | --------------------------- | ----------------- | ------------------------------------------- |
| **Stornieren**                           | Nein        | Guthaben wird zurückgebucht | Wird ausgeglichen | Unbezahlte Rechnungen                       |
| **Rückerstattung**                       | Ja          | Keine Auswirkung            | Wird reduziert    | Bezahlte/teilweise bezahlte Rechnungen      |
| **Gutschrift für zukünftige Rechnungen** | Nein        | Guthaben wird hinzugefügt   | Wird reduziert    | Bezahlte/teilweise bezahlte Rechnungen      |
| **Skonto gewähren**                      | Nein        | Keine Auswirkung            | Wird reduziert    | Finalisierte, teilweise bezahlte Rechnungen |
| **Gutschrift korrigieren**               | Nein        | Keine Auswirkung            | Wird angepasst    | Spezielle Fälle                             |
| **Abschreiben**                          | Nein        | Keine Auswirkung            | Wird ausgeglichen | Unbezahlte Rechnungen                       |

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Warum sehe ich nicht alle Aktionen?">
    Die verfügbaren Aktionen hängen vom Status der Rechnung ab. Das System zeigt nur die Aktionen an, die für den aktuellen Status sinnvoll sind. Beispielsweise kann eine bereits bezahlte Rechnung nicht mehr storniert werden.
  </Accordion>

  <Accordion title="Was passiert mit dem Guthaben bei verschiedenen Aktionen?">
    * **Stornierung**: Guthaben wird zurückgebucht
    * **Rückerstattung**: Keine Auswirkung auf Guthaben
    * **Gutschrift für zukünftige Rechnungen**: Guthaben wird hinzugefügt
  </Accordion>

  <Accordion title="Kann ich eine Aktion rückgängig machen?">
    Nein, Aktionen können nicht direkt rückgängig gemacht werden. Du musst eine neue Aktion ausführen, um das Ergebnis zu korrigieren. Alle Aktionen werden im Verlaufsprotokoll dokumentiert.
  </Accordion>

  <Accordion title="Werden Buchungen automatisch erstellt?">
    Ja, wenn Buchungen in deinen Einstellungen aktiviert sind, werden entsprechende Buchungssätze automatisch erstellt, wenn du eine Aktion ausführst.
  </Accordion>
</AccordionGroup>


# Rechnungsdetails
Source: https://docs.fynn.eu/guide/invoices/invoice-detail

Alle Informationen zu einer Rechnung auf einen Blick

## Übersicht

Die Rechnungsdetailseite bietet dir einen umfassenden Überblick über alle relevanten Informationen einer Rechnung. Du findest hier Kennzahlen, Positionen, Zahlungsinformationen und die vollständige Aktivitätshistorie.

***

## Kennzahlen

Am oberen Rand der Rechnungdetailseite siehst du vier wichtige Kennzahlen:

| Kennzahl         | Beschreibung                                            |
| ---------------- | ------------------------------------------------------- |
| **Bruttobetrag** | Gesamtbetrag des Rechnungs inklusive Mehrwertsteuer     |
| **Bezahlt**      | Summe aller eingegangenen Zahlungen für diesen Rechnung |
| **Offen**        | Noch ausstehender Betrag (Bruttobetrag - Bezahlt)       |
| **Fälligkeit**   | Zahlungsziel des Rechnungs                              |

<Tip>
  Die Kennzahlen haben visuelle Indikatoren:

  * **Bezahlt** wird grün dargestellt, wenn der Rechnung vollständig bezahlt wurde
  * **Offen** wird rot dargestellt, wenn noch ein Betrag aussteht
</Tip>

***

## Tabs

Die Rechnungdetailseite ist in mehrere Tabs unterteilt:

### Übersicht

Der Übersicht-Tab zeigt:

* **Positionen**: Alle Rechnungspositionen mit Menge, Einzelpreis und Gesamtpreis
* **Zusammenfassung**: Nettobetrag, Steuer und Bruttobetrag
* **Abschlusstext**: Der konfigurierte Abschlusstext für den Rechnung

<Info>
  Du kannst alle Positionsdetails mit einem Klick auf "Alle Details anzeigen" aufklappen oder wieder einklappen.
</Info>

### Zahlungen

Der Zahlungen-Tab zeigt alle Transaktionen, die mit diesem Rechnung verknüpft sind:

| Spalte              | Beschreibung                                                                |
| ------------------- | --------------------------------------------------------------------------- |
| **Datum**           | Datum der Zahlung oder Erstellung der Transaktion                           |
| **Status**          | Aktueller Status der Transaktion (z.B. Ausstehend, Bezahlt, Fehlgeschlagen) |
| **Zahlungsmethode** | Verwendete Zahlungsmethode (z.B. VISA, SEPA, PayPal)                        |
| **Betrag**          | Betrag der Transaktion                                                      |
| **Beschreibung**    | Interne Referenznummer der Transaktion                                      |

#### Ausstehende Zahlungen

Bei ausstehenden Zahlungen (Status "Ausstehend", "In Bearbeitung" oder "Autorisiert") wird neben dem Betrag ein Info-Symbol angezeigt. Beim Überfahren mit der Maus erscheint ein Tooltip mit dem Hinweis "Dieser Betrag wird in Kürze eingezogen".

<Note>
  Falls beim Laden der Zahlungen ein Fehler auftritt, kannst du über den "Erneut versuchen"-Button die Daten neu laden.
</Note>

### Verlauf

Der Verlauf-Tab dokumentiert alle Aktivitäten und Änderungen am Rechnung:

* Erstellung und Finalisierung
* Statusänderungen
* Zahlungseingänge
* E-Mail-Versand
* Manuelle Notizen und Kommentare

Du kannst im Verlauf auch eigene Kommentare hinzufügen, um wichtige Informationen zu dokumentieren.

***

## Seitenleiste

Die rechte Seitenleiste zeigt zusätzliche Informationen:

### Rechnungdetails

* **Rechnungnummer**: Eindeutige Nummer des Rechnungs
* **Rechnungdatum**: Datum der Finalisierung
* **Leistungszeitraum**: Zeitraum, auf den sich die Leistung bezieht
* **Abonnement**: Verknüpftes Abonnement (falls vorhanden)
* **Zahlungsmethode**: Aktuell zugewiesene Zahlungsmethode

### Kundeninformationen

* **Kunde**: Name und Kundennummer
* **Rechnungsadresse**: Vollständige Rechnungsadresse

### Verknüpfte Rechnunge

Bei Gutschriften oder Stornorechnungen werden hier die verknüpften Rechnunge angezeigt:

* **Storno-Rechnung**: Verweis auf den stornierten Rechnung
* **Original-Rechnung**: Verweis auf die ursprüngliche Rechnung
* **Referenz-Rechnung**: Verweis auf referenzierte Rechnunge

### Mahnwesen

<Info>
  Der Mahnwesen-Bereich wird nur bei offenen Rechnungen angezeigt.
</Info>

Der Mahnwesen-Bereich zeigt:

* Aktuelle Mahnstufe
* Status des Mahnwesens (aktiv, pausiert, abgeschlossen)
* Möglichkeit zum Pausieren oder Fortsetzen

Weitere Details findest du unter [Zahlungsausfälle](/guide/dunning/introduction).

***

## Status-Banner

Je nach Status des Rechnungs werden am oberen Rand Banner angezeigt:

| Status               | Banner                                             |
| -------------------- | -------------------------------------------------- |
| **Wird finalisiert** | Blauer Info-Banner während der Finalisierung       |
| **Storniert**        | Gelber Warn-Banner mit Hinweis auf Stornierung     |
| **Geschlossen**      | Grauer Banner bei manuell geschlossenen Rechnungen |

***

## Aktionen

Über den "Aktionen"-Button in der Kopfzeile stehen dir verschiedene Optionen zur Verfügung:

<AccordionGroup>
  <Accordion title="Erneut versenden">
    Sendet den Rechnung erneut per E-Mail an den Kunden.

    Siehe auch: [Rechnung erneut senden](/guide/invoices/introduction#rechnung-erneut-per-e-mail-senden)
  </Accordion>

  <Accordion title="Zahlungsart ändern">
    Ändert die Zahlungsmethode und stößt einen neuen Zahlungseinzug an.

    Siehe auch: [Zahlung erneut anstoßen](/guide/invoices/introduction#zahlung-erneut-anstossen)
  </Accordion>

  <Accordion title="Zahlung hinzufügen">
    Erfasst eine manuelle Zahlung für den Rechnung.

    Siehe auch: [Zahlung hinzufügen](/guide/invoices/add-payment)
  </Accordion>

  <Accordion title="Gutschrift erstellen">
    Erstellt eine Gutschrift für ausgewählte Positionen.

    Siehe auch: [Gutschrift erstellen](/guide/invoices/create-credit)
  </Accordion>

  <Accordion title="Stornieren">
    Storniert den Rechnung und erstellt automatisch eine Stornorechnung.

    Siehe auch: [Rechnung stornieren](/guide/invoices/cancel-invoice)
  </Accordion>

  <Accordion title="Finalisieren">
    Finalisiert den Rechnung und generiert das PDF. Nach der Finalisierung kann der Rechnung nicht mehr bearbeitet werden.

    <Note>
      Diese Option ist für alle Rechnungtypen (Rechnung, Gutschrift, Storno) im Status "Entwurf" verfügbar.
    </Note>
  </Accordion>

  <Accordion title="Vorschau">
    Zeigt eine Vorschau des PDFs an, bevor der Rechnung finalisiert wird.

    <Note>
      Diese Option ist für alle Rechnungtypen (Rechnung, Gutschrift, Storno) im Status "Entwurf" verfügbar.
    </Note>
  </Accordion>

  <Accordion title="Rechnung schließen">
    Schließt den Rechnung und entfernt ihn aus der aktiven Übersicht.

    <Note>
      Diese Option ist für alle Rechnungtypen (Rechnung, Gutschrift, Storno) im Status "Entwurf" verfügbar.
    </Note>
  </Accordion>
</AccordionGroup>

***

## PDF-Vorschau

<Tabs>
  <Tab title="Finalisierte Rechnunge">
    Bei finalisierten Rechnungen wird das PDF direkt in der Detailansicht angezeigt. Du kannst:

    * Das PDF vergrößern/verkleinern
    * Das PDF herunterladen
    * Zur E-Rechnung wechseln (falls vorhanden)
  </Tab>

  <Tab title="Entwürfe">
    Bei Entwürfen kannst du über den "Vorschau"-Button eine Vorschau des PDFs generieren, um das finale Aussehen zu prüfen.
  </Tab>
</Tabs>

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Warum ist die Zahlung ausstehend?">
    Eine Zahlung kann aus verschiedenen Gründen ausstehend sein:

    * **Banküberweisung**: Der Kunde muss die Zahlung manuell ausführen
    * **SEPA-Lastschrift**: Die Abbuchung wird innerhalb der nächsten Tage durchgeführt
    * **Kreditkarte**: Die Autorisierung wurde erteilt, aber noch nicht eingezogen

    Der genaue Status wird im Zahlungen-Tab angezeigt.
  </Accordion>

  <Accordion title="Was bedeutet der rote 'Offen'-Betrag?">
    Ein roter "Offen"-Betrag zeigt an, dass der Rechnung noch nicht vollständig bezahlt wurde. Der Betrag entspricht der Differenz zwischen Bruttobetrag und bereits eingegangenen Zahlungen.

    Sobald der Rechnung vollständig bezahlt ist, wird der "Offen"-Betrag schwarz mit "0,00 €" angezeigt und "Bezahlt" wird grün dargestellt.
  </Accordion>

  <Accordion title="Kann ich den Zahlungen-Tab auch bei Entwürfen sehen?">
    Nein, der Zahlungen-Tab ist nur bei finalisierten Rechnungen verfügbar. Bei Entwürfen können noch keine Zahlungen eingehen.
  </Accordion>

  <Accordion title="Wie kann ich eine fehlgeschlagene Zahlung wiederholen?">
    Klicke auf "Aktionen" > "Zahlungsart ändern" und wähle eine neue Zahlungsmethode aus. Der ausstehende Betrag wird automatisch über die neue Zahlungsmethode eingezogen.
  </Accordion>
</AccordionGroup>

<Snippet />


# Filter für Rechnungen, Zahlungen und Abos
Source: https://docs.fynn.eu/guide/invoices/list-filters

Beispiele, wie du die Tabellenfilter in den Rechnungs-, Zahlungs- und Abonnementlisten einsetzt.

Auf dieser Seite findest du konkrete Beispiele, wie du die Filter in den Listen für **Rechnungen**, **Zahlungen** und **Abonnements** einsetzen kannst.

Eine allgemeine Einführung in Listen und Tabellen (inkl. Spalten, Sortierung und Ansichten) findest du unter\
[Listen und Tabellen](/guide/list-views).

## Textfilter – flexible Suche in Zeichenfeldern

Textfilter kannst du z.B. für folgende Felder nutzen:

* Rechnungen:
  * **Belegnummer**
  * **Kundennummer**
  * **Kundenname**
  * **Interne Notiz**
* Abonnements:
  * **Abonummer**
  * **Name**
  * **Kundennummer** / **Kundenname**
  * **PO-Nummer**
* Zahlungen:
  * **Zahlungsnummer**
  * **Rechnungsnummer**
  * **Beschreibung**

Alle Text‑Filteroperatoren sind **case‑insensitive** – Groß-/Kleinschreibung spielt also keine Rolle.

### Verfügbare Möglichkeiten

* **Ist gleich**\
  Findet Einträge, bei denen der Text genau übereinstimmt.\
  Beispiel: Eine bestimmte Kundennummer oder Belegnummer.

* **Enthält**\
  Findet Einträge, in denen ein Wort oder Teilwort vorkommt.\
  Beispiel: Alle Beschreibungen, in denen „fehlgeschlagen“ vorkommt.

* **Ist ungleich**\
  Schließt einen bestimmten Text explizit aus.\
  Beispiel: Alle Einträge außer einem bestimmten Status oder Namen.

* **Enthält nicht**\
  Schließt alle Einträge aus, die einen bestimmten Text enthalten.\
  Beispiel: Alle internen Notizen ohne das Wort „Test“.

* **Ist leer / Ist nicht leer**\
  Filtert nach leeren bzw. nicht‑leeren Textfeldern, z.B. „Interne Notiz ist leer“.

## Datumsfilter – vor, nach, an einem Tag

Für Datumsfelder wie z.B. **Erstellt am**, **Fällig am**, **Abgebucht am** oder **Nächste Abrechnung** stehen dir folgende Möglichkeiten zur Verfügung:

* **Ab einem Datum** – zeigt alle Einträge ab diesem Tag (einschließlich)
* **Bis zu einem Datum** – zeigt alle Einträge bis zu diesem Tag (einschließlich)
* **Genau an einem Tag** – zeigt nur Einträge, die an diesem Kalendertag liegen
* **Zeitraum von/bis** – zeigt Einträge zwischen zwei Daten

### „Genau an einem Tag“

Wenn du „Genau an einem Tag“ auswählst, werden alle Einträge berücksichtigt, deren Datum an diesem Kalendertag liegt – unabhängig von der Uhrzeit.

<Tip>
  Wir berücksichtigen automatisch die in deinem Mandanten eingestellte Zeitzone, damit die Datumsfilter immer zu deiner Ansicht im System passen.
</Tip>

## Betragsfilter – Betragsbereiche filtern

Betragsfelder (z.B. **Bruttobetrag**, **Unbezahlt**, **Netto**, **Gebühren**, **Kontostand**) kannst du nach Bereichen filtern:

* **Größer als**
* **Größer gleich**
* **Kleiner als**
* **Kleiner gleich**
* **Zwischen zwei Beträgen**

<Note>
  Bei Geldbeträgen rechnet die Tabelle im Hintergrund mit der kleinsten Einheit (z.B. Cent), damit Filter und Sortierung exakt und stabil funktionieren.
</Note>

## Beispiele

### Beispiel 1: Offene Rechnungen eines Kunden im Juli

Du möchtest alle **offenen Rechnungen** eines bestimmten Kunden sehen, deren **Fälligkeitsdatum im Juli** liegt.

Im visuellen Builder:

<Steps>
  <Step title="Filter hinzufügen">
    * Feld: **Status** → Wert: `Unbezahlt`
    * Feld: **Kunde** → gewünschter Kunde (Kundenfilter)
    * Feld: **Fällig am** → Operator: `Zwischen` → vom `01.07.2025` bis `31.07.2025`
  </Step>

  <Step title="Filter anwenden">
    Klicke auf **Anwenden**, um die Liste zu aktualisieren.
  </Step>
</Steps>

### Beispiel 2: Abonnements ohne PO‑Nummer

Alle Abos, bei denen noch **keine PO‑Nummer** gepflegt ist:

<Steps>
  <Step title="Filter öffnen">
    Gehe zu **Abonnements → Abonnements** und klicke auf **Filter**.
  </Step>

  <Step title="Regel anlegen">
    * Feld: **PO-Nummer**
    * Operator: `Ist leer`
  </Step>
</Steps>

### Beispiel 3: Zahlungen mit bestimmtem Text in der Beschreibung

Du möchtest alle **Zahlungen** finden, in deren **Beschreibung** das Wort „chargeback“ vorkommt:

<Steps>
  <Step title="Filter öffnen">
    Gehe zu **Abrechnung → Zahlungen** und öffne den Filter.
  </Step>

  <Step title="Regel anlegen">
    * Feld: **Beschreibung**
    * Operator: `Enthält`
    * Wert: `chargeback`
  </Step>
</Steps>

## Ansichten (Presets) speichern

Komplexere Filterkombinationen kannst du als **Ansicht** speichern:

1. Filter konfigurieren und anwenden.
2. Im Filter‑Popover **„Als Ansicht speichern“** wählen.
3. Einen Namen vergeben (z.B. „Offene Rechnungen Q3 DE“).

Diese Ansicht steht dir dann als Tab über der Tabelle zur Verfügung und kann jederzeit wieder aktiviert, umbenannt oder aktualisiert werden.

<Tip>
  Views enthalten:

  * aktive Filter,
  * sichtbare Spalten und deren Reihenfolge,
  * sowie die aktuelle Sortierung.
</Tip>


# Kundenguthaben
Source: https://docs.fynn.eu/guide/invoices/wallet-balance

Verstehe, wie das Kundenguthaben funktioniert, automatisch bei Überzahlungen entsteht und auf offene Rechnungen angerechnet wird

Das **Kundenguthaben** (auch Wallet Balance genannt) ist ein separates Guthabenkonto, das vorausbezahlte Kredite deiner Kunden verwaltet. Dieses Guthaben kann automatisch auf zukünftige Rechnungen angewendet werden und reduziert den zu zahlenden Betrag.

## Was ist das Kundenguthaben?

Das Kundenguthaben funktioniert wie ein "Guthabenkonto" für deine Kunden. Wenn ein Kunde Guthaben hat, bedeutet das:

* **Aus Geschäftssicht**: Der Kunde hat vorausbezahltes Guthaben, das er nutzen kann
* **Aus buchhalterischer Sicht**: Du schuldest dem Kunden Geld (negativer Debitoren-Saldo)

Das Guthaben wird automatisch auf neue Rechnungen angewendet, sodass der Kunde weniger bezahlen muss.

## Wie entsteht Kundenguthaben?

Kundenguthaben kann auf verschiedene Weise entstehen:

### Automatische Überzahlungserkennung

Wenn ein Kunde eine Rechnung überbezahlt, erkennt Fynn die Differenz automatisch und bucht den überschüssigen Betrag als Guthaben auf das Kundenkonto. Der offene Betrag der Rechnung wird dabei automatisch auf null gesetzt.

```
Beispiel:
- Rechnung: 100,00 €
- Eingehende Zahlung: 130,00 €
- Ergebnis: Rechnung ist bezahlt, 30,00 € werden als Guthaben gutgeschrieben
```

Dieses Verhalten muss in den Einstellungen aktiviert werden (siehe [Einstellungen konfigurieren](#einstellungen-konfigurieren)).

<Note>
  Geht nach einer Überzahlung eine weitere Zahlung auf dieselbe Rechnung ein, wird nur der neue Überschuss zusätzlich gutgeschrieben. Fynn verhindert, dass bereits verrechnete Beträge doppelt übertragen werden.
</Note>

### Gutschrift für zukünftige Rechnungen

Wenn du eine Gutschrift erstellst und die Aktion "Gutschrift für zukünftige Rechnungen" wählst, wird der Betrag dem Kundenguthaben hinzugefügt. Mehr dazu unter [Korrigieren](/guide/invoices/invoice-actions).

### Manuelles Guthaben

Du kannst einem Kunden manuell Guthaben hinzufügen, z. B. als Entschädigung oder bei einer individuellen Vereinbarung.

## Automatische Anrechnung auf offene Rechnungen

Fynn kann vorhandenes Kundenguthaben automatisch auf offene Rechnungen anrechnen. Die Verrechnung erfolgt in einer festen Reihenfolge: Die älteste fällige Rechnung wird zuerst bedient, dann die nächstältere, und so weiter.

```
Beispiel:
- Kundenguthaben: 70,00 €
- Offene Rechnung A (Fälligkeit: 01.02.): 40,00 €
- Offene Rechnung B (Fälligkeit: 15.02.): 60,00 €
- Ergebnis: Rechnung A wird vollständig beglichen (40,00 €),
  30,00 € werden auf Rechnung B angerechnet (noch 30,00 € offen)
```

Die automatische Anrechnung wird nach jeder Guthabenänderung ausgelöst, etwa wenn eine Überzahlung eingeht oder manuell Guthaben hinzugefügt wird.

<Info>
  Die Sortierung der offenen Rechnungen erfolgt nach Fälligkeitsdatum, dann nach Finalisierungsdatum. Bei identischen Daten entscheidet die Rechnungs-ID als letztes Kriterium.
</Info>

### Anrechnung bei Finalisierung

Wenn eine Rechnung finalisiert wird, prüft Fynn ebenfalls, ob der Kunde Guthaben hat. Falls ja, wird das verfügbare Guthaben auf die Rechnung angewendet:

```
Beispiel:
- Neue Rechnung: 100,00 €
- Kundenguthaben: 30,00 €
- Ergebnis: Kunde muss nur noch 70,00 € bezahlen
```

<Note>
  Das Guthaben wird nur bis zur Höhe des Rechnungsbetrags angewendet. Wenn ein Kunde 50,00 € Guthaben hat, aber die Rechnung nur 30,00 € beträgt, werden nur 30,00 € verwendet. Die restlichen 20,00 € bleiben als Guthaben erhalten.
</Note>

## Einstellungen konfigurieren

Zwei Einstellungen steuern das Verhalten des Kundenguthabens. Beide können global unter **Einstellungen > Abrechnung** gesetzt und pro Kunde individuell überschrieben werden.

| Einstellung                                              | Beschreibung                                                                            | Standard    |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------- |
| **Überzahlungen als Guthaben verbuchen**                 | Überschüssige Zahlungsbeträge werden automatisch dem Kundenguthaben gutgeschrieben      | Deaktiviert |
| **Guthaben automatisch auf offene Rechnungen anrechnen** | Vorhandenes Guthaben wird automatisch auf offene Rechnungen angewendet (älteste zuerst) | Aktiviert   |

<Tabs>
  <Tab title="Global konfigurieren">
    <Steps>
      <Step title="Abrechnungseinstellungen öffnen">
        Navigiere zu **Einstellungen > Abrechnung**.
      </Step>

      <Step title="Wallet-Einstellungen anpassen">
        Aktiviere oder deaktiviere die gewünschten Optionen im Abschnitt **Kundenguthaben**.
      </Step>

      <Step title="Speichern">
        Bestätige die Änderungen mit **Speichern**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Pro Kunde konfigurieren">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zu **Kunden** und wähle den gewünschten Kunden aus.
      </Step>

      <Step title="Einstellungen Tab öffnen">
        Klicke auf den Tab **Einstellungen** in der Kundendetailansicht.
      </Step>

      <Step title="Wallet-Einstellungen anpassen">
        Passe die Einstellungen im Abschnitt **Abrechnung** an. Die Werte überschreiben die globalen Einstellungen für diesen Kunden.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  Kundenspezifische Einstellungen haben Vorrang vor den globalen Werten. Wenn du eine Einstellung für einen Kunden individuell setzt, wird der globale Wert für diesen Kunden nicht mehr berücksichtigt.
</Info>

## Guthaben bei Rechnungsstornierung

Wenn eine Rechnung storniert wird, auf die bereits Guthaben angewendet wurde, passiert Folgendes:

1. **Guthaben wird zurückgebucht**: Das verwendete Guthaben wird dem Kunden wieder gutgeschrieben
2. **Vollständige Rückabwicklung**: Die ursprüngliche Guthaben-Transaktion wird durch eine Rückbuchung ausgeglichen
3. **Nachvollziehbarkeit**: Alle Transaktionen bleiben im System erhalten und sind nachvollziehbar (GoBD-konform)

<Warning>
  Bei einer Stornierung wird das Guthaben immer zurückgebucht, da die Rechnung so behandelt wird, als hätte sie nie existiert.
</Warning>

## Guthaben bei Gutschriften

Wenn du eine Gutschrift für eine bereits bezahlte Rechnung erstellst, wird das Guthaben **nicht** automatisch zurückgebucht. Stattdessen hängt es von der gewählten Aktion ab:

| Aktion                                   | Guthaben-Impact                                                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Rückerstattung**                       | Keine Auswirkung auf Guthaben. Die Gutschrift wird als neue Verbindlichkeit behandelt und per Auszahlung beglichen. |
| **Betrag anpassen**                      | Keine Auswirkung auf Guthaben. Die Gutschrift gleicht nur den Debitoren-Saldo aus.                                  |
| **Gutschrift für zukünftige Rechnungen** | Der Gutschriftsbetrag wird dem Kundenguthaben hinzugefügt.                                                          |

<Info>
  Gutschriften sind separate Belege und keine Korrekturen der ursprünglichen Rechnung. Daher wird das ursprünglich verwendete Guthaben nicht zurückgebucht.
</Info>

## Herkunft der Zahlungsmethode

Bei Guthaben, das aus einer Überzahlung stammt, speichert Fynn die ursprüngliche Zahlungsmethode, das verwendete Gateway und die Transaktionsreferenz. Diese Informationen sind relevant, wenn das Guthaben später ausgezahlt werden soll, da Auszahlungen aus regulatorischen Gründen über den gleichen Zahlungsweg erfolgen müssen.

## Guthaben-Transaktionen

Jede Bewegung des Kundenguthabens wird als separate Transaktion dokumentiert. Dies gewährleistet:

* **Vollständige Nachvollziehbarkeit**: Jede Änderung ist dokumentiert
* **GoBD-Konformität**: Alle Transaktionen sind unveränderlich und nachvollziehbar
* **Transparenz**: Kunden können ihre Guthaben-Historie einsehen

### Transaktionstypen

| Typ                         | Beschreibung                               | Betrag  |
| --------------------------- | ------------------------------------------ | ------- |
| **Manuelles Guthaben**      | Guthaben wurde manuell hinzugefügt         | Positiv |
| **Auf Rechnung angewendet** | Guthaben wurde für eine Rechnung verwendet | Negativ |
| **Rechnung storniert**      | Rückbuchung bei Rechnungsstornierung       | Positiv |
| **Überzahlung**             | Kunde hat Rechnung überbezahlt             | Positiv |
| **Gutschrift gewährt**      | Gutschrift wurde als Guthaben gewährt      | Positiv |

## Guthaben einsehen

Du kannst das aktuelle Guthaben eines Kunden in der Kundenübersicht einsehen. Dort siehst du:

* Den aktuellen Guthabenstand
* Die Transaktionshistorie
* Verknüpfte Rechnungen und Gutschriften

<Note>
  Das Guthaben wird pro Währung separat geführt. Ein Kunde kann also beispielsweise 50,00 € in EUR und 30,00 \$ in USD als Guthaben haben.
</Note>

## Praxisbeispiele

<AccordionGroup>
  <Accordion title="Kunde zahlt per Überweisung zu viel">
    Ein Kunde überweist 500,00 € für eine Rechnung über 450,00 €. Fynn erkennt die Überzahlung von 50,00 € und bucht sie automatisch als Guthaben. Die nächste Rechnung des Kunden wird um 50,00 € reduziert, sofern die automatische Anrechnung aktiviert ist.
  </Accordion>

  <Accordion title="Mehrere offene Rechnungen nach Überzahlung">
    Ein Kunde hat 200,00 € Guthaben und drei offene Rechnungen: 80,00 € (fällig 01.03.), 150,00 € (fällig 15.03.) und 50,00 € (fällig 31.03.). Fynn verrechnet zuerst die 80,00 €-Rechnung vollständig, dann werden 120,00 € auf die 150,00 €-Rechnung angerechnet. Die dritte Rechnung bleibt unberührt, da kein Guthaben mehr verfügbar ist.
  </Accordion>

  <Accordion title="Überzahlung ist deaktiviert">
    Wenn die Einstellung "Überzahlungen als Guthaben verbuchen" deaktiviert ist, wird eine Überzahlung nicht automatisch ins Guthaben übertragen. Der überzahlte Betrag bleibt als Differenz bestehen und muss manuell verarbeitet werden.
  </Accordion>

  <Accordion title="Kundenspezifische Einstellung überschreibt global">
    Global ist die automatische Anrechnung aktiviert, aber für einen bestimmten Kunden wurde sie deaktiviert. Guthaben, das bei diesem Kunden entsteht, wird nicht automatisch auf seine offenen Rechnungen angerechnet. Es bleibt stattdessen im Wallet stehen, bis du es manuell zuweist oder der Kunde eine neue Rechnung erhält, auf die es bei Finalisierung angewendet wird.
  </Accordion>
</AccordionGroup>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ein Kunde negatives Guthaben haben?">
    Nein. Das System verhindert, dass das Guthaben negativ wird. Wenn Guthaben auf eine Rechnung angewendet wird, wird nur so viel verwendet, wie verfügbar ist.
  </Accordion>

  <Accordion title="Was passiert, wenn eine Rechnung mit Guthaben storniert wird?">
    Das verwendete Guthaben wird automatisch zurückgebucht. Der Kunde erhält sein Guthaben zurück.
  </Accordion>

  <Accordion title="Kann ich Guthaben manuell entfernen?">
    Ja, du kannst Guthaben manuell anpassen. Dies sollte jedoch nur in Ausnahmefällen erfolgen und wird im Verlaufsprotokoll dokumentiert.
  </Accordion>

  <Accordion title="Wie unterscheidet sich Guthaben vom Debitoren-Saldo?">
    Der **Debitoren-Saldo** zeigt die gesamte Forderungsposition (Rechnungen minus Zahlungen minus Gutschriften). Das **Kundenguthaben** zeigt nur das verfügbare Guthaben, das auf zukünftige Rechnungen angewendet werden kann. Wenn ein Kunde Guthaben hat, sollte der Debitoren-Saldo negativ sein, und dieser Betrag sollte dem Guthaben entsprechen.
  </Accordion>

  <Accordion title="Werden Überzahlungen bei mehrfachen Zahlungseingängen doppelt verbucht?">
    Nein. Fynn vergleicht bei jeder Zahlung den bereits übertragenen Betrag mit dem aktuellen Überschuss und bucht nur die Differenz. So wird sichergestellt, dass keine doppelten Gutschriften entstehen.
  </Accordion>

  <Accordion title="Warum wird meine Überzahlung nicht als Guthaben verbucht?">
    Prüfe, ob die Einstellung "Überzahlungen als Guthaben verbuchen" aktiviert ist. Diese findest du unter **Einstellungen > Abrechnung** oder in den individuellen Kundeneinstellungen. Standardmäßig ist sie deaktiviert.
  </Accordion>
</AccordionGroup>


# Guthaben auszahlen
Source: https://docs.fynn.eu/guide/invoices/wallet-payout

Zahle Kundenguthaben per SEPA-Überweisung auf das Bankkonto des Kunden aus, mit Herkunftsprüfung und automatischer Rückbuchung bei Fehlern

Mit einer **Guthaben-Auszahlung** überweist du das Kundenguthaben zurück auf das Bankkonto des Kunden. Fynn erstellt dafür eine SEPA-Überweisung. Das Guthaben wird beim Anstoßen der Auszahlung sofort abgezogen und erst dann endgültig verbucht, wenn die Bank die Überweisung ausgeführt hat.

Wie die Überweisung zur Bank gelangt, hängt vom eingestellten Einreichungs-Modus ab: im **manuellen Modus** (Standard) lädst du die SEPA-Datei selbst herunter und reichst sie bei deiner Bank ein, im **automatischen Modus** wird sie über EBICS eingereicht. Den Modus stellst du in den SEPA-Lastschrift-Einstellungen ein.

## Wann eine Auszahlung sinnvoll ist

Kundenguthaben entsteht zum Beispiel durch Überzahlungen oder eine [Aufladung](/guide/invoices/wallet-top-up). Normalerweise wird es automatisch auf die nächsten Rechnungen angerechnet (siehe [Kundenguthaben](/guide/invoices/wallet-balance)). Möchte der Kunde sein Guthaben stattdessen zurückerhalten, zahlst du es aus.

<Info>
  Eine Auszahlung ist keine Gutschrift und keine Rechnungskorrektur. Sie bewegt nur bestehendes Guthaben zurück auf das Bankkonto des Kunden. Für die Erstattung einer bezahlten Rechnung nutzt du die Rechnungsaktion **Rückerstattung** (siehe [Rechnungsaktionen](/guide/invoices/invoice-actions)).
</Info>

## Voraussetzungen

Damit du Guthaben per Überweisung auszahlen kannst, müssen diese Dinge eingerichtet sein:

| Voraussetzung                 | Beschreibung                                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SEPA-XML-Einstellungen**    | Das Absender-Bankkonto (IBAN, BIC und Kontoinhaber) ist unter den SEPA-Lastschrift-Einstellungen hinterlegt. Von diesem Konto wird die Überweisung ausgeführt. Diese Angaben sind in beiden Modi nötig. |
| **Bankverbindung des Kunden** | Für den Kunden ist eine Bankverbindung hinterlegt (SEPA-Mandat oder Zahlungsmethode per Überweisung). Alternativ gibst du die Empfänger-IBAN direkt beim Anstoßen der Auszahlung an.                    |
| **EBICS-Anbindung**           | Nur für den automatischen Modus: Deine Organisation ist über EBICS mit der Bank verbunden, über die die Überweisung eingereicht wird. Im manuellen Modus ist EBICS nicht erforderlich.                  |

<Warning>
  Fehlt eine erforderliche Voraussetzung, wird die Auszahlung nicht angestoßen und das Guthaben bleibt unverändert. Fynn gibt in diesem Fall eine klare Fehlermeldung aus, statt eine Buchung anzulegen, die später fehlschlägt.
</Warning>

## Woher das Guthaben stammt entscheidet über den Weg

Aus regulatorischen Gründen (Geldwäsche-Prävention) darf Guthaben nur über den Weg zurückfließen, über den es hereingekommen ist. Eine Bankauszahlung ist deshalb nur erlaubt, wenn das Guthaben ursprünglich per Banküberweisung oder SEPA-Lastschrift entstanden ist.

Fynn merkt sich für jede Guthaben-Gutschrift, aus welcher Zahlung sie stammt, und prüft das bei jeder Auszahlung.

| Herkunft des Guthabens        | Bankauszahlung möglich? | Richtiger Weg                                                       |
| ----------------------------- | ----------------------- | ------------------------------------------------------------------- |
| Banküberweisung               | Ja                      | Auszahlung per SEPA-Überweisung                                     |
| SEPA-Lastschrift              | Ja                      | Auszahlung per SEPA-Überweisung                                     |
| Kartenzahlung (Stripe, Unzer) | Nein                    | Erstattung über den ursprünglichen Zahlungsweg zurück auf die Karte |
| PayPal                        | Nein                    | Erstattung über PayPal                                              |
| GoCardless                    | Nein                    | Erstattung über GoCardless                                          |
| Unbekannte Herkunft           | Nein                    | Manuelle Prüfung nötig, dann Erstattung über den ursprünglichen Weg |

<Note>
  Setzt sich das Guthaben aus mehreren Zahlungen zusammen, ist eine Bankauszahlung nur möglich, wenn **jeder** verrechnete Anteil aus einer erlaubten Herkunft stammt. Ein einziger gesperrter Anteil verhindert die gesamte Auszahlung. So bleibt jeder Cent eindeutig einem Zufluss zugeordnet.
</Note>

Wird eine Auszahlung wegen der Herkunft abgelehnt, wird nichts gebucht und das Guthaben bleibt vollständig erhalten. Du erstattest den Betrag dann über den ursprünglichen Zahlungsweg oder triffst nach einer manuellen Prüfung eine dokumentierte Entscheidung.

## Ablauf und Status

Jede Auszahlung durchläuft feste Schritte. Solange sie nicht abgeschlossen ist, kannst du den aktuellen Stand am Status ablesen.

| Status             | Bedeutung                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Offen**          | Die Auszahlung ist angelegt und das Guthaben ist bereits vom Konto des Kunden abgezogen. Sie wartet auf die Einreichung bei der Bank. |
| **Eingereicht**    | Die SEPA-Überweisung wurde bei der Bank eingereicht und wird von ihr verarbeitet.                                                     |
| **Ausgeführt**     | Die Bank hat die Überweisung ausgeführt und über den Kontoumsatz bestätigt. Die Auszahlung ist abgeschlossen.                         |
| **Fehlgeschlagen** | Die Einreichung ist fehlgeschlagen. Das Guthaben wurde automatisch wieder gutgeschrieben.                                             |

### Manueller Modus (Standard)

<Steps>
  <Step title="Auszahlung anstoßen">
    Du gibst den Betrag an und optional eine abweichende Empfänger-Bankverbindung. Ohne Angabe verwendet Fynn die hinterlegte Bankverbindung des Kunden. Fynn prüft das verfügbare Guthaben und die Herkunft, zieht den Betrag sofort vom Guthaben ab und legt die Auszahlung mit Status **Offen** an.
  </Step>

  <Step title="SEPA-Datei erstellen und herunterladen">
    Auf der Seite **Auszahlungen** erstellst du mit einem Klick die SEPA-Datei für alle offenen Auszahlungen und lädst sie herunter.
  </Step>

  <Step title="Bei der Bank einreichen">
    Du reichst die heruntergeladene SEPA-Datei über das Online-Banking deiner Bank ein.
  </Step>

  <Step title="Upload bestätigen">
    Auf der Seite **SEPA-Exporte** markierst du die Datei als hochgeladen. Die enthaltenen Auszahlungen wechseln damit auf **Eingereicht**.
  </Step>

  <Step title="Ausführung bestätigen">
    Sobald der Kontoumsatz die Überweisung bestätigt, wechselt die Auszahlung auf **Ausgeführt**.
  </Step>
</Steps>

### Automatischer Modus

Ist der automatische Modus in den SEPA-Lastschrift-Einstellungen aktiviert, übernimmt Fynn die Einreichung selbst.

<Steps>
  <Step title="Auszahlung anstoßen">
    Wie im manuellen Modus: Betrag und optional eine abweichende Bankverbindung. Der Betrag wird sofort vom Guthaben abgezogen.
  </Step>

  <Step title="Überweisung einreichen">
    Fynn erstellt die SEPA-Überweisung und reicht sie über EBICS bei deiner Bank ein. Die Auszahlung wechselt auf **Eingereicht**.
  </Step>

  <Step title="Ausführung bestätigen">
    Sobald der Kontoumsatz die Überweisung bestätigt, wechselt die Auszahlung auf **Ausgeführt**.
  </Step>
</Steps>

## Was bei einem Fehler passiert

Im automatischen Modus bucht Fynn den abgezogenen Betrag automatisch wieder zurück, falls die Einreichung über EBICS fehlschlägt. Das Guthaben entspricht danach genau dem Stand vor der Auszahlung. Die Auszahlung erhält den Status **Fehlgeschlagen** und einen Grund.

Im manuellen Modus bleibt eine Auszahlung so lange **Offen**, bis du den Upload auf der Seite SEPA-Exporte bestätigst. Solange du die Datei nicht als hochgeladen markierst, ist noch nichts endgültig, und das abgezogene Guthaben ist weiterhin dieser offenen Auszahlung zugeordnet.

<Check>
  Es wird nie ein Betrag ohne Deckung ausgezahlt: Entweder die Überweisung ist eingereicht (Status **Eingereicht**), die Auszahlung wartet noch als **Offen** auf die Einreichung, oder das Guthaben ist vollständig zurückgebucht (Status **Fehlgeschlagen**).
</Check>

## Nachvollziehbarkeit

Jede Auszahlung dokumentiert, aus welchen Zuflüssen sie stammt, welche Empfänger-Bankverbindung verwendet wurde und über welche Referenz sie im Kontoumsatz wiederzufinden ist. Damit lässt sich für jeden ausgezahlten Betrag lückenlos belegen, woher das Guthaben kam und wohin es geflossen ist.

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich auf eine andere IBAN als die des Kunden auszahlen?">
    Ja. Du kannst beim Anstoßen der Auszahlung eine abweichende Empfänger-IBAN angeben. Sie wird auf der Auszahlung dokumentiert. Ohne Angabe verwendet Fynn die hinterlegte Bankverbindung des Kunden.
  </Accordion>

  <Accordion title="Warum wird meine Auszahlung wegen der Herkunft abgelehnt?">
    Das Guthaben stammt ganz oder teilweise aus einer Zahlung, die nicht per Überweisung zurückfließen darf, zum Beispiel aus einer Kartenzahlung oder über PayPal. Erstatte den Betrag in diesem Fall über den ursprünglichen Zahlungsweg.
  </Accordion>

  <Accordion title="Ist das Guthaben nach einem Fehlschlag verloren?">
    Nein. Schlägt die Einreichung fehl, wird der abgezogene Betrag automatisch wieder gutgeschrieben. Das Guthaben entspricht danach wieder dem Stand vor der Auszahlung.
  </Accordion>

  <Accordion title="Was passiert, wenn nicht genug Guthaben vorhanden ist?">
    Die Auszahlung wird abgelehnt und es wird nichts gebucht. Das Guthaben kann durch eine Auszahlung nie negativ werden.
  </Accordion>

  <Accordion title="Kann ich mehr als das aktuelle Guthaben auszahlen?">
    Nein. Es lässt sich höchstens der aktuell verfügbare Guthabenstand in der jeweiligen Währung auszahlen.
  </Accordion>
</AccordionGroup>

## Verwandte Themen

<Columns>
  <Card title="Kundenguthaben" icon="wallet" href="/guide/invoices/wallet-balance">
    Wie Guthaben entsteht und automatisch auf Rechnungen angerechnet wird.
  </Card>

  <Card title="Wallet aufladen" icon="plus" href="/guide/invoices/wallet-top-up">
    Guthaben manuell oder automatisch per Zahlungseinzug auffüllen.
  </Card>
</Columns>


# Wallet aufladen
Source: https://docs.fynn.eu/guide/invoices/wallet-top-up

Lade das Kundenguthaben manuell oder automatisch auf, um Rechnungen vorab zu bezahlen

Mit der **Wallet-Aufladung** können Kunden ihr Guthaben gezielt auffüllen — entweder manuell über die Web-App oder automatisch per Regel, wenn das Guthaben unter einen bestimmten Schwellenwert fällt.

## Manuelle Aufladung

Eine manuelle Aufladung startet einen Zahlungsvorgang, der den gewünschten Betrag vom Kunden einzieht und als Guthaben verbucht.

<Tabs>
  <Tab title="Web-App">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zu **Kunden** und wähle den gewünschten Kunden aus.
      </Step>

      <Step title="Debitorenkonto-Tab öffnen">
        Klicke auf den Tab **Debitorenkonto** in der Kundendetailansicht.
      </Step>

      <Step title="Aufladen klicken">
        Klicke auf den Button **Aufladen** in der Wallet-Guthaben-Karte.
      </Step>

      <Step title="Betrag eingeben">
        Gib den gewünschten Aufladebetrag ein. Optional kannst du eine bestimmte Zahlungsmethode auswählen — andernfalls wird die Standard-Zahlungsmethode des Kunden verwendet.
      </Step>

      <Step title="Aufladung bestätigen">
        Klicke auf **Aufladen**. Fynn erstellt einen Zahlungsvorgang (PaymentIntent), der den Betrag einzieht.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://coreapi.io/api/wallet/top-up \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "customerId": "CUSTOMER_ID",
        "amount": 100.00,
        "currencyCode": "EUR"
      }'
    ```

    Siehe [API-Dokumentation](/api-reference/guides/wallet-top-up) für alle Parameter und Optionen.
  </Tab>
</Tabs>

### Status einer Aufladung

Jede Aufladung durchläuft einen Zahlungsstatus:

| Status             | Beschreibung                                           | Badge |
| ------------------ | ------------------------------------------------------ | ----- |
| **Ausstehend**     | Zahlung wurde gestartet, aber noch nicht abgeschlossen | Gelb  |
| **Abgeschlossen**  | Zahlung war erfolgreich, Guthaben wurde gutgeschrieben | Grün  |
| **Fehlgeschlagen** | Zahlung konnte nicht eingezogen werden                 | Rot   |

<Note>
  Nach einer erfolgreichen Aufladung wird das Guthaben sofort verfügbar und kann automatisch auf offene Rechnungen angerechnet werden, sofern die [automatische Anrechnung](/guide/invoices/wallet-balance#automatische-anrechnung-auf-offene-rechnungen) aktiviert ist.
</Note>

### Aufladungshistorie

Im Debitorenkonto-Tab findest du die Karte **Aufladungen** mit einer Übersicht aller bisherigen Aufladungen — inklusive angefordertem Betrag, gutgeschriebenem Betrag und Status.

## Automatische Aufladung

Mit automatischen Aufladungsregeln lässt sich das Guthaben eines Kunden automatisch auffüllen, wenn es unter einen definierten Schwellenwert fällt.

### Regel erstellen

<Steps>
  <Step title="Debitorenkonto öffnen">
    Navigiere zum Tab **Debitorenkonto** des gewünschten Kunden.
  </Step>

  <Step title="Regel hinzufügen">
    Klicke in der Karte **Automatische Aufladung** auf **Regel hinzufügen**.
  </Step>

  <Step title="Parameter konfigurieren">
    Konfiguriere die Regel:

    | Parameter           | Beschreibung                                                                          |
    | ------------------- | ------------------------------------------------------------------------------------- |
    | **Währung**         | Die Währung, für die die Regel gilt (z.B. EUR)                                        |
    | **Schwellenwert**   | Wenn das Guthaben unter diesen Betrag fällt, wird aufgeladen                          |
    | **Aufladebetrag**   | Der Betrag, der automatisch aufgeladen wird                                           |
    | **Zahlungsmethode** | Optional: Spezifische Zahlungsmethode (Standard: Standard-Zahlungsmethode des Kunden) |
  </Step>

  <Step title="Regel speichern">
    Klicke auf **Erstellen**. Die Regel ist sofort aktiv.
  </Step>
</Steps>

<Info>
  Pro Kunde und Währung kann jeweils nur eine automatische Aufladungsregel existieren.
</Info>

### Wie funktioniert die automatische Aufladung?

1. **Trigger**: Bei jeder Guthaben-Abbuchung (z.B. Anrechnung auf eine Rechnung) prüft Fynn, ob das Guthaben unter den Schwellenwert gefallen ist
2. **Aufladung starten**: Falls ja, wird automatisch eine Aufladung über den konfigurierten Betrag gestartet
3. **Zahlung einziehen**: Der Betrag wird über die konfigurierte (oder Standard-) Zahlungsmethode eingezogen
4. **Guthaben gutschreiben**: Nach erfolgreicher Zahlung wird das Guthaben aufgeladen

```
Beispiel:
- Schwellenwert: 10,00 €
- Aufladebetrag: 100,00 €
- Aktuelles Guthaben: 50,00 €
- Neue Rechnung: 45,00 € (Guthaben wird angerechnet)
- Guthaben danach: 5,00 € → unter Schwellenwert!
- Automatische Aufladung: 100,00 € wird eingezogen
- Guthaben nach Aufladung: 105,00 €
```

### Regeln verwalten

In der Karte **Automatische Aufladung** kannst du bestehende Regeln:

* **Aktivieren/Deaktivieren**: Regel vorübergehend ein- oder ausschalten
* **Bearbeiten**: Schwellenwert, Betrag oder Zahlungsmethode ändern
* **Löschen**: Regel dauerhaft entfernen

### Sicherheitsmechanismen

Fynn schützt vor ungewollten Mehrfach-Aufladungen:

* **Aufladung durch Aufladung wird nicht getriggert**: Eine Guthaben-Aufladung (Top-Up) löst keine erneute Schwellenwert-Prüfung aus
* **Fehlerzähler**: Nach aufeinanderfolgenden fehlgeschlagenen Aufladungen wird eine Warnung angezeigt. So erkennst du frühzeitig, wenn eine Zahlungsmethode nicht mehr funktioniert
* **Feature-Flag**: Die Wallet-Aufladung muss für deinen Account aktiviert sein

<Warning>
  Wenn die Zahlungsmethode eines Kunden nicht mehr gültig ist (z.B. abgelaufene Kreditkarte), schlägt die automatische Aufladung fehl. Prüfe regelmäßig Regeln mit Fehlerwarnungen.
</Warning>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich das Guthaben auch ohne Aufladung manuell erhöhen?">
    Ja. Neben der Aufladung per Zahlungseinzug kannst du auch manuell Guthaben hinzufügen — z.B. über eine Gutschrift oder manuelle Buchung. Die Aufladung unterscheidet sich dadurch, dass sie automatisch eine Zahlung vom Kunden einzieht.
  </Accordion>

  <Accordion title="Was passiert, wenn die Zahlung fehlschlägt?">
    Die Aufladung wird als **Fehlgeschlagen** markiert. Das Guthaben bleibt unverändert. Bei automatischen Aufladungen wird der Fehlerzähler erhöht, und bei der nächsten Guthaben-Abbuchung wird erneut versucht aufzuladen.
  </Accordion>

  <Accordion title="Kann ich mehrere Regeln für verschiedene Währungen haben?">
    Ja. Du kannst pro Währung eine automatische Aufladungsregel erstellen. So lassen sich z.B. EUR- und USD-Guthaben mit unterschiedlichen Schwellenwerten verwalten.
  </Accordion>

  <Accordion title="Werden automatische Aufladungen sofort verarbeitet?">
    Die Aufladung wird sofort ausgelöst, sobald das Guthaben unter den Schwellenwert fällt. Die tatsächliche Gutschrift erfolgt, sobald die Zahlung erfolgreich eingezogen wurde.
  </Accordion>

  <Accordion title="Kann ich die automatische Aufladung vorübergehend deaktivieren?">
    Ja. Du kannst eine Regel deaktivieren, ohne sie zu löschen. Die Regel bleibt gespeichert und kann jederzeit wieder aktiviert werden.
  </Accordion>
</AccordionGroup>


# Listen und Tabellen
Source: https://docs.fynn.eu/guide/list-views

So arbeitest du mit Listenansichten in Fynn – filtern, sortieren und anpassen.

Auf dieser Seite erfährst du, wie du:

* Filter verwendest, um Einträge schnell einzugrenzen
* Spalten ein- und ausblendest
* Sortierungen anpasst
* Ansichten speicherst und wiederverwendest

## Filter verwenden

Mit den Tabellenfiltern kannst du große Listen schnell eingrenzen.

1. Öffne die gewünschte Liste.
2. Klicke oben rechts in der Tabellenleiste auf **Filter**.
3. Im Popover kannst du:
   * im **visuellen Modus** Filterregeln zusammenklicken
   * oder über die **Textsuche** eine einfache Suchzeile eingeben (optional).

[Ausführliche Beispiele zu Filtern findest du hier](/guide/invoices/list-filters).

## Spalten anpassen

Du kannst in vielen Listen selbst bestimmen, welche Spalten angezeigt werden.

1. Öffne die gewünschte Liste.
2. Klicke in der Tabellenleiste auf **Spalten** (oder das Spalten‑Symbol).
3. Wähle aus, welche Spalten sichtbar sein sollen.
4. Ziehe Spalten in der Tabelle per Drag & Drop an die gewünschte Position (sofern verfügbar).

Deine Einstellungen werden in der Regel pro Benutzer gespeichert, sodass du mit deiner bevorzugten Ansicht weiterarbeiten kannst.

## Sortierung anpassen

Um die Sortierung zu ändern:

1. Klicke auf die Spaltenüberschrift, nach der du sortieren möchtest (z.B. **Erstellt am**, **Fällig am**, **Betrag**).
2. Ein erneuter Klick kehrt die Sortierreihenfolge (aufsteigend/absteigend) um.

In manchen Listen kannst du zusätzlich eine Standardsortierung pro gespeicherter Ansicht festlegen.

## Ansichten speichern

Komplexere Kombinationen aus:

* Filtern,
* sichtbaren Spalten,
* deren Reihenfolge,
* und Sortierung

kannst du als **Ansicht** speichern.

1. Stelle die Liste so ein, wie du sie benötigst.
2. Öffne das Menü für Ansichten (z.B. oben über der Tabelle).
3. Wähle **„Als Ansicht speichern“**.
4. Vergib einen Namen (z.B. „Offene Rechnungen Q3 DE“).

Die gespeicherte Ansicht steht dir anschließend als Tab oder Eintrag in der Auswahlliste zur Verfügung und kann jederzeit wieder ausgewählt, umbenannt oder aktualisiert werden.


# Eigene E-Mail-Domain
Source: https://docs.fynn.eu/guide/notifications/custom-email-domain

Richte deine eigene Domain als E-Mail-Absender ein, um E-Mails direkt über deine Unternehmens-Domain zu versenden.

## Voraussetzungen

<Note>
  Um E-Mails über deine eigene Domain zu versenden, muss die Domain zunächst vom Fynn-Team eingerichtet werden. Schreibe uns eine kurze E-Mail an [hi@fynn.eu](mailto:hi@fynn.eu) mit der gewünschten Domain.
</Note>

Nachdem das Fynn-Team deine Domain eingerichtet hat, musst du zwei Schritte durchführen:

1. **Domain-Verifizierung** - Bestätige, dass du der Inhaber der Domain bist
2. **DNS-Konfiguration** - Richte SPF, DKIM und optionale Einträge ein, um eine zuverlässige Zustellung sicherzustellen

***

## Schritt 1: Domain verifizieren

Um zu bestätigen, dass du Inhaber der Domain bist, muss ein TXT-Record in deinen DNS-Einstellungen hinterlegt werden.

<Steps>
  <Step title="Verifizierungsdaten erhalten">
    Nachdem das Fynn-Team deine Domain angelegt hat, erhältst du einen Verifizierungscode. Dieser sieht beispielsweise so aus:

    | Typ | Name              | Wert                                         |
    | --- | ----------------- | -------------------------------------------- |
    | TXT | `@` (Root-Domain) | `postal-verification deinVerifizierungsCode` |
  </Step>

  <Step title="TXT-Record anlegen">
    Melde dich bei deinem DNS-Provider an (z.B. Cloudflare, IONOS, Hetzner, AWS Route 53) und erstelle einen neuen **TXT-Record** mit den erhaltenen Daten.
  </Step>

  <Step title="Verifizierung abschliessen">
    Klicke in der Verwaltungsoberfläche auf **"Verify TXT record"**, um die Verifizierung zu starten. Der DNS-Eintrag wird geprüft und die Domain bestätigt.

    <Tip>
      DNS-Änderungen können bis zu 24 Stunden dauern, bis sie weltweit verfügbar sind. In der Regel ist der Eintrag jedoch innerhalb weniger Minuten sichtbar.
    </Tip>
  </Step>
</Steps>

***

## Schritt 2: DNS-Konfiguration

Nach erfolgreicher Verifizierung müssen weitere DNS-Einträge konfiguriert werden, um eine zuverlässige E-Mail-Zustellung sicherzustellen.

### SPF-Record (erforderlich)

Der SPF-Record legt fest, welche Server E-Mails im Namen deiner Domain versenden dürfen.

Erstelle einen **TXT-Record** auf der Root-Domain (`@`) mit folgendem Inhalt:

```
v=spf1 a mx include:spf.pes.netzfabrik.eu ~all
```

<Warning>
  Falls du bereits einen SPF-Record hast (z.B. für einen anderen E-Mail-Dienst), füge lediglich `include:spf.pes.netzfabrik.eu` zu deinem bestehenden Record hinzu. Es darf pro Domain nur **einen** SPF-Record geben.

  **Beispiel:** Dein bestehender Record `v=spf1 include:_spf.google.com ~all` wird zu:

  ```
  v=spf1 include:_spf.google.com include:spf.pes.netzfabrik.eu ~all
  ```
</Warning>

### DKIM-Record (erforderlich)

DKIM signiert ausgehende E-Mails kryptografisch und stellt sicher, dass sie nicht manipuliert wurden.

Erstelle einen **TXT-Record** mit dem Namen und Inhalt, die du vom Fynn-Team erhältst. Der Eintrag sieht beispielsweise so aus:

| Typ | Name                      | Wert                                       |
| --- | ------------------------- | ------------------------------------------ |
| TXT | `postal-XXXXX._domainkey` | `v=DKIM1; t=s; h=sha256; p=MIGfMA0GCSq...` |

<Tip>
  Der genaue Name und Wert des DKIM-Records wird individuell für deine Domain generiert und in der Verwaltungsoberfläche angezeigt.
</Tip>

### Return Path (empfohlen)

Der Return Path verbessert die Zustellbarkeit und hilft bei der DMARC-Ausrichtung.

Erstelle einen **CNAME-Record**:

| Typ   | Name   | Wert                   |
| ----- | ------ | ---------------------- |
| CNAME | `psrp` | `rp.pes.netzfabrik.eu` |

### MX-Records (optional)

MX-Records sind nur erforderlich, wenn du auch **eingehende** E-Mails über Fynn empfangen möchtest. Für den reinen Versand von Benachrichtigungen sind sie nicht notwendig.

Falls gewünscht, erstelle einen **MX-Record** mit Priorität 10:

| Typ | Priorität | Wert                   |
| --- | --------- | ---------------------- |
| MX  | 10        | `mx.pes.netzfabrik.eu` |

***

## DNS-Einträge prüfen

Nachdem du alle DNS-Einträge konfiguriert hast, kannst du in der Verwaltungsoberfläche über **"Check my records are correct"** prüfen, ob alle Einträge korrekt gesetzt sind. Für jeden Eintrag wird der aktuelle Status angezeigt.

<Snippet />


# Übersicht-E-Mails (Digest)
Source: https://docs.fynn.eu/guide/notifications/digest-emails

Erhalte regelmäßige Zusammenfassungen mit den wichtigsten Kennzahlen und Aufgaben deiner Organisation.

## Übersicht

Übersicht-E-Mails (Digest) fassen die wichtigsten Kennzahlen und offenen Aufgaben deiner Organisation in einer einzigen E-Mail zusammen. Du erhältst damit einen kompakten Überblick, ohne dich in die Plattform einloggen zu müssen.

Jeder Benutzer kann individuell festlegen, welche Informationen er erhalten möchte und in welchem Rhythmus die E-Mails versendet werden.

## Benutzerkontobereich

Die Einstellungen für Übersicht-E-Mails befinden sich im persönlichen Benutzerkontobereich. Dort kannst du dein Profil verwalten und deine Benachrichtigungseinstellungen konfigurieren.

### Benachrichtigungen konfigurieren

<Steps>
  <Step title="Benutzerkontobereich öffnen">
    Klicke auf deinen Avatar oder Namen in der oberen Navigation und wähle **Mein Profil**.
  </Step>

  <Step title="Benachrichtigungen auswählen">
    Wähle den Tab **Benachrichtigungen** in der linken Seitennavigation.

    <Frame>
      <img alt="Benachrichtigungseinstellungen im Benutzerkontobereich" />
    </Frame>
  </Step>

  <Step title="Übersicht-E-Mails aktivieren">
    Aktiviere den Hauptschalter **Übersicht-E-Mails**, um regelmäßige Zusammenfassungen zu erhalten. Wenn der Schalter deaktiviert ist, werden keine Digest-E-Mails versendet.
  </Step>

  <Step title="Abschnitte konfigurieren">
    Wähle für jeden verfügbaren Abschnitt die gewünschte Frequenz:

    * **Täglich** — Du erhältst den Abschnitt in täglichen E-Mails (Montag bis Freitag)
    * **Wöchentlich** — Du erhältst den Abschnitt einmal pro Woche
    * **Deaktiviert** — Der Abschnitt wird nicht in deine E-Mails aufgenommen
  </Step>
</Steps>

<Info>
  Welche Abschnitte dir zur Verfügung stehen, hängt von deinen Berechtigungen ab. Du siehst nur Abschnitte, für die deine Benutzerrolle die erforderlichen Rechte hat. Ändert sich deine Rolle, werden die verfügbaren Abschnitte automatisch angepasst.
</Info>

## Verfügbare Abschnitte

Die Abschnitte sind in Kategorien gruppiert. Jeder Abschnitt kann einzeln aktiviert oder deaktiviert werden.

### Kunden & Umsatz

<CardGroup>
  <Card title="Neue Kunden" icon="user-plus">
    Verfolge das Kundenwachstum und erkenne Trends in der Neukundengewinnung. Zeigt die Anzahl neuer Kunden im gewählten Zeitraum.
  </Card>

  <Card title="Umsatzübersicht" icon="chart-line">
    Erhalte einen Überblick über die Umsatzentwicklung und Veränderungen zum Vorperioden-Vergleich.
  </Card>
</CardGroup>

### Rechnungen & Zahlungen

<CardGroup>
  <Card title="Rechnungen zur Freigabe" icon="file-invoice">
    Erhalte eine Übersicht über Rechnungen, die noch auf Prüfung und Freigabe warten.
  </Card>

  <Card title="Offene SEPA-Exporte" icon="building-columns">
    Behalte ausstehende Lastschrift-Exporte im Blick, damit keine Zahlungseingänge verzögert werden.
  </Card>

  <Card title="Nicht zugeordnete Zahlungen" icon="money-bill-transfer">
    Behalte eingehende Zahlungen im Blick, die noch manuell einer Rechnung zugeordnet werden müssen.
  </Card>
</CardGroup>

<Note>
  Die Benachrichtigung über ausstehende SEPA-XML-Exporte wird jetzt über die Übersicht-E-Mails gesteuert und kann individuell pro Benutzer konfiguriert werden. Bisher wurde diese Information systemseitig versendet.
</Note>

### Buchhaltung

<CardGroup>
  <Card title="Monatsabschluss verfügbar" icon="calendar-check">
    Werde informiert, sobald ein Monat für den Monatsabschluss bereit ist.
  </Card>
</CardGroup>

### Betrieb

<CardGroup>
  <Card title="Fehlgeschlagene E-Mails" icon="envelope-circle-xmark">
    Erkenne Zustellprobleme frühzeitig und verhindere, dass wichtige Kommunikation verloren geht.
  </Card>

  <Card title="Xentral-Bestellungen" icon="boxes-stacked">
    Erhalte einen Überblick über alle Xentral-Bestellungen und deren Status.
  </Card>

  <Card title="Fehlgeschlagene Xentral-Bestellungen" icon="triangle-exclamation">
    Werde über fehlgeschlagene Xentral-Bestellungen informiert, die deine Aufmerksamkeit erfordern.
  </Card>
</CardGroup>

<Info>
  Die Xentral-Abschnitte sind nur sichtbar, wenn die Xentral-Integration für deinen Mandanten aktiviert ist.
</Info>

## Frequenz & Zustellung

### Tägliche E-Mails

* Versand an jedem Werktag (Montag bis Freitag)
* Enthält die Daten der letzten 24 Stunden
* Vergleich mit dem Vortag

### Wöchentliche E-Mails

* Versand immer montags
* Enthält die Daten der letzten 7 Tage
* Vergleich mit der Vorwoche

<Tip>
  Wenn du sowohl tägliche als auch wöchentliche Abschnitte aktiviert hast, erhältst du am Montag eine kombinierte E-Mail mit allen Abschnitten — statt zwei separater E-Mails.
</Tip>

### Leere Zeiträume

Wenn in einem Zeitraum keine relevanten Daten vorliegen (z.B. keine neuen Kunden, keine offenen Rechnungen), wird keine E-Mail versendet. Du erhältst nur dann eine E-Mail, wenn mindestens ein aktivierter Abschnitt Daten enthält.

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Warum sehe ich bestimmte Abschnitte nicht?">
    Die verfügbaren Abschnitte richten sich nach deinen Benutzerberechtigungen. Du siehst nur Abschnitte, für die deine Rolle die erforderlichen Rechte hat. Wende dich an einen Administrator, wenn du Zugriff auf weitere Abschnitte benötigst.
  </Accordion>

  <Accordion title="Kann ich den Versandzeitpunkt ändern?">
    Der Versandzeitpunkt wird systemseitig festgelegt. Wöchentliche E-Mails werden immer montags versendet.
  </Accordion>

  <Accordion title="Was passiert, wenn sich meine Berechtigungen ändern?">
    Änderungen an deiner Benutzerrolle wirken sich automatisch auf die verfügbaren Abschnitte aus. Wird ein Recht entzogen, wird der zugehörige Abschnitt ab der nächsten E-Mail nicht mehr angezeigt. Neue Rechte werden ebenfalls automatisch berücksichtigt.
  </Accordion>

  <Accordion title="Warum erhalte ich keine E-Mail?">
    E-Mails werden nur versendet, wenn mindestens ein aktivierter Abschnitt Daten enthält. Prüfe, ob der Hauptschalter aktiviert ist und ob mindestens ein Abschnitt auf „Täglich" oder „Wöchentlich" steht.
  </Accordion>

  <Accordion title="Was ist mit der SEPA-Export-Benachrichtigung passiert?">
    Die Benachrichtigung über ausstehende SEPA-XML-Exporte ist jetzt Teil der Übersicht-E-Mails. Du kannst sie im Benutzerkontobereich unter „Benachrichtigungen" individuell konfigurieren.
  </Accordion>
</AccordionGroup>


# Benachrichtigungen
Source: https://docs.fynn.eu/guide/notifications/introduction

Konfiguriere Benachrichtigungen und E-Mails.

<Frame>
  <img alt="Einstellungen der Benachrichtungen" />
</Frame>

Fynn bietet eine Reihe von Benachrichtigungen, die du anpassen kannst, um über wichtige Ereignisse in deiner Organisation informiert zu werden. Diese Benachrichtigungen können per E-Mail oder über andere Kanäle gesendet werden.

## Mehrsprachige E-Mail-Benachrichtigungen

<Info>
  E-Mail-Benachrichtigungen sind in **Deutsch und Englisch** verfügbar. Die Sprache wird automatisch anhand des Kundenprofils bestimmt.
</Info>

Fynn unterstützt mehrsprachige E-Mail-Vorlagen. Jede Benachrichtigung kann eine separate deutsche und englische Vorlage haben, die unabhängig voneinander bearbeitet und versioniert werden.

**So funktioniert es:**

* Kunden erhalten E-Mails automatisch in der Sprache, die in ihrem Profil hinterlegt ist (Feld "Sprache")
* Im Vorlagen-Editor kannst du über **Sprachreiter** zwischen der deutschen und englischen Version wechseln
* Mit der integrierten **KI-Übersetzung** kannst du die deutsche Vorlage per Klick ins Englische übersetzen lassen
* Die generierte Übersetzung kann vor dem Speichern überprüft und angepasst werden
* Auch der **globale E-Mail-Header und Footer** können pro Sprache konfiguriert werden
* Systemtexte (z.B. "Geschäftsführer", "E-Mail im Browser öffnen") werden automatisch in der Kundensprache dargestellt

<Tip>
  Ist für eine Benachrichtigung keine englische Vorlage konfiguriert, wird automatisch die deutsche Version verwendet. Du kannst englische Vorlagen also schrittweise hinzufügen.
</Tip>

## Benachrichtigungen konfigurieren

Um Benachrichtigungen zu konfigurieren, gehe zu den [Einstellungen > Benachrichtigungen](https://app.fynn.eu/settings/notifications). Hier kannst du die verschiedenen verfügbaren Benachrichtigungen einsehen und anpassen.

Für jede Benachrichtigung kannst du festlegen, ob sie aktiviert ist und welche Vorlage verwendet wird.

<Tabs>
  <Tab title="E-Mail Benachrichtigungen">
    ### Benachrichtigungen anpassen

    <Frame>
      <img alt="Einstellungen der Benachrichtungen" />
    </Frame>

    Die E-Mail Vorlagen sind im MJML Format verfasst, welches eine einfache Möglichkeit bietet, responsive E-Mails zu erstellen. Du kannst die Vorlagen anpassen, um den Stil und Inhalt der E-Mails zu ändern, die an deine Nutzer gesendet werden.

    Die Vorlagen enthalten Platzhalter, die automatisch durch die entsprechenden Informationen ersetzt werden, wenn die E-Mail gesendet wird. Diese Platzhalter sind in geschweifte Klammern eingeschlossen, z.B. `{{ invoice.number }}` für den die Rechnungsnummer.

    Eine genaue Liste der verfügbaren Platzhalter steht aktuell nicht zur Verfügung, aber du kannst die Vorlagen direkt in der Fynn App anpassen und testen.

    ### Variablen in E-Mail-Vorlagen

    ## Eigener E-Mail-Absender

    Du kannst E-Mails über deine eigene Domain versenden. Eine ausführliche Anleitung zur Einrichtung findest du unter [Eigene E-Mail-Domain](/guide/notifications/custom-email-domain).
  </Tab>

  <Tab title="SMS Benachrichtigungen">
    <Warning>
      Der SMS-Versand ist ein kostenpflichtiges Feature, jede SMS (160 Zeichen) kostet 0,10 EUR (zzgl. MwSt.).
    </Warning>

    ### Benachrichtigungen anpassen

    <Frame>
      <img alt="Einstellungen der Benachrichtungen für SMS" />
    </Frame>

    Das SMS Format ist ein einfacher Text, der an die Nutzer gesendet wird. Du kannst die Vorlagen anpassen, um den Stil und Inhalt der SMS zu ändern, die an deine Nutzer gesendet werden.

    Mit dem Klick auf "Einstellungen speichern" wird das SMS-Template bzw. Änderungen gespeichert.
  </Tab>

  <Tab title="Briefversand">
    <Warning>
      Um diese Funktion zu nutzen, muss sie von unserem Team aktiviert werden. Schreibe uns eine kurze E-Mail mit dem Wunsch an [hi@fynn.eu](mailto:hi@fynn.eu)
    </Warning>

    Fynn bietet die Möglichkeit, Benachrichtigungen per Brief zu versenden. Diese Funktion ist besonders nützlich für wichtige Mitteilungen, die nicht elektronisch zugestellt werden können oder sollen.

    Briefe bis 14 Uhr werden noch am selben Tag gedruckt und versendet. Briefe, die nach 14 Uhr erstellt werden, werden am nächsten Werktag gedruckt und versendet.
  </Tab>
</Tabs>

## Zusätzliche Rechnungs-Empfänger

<Warning>
  Um diese Funktion zu nutzen, muss sie von unserem Team aktiviert werden. Schreibe uns eine kurze E-Mail mit dem Wunsch an [hi@fynn.eu](mailto:hi@fynn.eu)
</Warning>

<Frame>
  <img alt="Zusätzliche Rechnungs-Empfänger" />
</Frame>

Die Funktion "Zusätzliche Rechnungs-Empfänger" ermöglicht es dir, Rechnungen bspw. direkt per E-Mail Upload an dein Buchhaltungssystem zu senden. Als Absender wird die E-Mail-Adresse verwendet, die in den Einstellungen der Organisation hinterlegt ist. Diese muss ggf. in deiner Buchhaltungssoftware vorab freigeschaltet werden.

Der Kunde erhält weiterhin eine separate E-Mail mit der Rechnung. Die zusätzlichen Empfänger erhalten die Rechnung ebenfalls, aber ohne den Hinweis, dass es sich um eine Kopie handelt.


# Postversand (Briefe)
Source: https://docs.fynn.eu/guide/notifications/postversand

Versende Rechnungen als physischen Brief, mit automatischem Fallback von E-Mail auf Brief und voller Nachverfolgung des Zustellstatus.

## Übersicht

Mit dem Postversand versendest du Rechnungen, Stornos und Gutschriften als
physischen Brief. Fynn übergibt das fertige Dokument an einen Druckdienstleister,
der es druckt, kuvertiert und verschickt. Den Versand- und Zustellstatus siehst
du direkt an der Rechnung und in einer eigenen Übersicht.

Der Brief nutzt dieselbe PDF wie der E-Mail-Versand. Die Empfängeradresse wird
aus dem Adressfenster des Dokuments gelesen, du musst also keine Adresse separat
pflegen. Sobald der Postversand für deine Organisation aktiv ist, blendet Fynn
die Absenderzeile im Adressfenster automatisch aus, damit die Empfängeradresse
sauber erkannt wird.

<Note>
  Der Postversand wird für deine Organisation freigeschaltet. Wende dich an uns,
  wenn du ihn nutzen möchtest.
</Note>

## Rechnung als Brief versenden

Eine finalisierte Rechnung versendest du über die API auf dem Kanal `letter`:

```bash theme={null}
curl -X POST https://coreapi.io/api/invoices/{id}/send \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "letter",
    "options": {
      "isColor": true,
      "isDuplex": false,
      "isInternational": false
    }
  }'
```

Mit `channel: "email"` versendest du dieselbe Rechnung stattdessen per E-Mail.

### Druckoptionen

Die Optionen werden an den Druckdienstleister durchgereicht:

| Option            | Bedeutung                  | Standard |
| ----------------- | -------------------------- | -------- |
| `isColor`         | Farbdruck statt Graustufen | `true`   |
| `isDuplex`        | Beidseitiger Druck         | `false`  |
| `isInternational` | Internationaler Versand    | `false`  |

Die Antwort enthält den Kanal, den aktuellen Status und, sofern verfügbar, die
Sendungsnummer:

```json theme={null}
{
  "channel": "letter",
  "status": "submitted",
  "letterId": "…",
  "trackingNumber": "…"
}
```

## Automatischer Fallback von E-Mail auf Brief

Ist ein Kunde per E-Mail nicht erreichbar, kann Fynn die Rechnung automatisch als
Brief versenden. Der Fallback greift, wenn die letzte Rechnungs-E-Mail an den
Kunden als unzustellbar zurückgekommen ist (Bounce) oder keine nutzbare
E-Mail-Adresse hinterlegt ist, und wenn die Rechnung eine gültige Postadresse
trägt.

Der automatische Fallback ist konfigurierbar und wird zusätzlich zum Postversand
freigeschaltet. So behältst du die Kontrolle darüber, ob nicht zustellbare
E-Mails auf Papier ausweichen sollen.

## Zustellstatus nachverfolgen

Jeder Brief durchläuft die folgenden Status:

| Status          | Bedeutung                                                 |
| --------------- | --------------------------------------------------------- |
| `submitted`     | Vom Druckdienstleister angenommen und eingeplant          |
| `dispatched`    | Gedruckt und der Post übergeben                           |
| `delivered`     | Zustellung bestätigt (nur bei nachverfolgbaren Produkten) |
| `undeliverable` | Nicht zustellbar (falsche oder unbekannte Adresse)        |
| `failed`        | Vom Druckdienstleister abgelehnt                          |
| `cancelled`     | Vor dem Versand storniert                                 |

In der **Rechnungsdetailansicht** siehst du zu jeder Rechnung den aktuellen
Briefstatus, die Sendungsnummer und das Versand- sowie Zustelldatum.

Unter **Einstellungen → Versendete Briefe** findest du alle versendeten Briefe
deiner Organisation, filterbar nach Status, Datum und Kunde.

### Fehlgeschlagene Zustellung

Kommt ein Brief nicht an (`undeliverable` oder `failed`), legt Fynn automatisch
eine Aufgabe an, die dir den betroffenen Kunden und die Rechnung anzeigt. So
siehst du direkt, wo Handlungsbedarf besteht, und kannst die Adresse prüfen und
den Versand erneut anstoßen.

## Webhooks

Für die Anbindung eigener Systeme stehen zwei Ereignisse bereit:

* `invoice.letter.dispatched` wird ausgelöst, sobald der Brief an den
  Druckdienstleister übergeben wurde.
* `invoice.letter.delivered` wird ausgelöst, sobald die Zustellung bestätigt ist.

Beide Ereignisse enthalten die Rechnung sowie die Briefdaten mit Status und
Sendungsnummer. Mehr zur Einrichtung von Webhooks findest du in der
[Webhooks-Übersicht](/guide/webhooks/introduction).


# E-Mail Vorlagen Variablen
Source: https://docs.fynn.eu/guide/notifications/template-variables

Alle verfügbaren Variablen für E-Mail Benachrichtigungen

<Note>
  Alle Variablen werden automatisch formatiert. Daten werden entsprechend der Sprache des Empfängers formatiert (Deutsch: `31.12.2024`, Englisch: `12/31/2024`). Geldbeträge werden ebenfalls automatisch formatiert.
</Note>

## Übersicht

Alle Variablen sind bereits formatiert und müssen nicht zusätzlich formatiert werden.

**Wichtig**:

* Alle Daten und Datum/Zeit-Werte werden automatisch formatiert
* Alle Geldbeträge sind bereits formatiert mit Währungssymbolen

## Variablen-Kategorien

### Kundeninformationen

Verfügbar in allen Benachrichtigungen:

* `customer.firstName` - Vorname des Kunden (Text)
* `customer.lastName` - Nachname des Kunden (Text)
* `customer.companyName` - Firmenname, falls vorhanden (Text, optional)
* `customer.customerNumber` - Kundennummer (Text)
* `customer.language` - Sprache des Kunden (Text)
* `customer.locale` - Locale-Code des Kunden (Text)
* `customer.contactPerson.firstName` - Vorname der Kontaktperson (Text, optional)
* `customer.contactPerson.lastName` - Nachname der Kontaktperson (Text, optional)
* `customer.contactPerson.email` - E-Mail der Kontaktperson (Text, optional)

### Organisationsinformationen

Verfügbar in allen Benachrichtigungen:

* `tenant.name` - Name der Organisation (Text)
* `tenant.legalCompanyName` - Rechtlicher Firmenname (Text)
* `tenant.street` - Straße (Text)
* `tenant.housenumber` - Hausnummer (Text)
* `tenant.zip` - Postleitzahl (Text)
* `tenant.city` - Stadt (Text)
* `tenant.email` - E-Mail-Adresse (Text)
* `tenant.phone` - Telefonnummer (Text, optional)
* `tenant.ceo` - Geschäftsführer (Text)
* `tenant.commercialRegisterNumber` - Handelsregisternummer (Text)
* `tenant.commercialRegister` - Handelsregister (Text)

### Rechnungsinformationen

Verfügbar in rechnungsbezogenen Benachrichtigungen:

* `invoice.number` - Rechnungsnummer (Text)
* `invoice.grossAmount` - Gesamtbetrag inklusive Steuern (formatiert)
* `invoice.netAmount` - Nettobetrag ohne Steuern (formatiert)
* `invoice.taxAmount` - Steuerbetrag (formatiert)
* `invoice.dueDate` - Fälligkeitsdatum (formatiert: `d.m.Y` für Deutsch, `m/d/Y` für Englisch)
* `invoice.finalizationDate` - Datum der Rechnungsstellung (formatiert, optional)
* `invoice.payDate` - Zahlungsdatum (formatiert, optional)
* `invoice.documentDate` - Dokumentdatum (formatiert)
* `invoice.customerNumber` - Kundennummer (Text)
* `invoice.referencedInvoiceNumber` - Referenz-Rechnungsnummer (Text, optional)
* `invoice.referencedInvoiceDate` - Referenz-Rechnungsdatum (formatiert, optional)
* `invoice.referencedInvoiceDueDate` - Referenz-Fälligkeitsdatum (formatiert, optional)
* `invoice.referencedInvoiceTotalGrossAmount` - Referenz-Rechnungsbetrag (formatiert, optional)
* `invoice.dueDateInDays` - Tage bis Fälligkeit (Zahl, optional)
* `invoice.dunningLevel` - Mahnstufe (Zahl, optional)
* `invoice.paymentMethod.type` - Zahlungsmethoden-Typ (Text, optional)
* `invoice.paymentMethod.displayName` - Vorfomatieter Anzeigename der Zahlungsmethode (Text, optional)
* `invoice.paymentMethod.card.lastFour` - Letzte vier Ziffern der Karte (Text, optional, nur bei Karten)
* `invoice.paymentMethod.card.expirationDate` - Ablaufdatum der Karte formatiert als "MM/YYYY" (Text, optional, nur bei Karten)

### Transaktionsinformationen

Verfügbar in transaktionsbezogenen Benachrichtigungen:

* `transaction.amount` - Transaktionsbetrag (formatiert)
* `transaction.refundAmount` - Rückerstattungsbetrag (formatiert, optional)
* `transaction.chargedAmount` - Belasteter Betrag (formatiert, optional)
* `transaction.description` - Transaktionsbeschreibung (Text)
* `transaction.documentNumber` - Dokumentreferenznummer (Text)
* `transaction.paidAt` - Datum und Uhrzeit der Zahlung (formatiert: `d.m.Y H:i` für Deutsch, `m/d/Y h:i A` für Englisch, optional)
* `transaction.failedAt` - Datum und Uhrzeit des Fehlschlags (formatiert, optional)
* `transaction.failReason` - Fehlergrund (Text, optional)
* `transaction.offsiteReason` - Grund für Offsite-Autorisierung (Text, optional)
* `transaction.paymentMethod.type` - Zahlungsmethoden-Typ (Text, optional)
* `transaction.paymentMethod.displayName` - Vorfomatieter Anzeigename der Zahlungsmethode (Text, optional)
* `transaction.paymentMethod.card.lastFour` - Letzte vier Ziffern der Karte (Text, optional, nur bei Karten)
* `transaction.paymentMethod.card.expirationDate` - Ablaufdatum der Karte formatiert als "MM/YYYY" (Text, optional, nur bei Karten)

### Zahlungsmethoden-Informationen

Verfügbar in zahlungsmethodenbezogenen Benachrichtigungen:

* `paymentMethod.type` - Zahlungsmethoden-Typ (Text)
* `paymentMethod.displayName` - Vorfomatieter Anzeigename der Zahlungsmethode (Text)
* `paymentMethod.card.lastFour` - Letzte vier Ziffern der Karte (Text, optional, nur bei Karten)
* `paymentMethod.card.expirationDate` - Ablaufdatum der Karte formatiert als "MM/YYYY" (Text, optional, nur bei Karten)

### Abonnement-Informationen

Verfügbar in abonnementbezogenen Benachrichtigungen:

* `subscription.number` - Abonnementnummer (Text)
* `subscription.name` - Abonnementname (Text)
* `subscription.poNumber` - Bestellnummer (Text, optional)
* `subscription.trialEndsOn` - Datum des Testzeitraum-Endes (formatiert, optional)
* `subscription.customFields.<key>` - Wert eines benutzerdefinierten Feldes (Text, optional)

### Preisänderungs-Items

Verfügbar in Preisänderungs-Benachrichtigungen (Array):

* `updateItems[].subscriptionId` - Abonnement-ID (Text)
* `updateItems[].subscriptionNumber` - Abonnementnummer (Text)
* `updateItems[].subscriptionName` - Abonnementname (Text)
* `updateItems[].contractStart` - Vertragsstartdatum und -zeit (formatiert)
* `updateItems[].applyOn` - Datum und Zeit der Anwendung (formatiert)
* `updateItems[].billingInterval` - Abrechnungsintervall (z.B. "monatlich", "jährlich") (Text)
* `updateItems[].oldPrice` - Vorheriger Preis (formatiert)
* `updateItems[].newPrice` - Neuer Preis (formatiert)

## Verwendungsbeispiele

### Einfacher Variablenzugriff

```
Hallo {{ customer.firstName }} {{ customer.lastName }},

Ihre Rechnung {{ invoice.number }} über {{ invoice.totalGrossAmount }} ist fällig.
```

### Verschachtelte Eigenschaften

```
Zahlungsmethode: {{ invoice.paymentMethod.displayName }}

{% if invoice.paymentMethod.card %}
Kartennummer: ****{{ invoice.paymentMethod.card.lastFour }}
Ablaufdatum: {{ invoice.paymentMethod.card.expirationDate }}
{% endif %}
```

### Datumsformatierung

Daten werden automatisch basierend auf der Sprache formatiert:

* Deutsch (`de`): `d.m.Y` (z.B. `31.12.2024`)
* Englisch (`en`): `m/d/Y` (z.B. `12/31/2024`)

Datum/Zeit werden formatiert als:

* Deutsch (`de`): `d.m.Y H:i` (z.B. `31.12.2024 14:30`)
* Englisch (`en`): `m/d/Y h:i A` (z.B. `12/31/2024 02:30 PM`)

```
Fälligkeitsdatum: {{ invoice.dueDate }}
Bezahlt am: {{ transaction.paidAt }}
```

### Array-Iteration

```
{% for item in updateItems %}
Abonnement: {{ item.subscriptionName }} ({{ item.subscriptionNumber }})
Alter Preis: {{ item.oldPrice }} / {{ item.billingInterval }}
Neuer Preis: {{ item.newPrice }} / {{ item.billingInterval }}
Gültig ab: {{ item.applyOn }}
{% endfor %}
```

### Bedingter Zugriff

```
{% if invoice.paymentMethod %}
Zahlungsmethode: {{ invoice.paymentMethod.displayName }}
{% endif %}

{% if transaction.failReason %}
Fehlergrund: {{ transaction.failReason }}
{% endif %}
```

## API-Zugriff

Du kannst alle verfügbaren Variablen programmatisch über die API abrufen:

```
GET /ui/notification-template-variables?notificationType=invoice.finalized
```

Dies gibt eine JSON-Antwort mit allen Variablen zurück, gruppiert nach Kategorien, einschließlich Beschriftungen, Typen und Beschreibungen.


# Oauth2 Flow
Source: https://docs.fynn.eu/guide/oauth2/introduction



OAuth 2.0 ist ein offenes Standardprotokoll zur sicheren Autorisierung von Anwendungen, ohne dass Benutzer ihre Zugangsdaten direkt weitergeben müssen. Stattdessen erhält eine Anwendung Zugriff auf eine API, indem sie Tokens verwendet.

| Type                            | URL                                                                                                                |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorize Endpoint (Production) | [https://oauth2.coreapi.io/oauth2/auth](https://oauth2.coreapi.io/oauth2/auth)                                     |
| Token Endpoint (Production)     | [https://oauth2.coreapi.io/oauth2/token](https://oauth2.coreapi.io/oauth2/token)                                   |
| JWK Keys (Production)           | [https://oauth2.coreapi.io/.well-known/jwks.json](https://oauth2.coreapi.io/.well-known/jwks.json)                 |
| Authorize Endpoint (Preview)    | [https://oauth2.preview.coreapi.io/oauth2/auth](https://oauth2.preview.coreapi.io/oauth2/auth)                     |
| Token Endpoint (Preview)        | [https://oauth2.preview.coreapi.io/oauth2/token](https://oauth2.preview.coreapi.io/oauth2/token)                   |
| JWK Keys (Preview)              | [https://oauth2.preview.coreapi.io/.well-known/jwks.json](https://oauth2.preview.coreapi.io/.well-known/jwks.json) |

<Check>
  Um Zugriff auf Oauth2 Clients zu erhalten, erstelle ein Support-Ticket.
</Check>

<Info>
  Redirect URLs müssen https verwenden. Hierbei ist [http://localhost](http://localhost) und [http://127.0.0.1](http://127.0.0.1) die Ausnahme.
</Info>

## Grundkonzepte von OAuth 2.0

* Authorization Server: Verifiziert die Identität des Benutzers und gibt Access Tokens aus.
* Resource Server: Der Server, der die geschützten Ressourcen bereitstellt (z. B. eine API).
* Client: Die Anwendung, die auf die API zugreifen möchte.
* Resource Owner: Der Benutzer, der entscheidet, ob eine Anwendung Zugriff auf seine Ressourcen erhält.
* Access Token: Ein temporäres Token, das für den Zugriff auf die API verwendet wird.
* Refresh Token (optional): Ein langfristiges Token, das zur Erneuerung eines Access Tokens genutzt wird.

## Grant Types

Je nach Anwendungsszenario gibt es unterschiedliche Grant Types, die festlegen, wie ein Client ein Access Token erhält.
Folgende Grant Types sind durch Fynn unterstützt:

### Authorization Code Flow (mit oder ohne PKCE)

Der Authorization Code Flow ist ein OAuth2-Prozess, der für Webanwendungen entwickelt wurde, um Benutzer sicher zu authentifizieren und Zugriff auf geschützte Ressourcen zu gewähren. Dieser Flow wird besonders für serverseitige Anwendungen empfohlen, da die sensiblen Zugangsdaten nicht direkt im Frontend gespeichert werden.

* Einsatzbereich: Webanwendungen & mobile Apps
* Sicherheit: Sehr hoch (Tokens werden nur im Backend verwaltet)

Ablauf des Authorization Code Flow

1. Weiterleitung zur Autorisierungsanfrage:
   Die Anwendung leitet den Benutzer auf die Anmeldeseite des Autorisierungsservers weiter. Hier gibt die Anwendung an, welche Berechtigungen (Scopes) sie benötigt.
2. Benutzerauthentifizierung und Zustimmung:
   Der Benutzer meldet sich beim Autorisierungsserver an und wird gefragt, ob er der Anwendung den gewünschten Zugriff gewähren möchte.
3. Erhalt des Autorisierungscodes:
   Nach erfolgreicher Authentifizierung wird der Benutzer zurück zur Anwendung geleitet. Dabei wird ein einmaliger Autorisierungscode übergeben.
4. Austausch des Codes gegen ein Zugriffstoken:
   Die Anwendung sendet den erhaltenen Code zusammen mit einem geheimen Schlüssel an den Autorisierungsserver. Falls die Anfrage gültig ist, stellt der Server ein Access Token aus.
5. Zugriff auf geschützte Ressourcen:
   Mit dem erhaltenen Access Token kann die Anwendung nun auf geschützte APIs zugreifen und im Namen des Benutzers Daten abrufen oder Aktionen durchführen.

#### Proof Key for Code Exchange (PKCE)

PKCE (Proof Key for Code Exchange) ist eine Erweiterung des Authorization Code Flow, die speziell für öffentliche Clients wie Single-Page- und Mobile-Apps entwickelt wurde. Es verhindert, dass der Autorisierungscode durch Angriffe (z. B. Code Interception) missbraucht wird.

Funktionsweise von PKCE:

* Der Client generiert einen zufälligen Code Verifier (eine lange, zufällige Zeichenkette).
* Daraus wird eine Code Challenge abgeleitet (eine transformierte Version des Verifiers, meist als SHA-256 Hash).
* Beim Austausch des Autorisierungscodes gegen ein Access Token muss der Client den ursprünglichen Code Verifier mit senden.
* Der Server überprüft die Challenge und stellt das Access Token nur aus, wenn die Werte übereinstimmen.

Da kein geheimer Schlüssel gespeichert werden muss, ist PKCE besonders für Clients ohne sichere Speicherung (z. B. Browser-Anwendungen) wichtig.

#### Erweiterungen des Authorization Code Flow

1. Refresh Token für langfristigen Zugriff:
   Damit sich ein Benutzer nicht ständig neu authentifizieren muss, kann zusätzlich ein Refresh Token angefordert werden. Dies ermöglicht es der Anwendung, ohne erneute Benutzereingabe neue Access Tokens zu erhalten. Hierfür ist der Scope `offline` notwendig.
2. ID Token für Benutzerinformationen (OpenID Connect):
   Falls die Anwendung auch Informationen über den angemeldeten Benutzer benötigt, kann ein ID Token angefordert werden. Dieses wird als JWT (JSON Web Token) ausgestellt und enthält beispielsweise die Benutzer-ID, E-Mail-Adresse oder weitere Identitätsattribute. Hierfür ist der Scope `openid` notwendig.
3. Scopes zur Steuerung der Berechtigungen:
   Der Autorisierungsprozess kann durch verschiedene Scopes gesteuert werden. Diese definieren, welche Daten oder Funktionen der Benutzer der Anwendung freigibt.

#### Beispiel

Szenario: Eine Webanwendung möchte den Benutzer authentifizieren und erhält Zugriff auf eine geschützte API.

1. Benutzer wird zur Autorisierung weitergeleitet

Die Anwendung leitet den Benutzer zum Autorisierungsserver weiter:

```
GET https://oauth2.coreapi.io/oauth2/auth
    ?response_type=code
    &client_id=client123
    &redirect_uri=https://my-app.com/callback
    &scope=openid offline entitlements.read
    &state=randomString
```

2. Benutzer meldet sich an
   Der Benutzer wird zum Login-Formular von Fynn weitergeleitet. Nach der Anmeldung fragt Fynn, ob die Anwendung Zugriff erhalten darf.

Wenn der Benutzer zustimmt, gibt der Server einen Autorisierungscode zurück:

```
GET https://my-app.com/callback?code=AUTH_CODE&state=randomString
```

3. Anwendung tauscht den Code gegen ein Access Token
   Die Anwendung sendet nun eine POST-Anfrage an den Autorisierungsserver:

```
POST https://oauth2.coreapi.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=client123
&client_secret=superSecret
&grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://my-app.com/callback
```

Der Server gibt ein Access Token, Refresh Token und JWT Token (OpenID), je nach angegebenen Scopes, zurück:

```
{
    "access_token": "...",
    "expires_in": 3600,
    "refresh_token": "...",
    "id_token": "...",
    "scope": "...",
    "token_type": "Bearer"
}
```

### Refresh Token

Wenn das Access Token abläuft, kann die Anwendung ein neues Token mit einem Refresh Token anfordern:

```
POST https://oauth2.coreapi.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=client123
&client_secret=superSecret
&grant_type=refresh_token
&refresh_token=abcd1234
&scope=offline openid entitlements.read
```

Der Server gibt ein Access Token, Refresh Token und JWT Token (OpenID), je nach angegebenen Scopes, zurück:

```
{
    "access_token": "...",
    "expires_in": 3600,
    "refresh_token": "...",
    "id_token": "...",
    "scope": "...",
    "token_type": "Bearer"
}
```

<Info>
  Wenn ein Client ein Refresh Token verwendet, um ein neues Access Token zu erhalten, wird auch einen neuer ID Token ausgestellt, sofern der ursprüngliche Token-Austausch bereits einen ID Token enthalten hat.
  Der neue ID Token hat eine aktualisierte Ablaufzeit, behält jedoch den gleichen auth\_time-Wert (den Zeitpunkt der ursprünglichen Authentifizierung des Benutzers) bei.
  Das auth\_time-Claim im ID Token dient dazu, festzustellen, ob die Authentifizierungssitzung des Benutzers noch aktiv ist.
</Info>

## Scopes

Scopes definieren, welche Berechtigungen eine Anwendung innerhalb eines Zugriffs erhält. Sie begrenzen den Zugriff auf spezifische APIs und Funktionen.
Folgende Scopes werden aktuell unterstützt:

| Scope             | Bedeutung                                                 |
| ----------------- | --------------------------------------------------------- |
| openid            | Zugriff auf die OpenID-Identität des Benutzers (bei OIDC) |
| offline           | Ermöglicht das Anfordern von Refresh Tokens               |
| entitlements.read | Erlaubt das Abrufen des Entitlements Endpunkt             |

Scopes werden sowohl bei der Autorisierungsanfrage als auch bei der [Anlage des Oauth2 Clients](#) angegeben.

## OpenID Connect

OpenID Connect erweitert die Authentifizierungsfunktionen von OAuth, indem es Komponenten wie ein ID-Token einführt, das als JSON Web Token (JWT) ausgegeben wird.

OpenID Connect ermöglicht eine standardisierte Authentifizierung, indem es auf OAuth 2.0 aufbaut und sicherstellt, dass Anwendungen die Identität eines Benutzers vertrauenswürdig verifizieren können.

Um OpenID Connect zu verwenden, muss der Scope `openid` hinzugefügt werden. Anschließend wird beim Abruf der Tokens ebenfalls ein ID Token zurückgegeben.

### ID Token

Das ID-Token ist konzeptionell mit einem Personalausweis vergleichbar, da es eine Reihe von JSON-Claims über den Benutzer enthält, wie zum Beispiel:

* sub (Subject) – Eindeutige Kennung des Benutzers
* name – Vollständiger Name des Benutzers
* email – E-Mail-Adresse des Benutzers
* iat (Issued At) – Zeitpunkt, zu dem das Token ausgestellt wurde
* exp (Expiration) – Ablaufzeit des Tokens
* iss (Issuer) – Identitätsanbieter (IdP), der das Token ausgestellt hat
* aud (Audience) – Die Zielanwendung, für die das Token bestimmt ist

```JWT Decoded ID Token theme={null}
{
  iss: "https://oauth2.coreapi.io",
  sub: "some-identity-id",
  aud: "some-client-id",
  exp: 1311281970,
  iat: 1311280970,
  nonce: "KxSty13b2L",
  name: "Jane Doe",
  given_name: "Jane",
  family_name: "Doe",
  email: "jane@example.org",
  email_verified: true,
}
```

### Validierung ID Token (JWK)

Der ID Token kann mit Hilfe der JWK Keys validiert werden. Der notwendige Endpunkt hierfür lautet: `https://oauth2.coreapi.io/.well-known/jwks.json`, `https://oauth2.preview.coreapi.io/.well-known/jwks.json`.

<Warning>
  ID Tokens dürfen nicht für API-Zugriffe verwendet werden.
</Warning>

### OpenID Connect Logout

Folgende Flows werden aktuell unterstützt:

| Feature                | Front-Channel                                       | Back-Channel                                                  |
| ---------------------- | --------------------------------------------------- | ------------------------------------------------------------- |
| Logout-Mechanismus     | Benutzer wird per Browser weitergeleitet            | Server-zu-Server-Anfrage                                      |
| Client-Session beenden | Durch Cookie- oder Session-Invalidierung im Browser | Direkt auf dem Server (z. B. Token-Revokation)                |
| Browser benötigt?      | Ja                                                  | Nein                                                          |
| Geeignet für           | Web-Apps mit Session-basiertem Login                | Sicherheitssensitive Anwendungen ohne Client-Side-Interaktion |

#### OpenID Connect Front-Channel Logout 1.0

Hierfür benötigen wir eine `Logout URI`. Teile uns diese bitte mit.

Funktionsweise:

* Wenn sich ein Benutzer abmeldet, leitet Fynn den User-Agent (Browser) an die registrierte `Logout URI` weiter.
* Die OAuth2-Client-Anwendung kann den Benutzer dann auch in deinem eigenen System abmelden, z. B. durch:
  * Löschen eines Authentifizierungs-Cookies
  * Invalidieren der Benutzersitzung

#### OpenID Connect Back-Channel Logout 1.0

Hierfür benötigen wir eine \`Logout URI\`\`. Teile uns diese bitte mit.

Beim Abmelden eines Benutzers wird eine HTTP-POST-Anfrage mit dem Content-Type application/x-www-form-urlencoded und einem `logout_token` an die konfigurierte URL gesendet.

Das logout\_token ist ein JWT, das mit demselben Schlüssel signiert ist, der auch für die Signierung von OpenID Connect ID-Tokens verwendet wird.
Daher sollte das logout\_token mithilfe des öffentlichen Schlüssels für ID-Tokens validiert werden, welcher über `/.well-known/jwks.json` abgerufen werden kann.

Das logout\_token enthält die folgenden Claims:

* iss (Issuer) – Identifikator des ausstellenden OpenID-Providers: `https://oauth2.coreapi.io` oder `https://oauth2.preview.coreapi.io`
* aud (Audience) – Die Client-ID des OAuth2-Clients, für den dieses Logout-Token bestimmt ist.
* iat (Issued At) – Zeitpunkt, zu dem das Token ausgestellt wurde. Kann verwendet werden, um das Alter des Tokens zu bestimmen.
* jti (JWT ID) – Eindeutige Kennung des JWTs, um Replay-Angriffe zu verhindern. Das Token sollte nur einmal verwendet werden.
* events – Enthält den Eintrag [http://schemas.openid.net/event/backchannel-logout](http://schemas.openid.net/event/backchannel-logout). Dies deklariert, dass das JWT ein Logout-Token ist. Der entsprechende Wert MUSS ein JSON-Objekt sein und SOLLTE  sein (leeres JSON-Objekt).
* sid (Session ID) – Eine Sitzungs-ID, die eine bestimmte Sitzung mit einem ID-Token verknüpft. Diese wird beim Logout-Aufruf als Parameter übergeben.


# Angebote
Source: https://docs.fynn.eu/guide/offers/introduction

Erstelle und verwalte deine Angebote.

## Angebote unterzeichnen

### Angebot gegenzeichnen

Aktiviere den Gegenzeichner in den [Einstellungen](https://app.fynn.eu/settings/offer), um automatisch
einen internen Signierer hinzuzufügen (bspw. den CEO). Sobald alle Parteien im Angebot unterschrieben haben,
erhält der Gegenzeichner eine Aufforderung um das Angebot final zu unterschreiben.

<Frame>
  <img alt="Gegenzeichner einrichten" />
</Frame>

### Compliance & Sicherheit

Die E-Signaturen werden durch [DocuSeal](https://www.docuseal.com) durchgeführt. Dabei wird das höchste Level
an Sicherheit, Transparenz und Compliance von digitalen Signaturen gewährleistet.

Weitere Informationen zur Compliance findest du [hier](https://www.docuseal.com/compliance).


# Regeln für Bankbuchungen
Source: https://docs.fynn.eu/guide/payments/bank-transaction-rules

Wiederkehrende Transaktionen automatisch ignorieren mit konfigurierbaren Regeln

## Übersicht

Mit Regeln kannst du wiederkehrende, irrelevante Bankbuchungen automatisch ignorieren lassen. Typische Anwendungsfälle:

* Kontoführungsgebühren deiner Bank
* Kreditkartenabbuchungen
* Interne Umbuchungen zwischen eigenen Konten
* Regelmäßige Abonnement-Zahlungen, die nicht zugeordnet werden müssen

Regeln werden beim Import neuer Bankbuchungen automatisch angewendet. Du kannst sie auch nachträglich auf bestehende, offene Buchungen anwenden.

<Frame>
  <img alt="Übersicht der Regeln in der Bankabstimmung" />
</Frame>

## Regel erstellen

<Steps>
  <Step title="Regeln öffnen">
    Navigiere zu [Buchhaltung > Kontobewegungen](https://app.fynn.eu/finance/bank-transactions) und klicke auf **Regeln** in der oberen Aktionsleiste.
  </Step>

  <Step title="Neue Regel anlegen">
    Klicke auf **Regel erstellen**. Es öffnet sich ein Formular mit folgenden Feldern:

    * **Name**: Beschreibender Name (z.B. "Kontogebühren ignorieren")
    * **Bedingungen**: Eine oder mehrere Filterbedingungen
    * **Priorität**: Reihenfolge der Regelauswertung (niedrigere Zahl = höhere Priorität)
  </Step>

  <Step title="Bedingungen definieren">
    Jede Bedingung besteht aus drei Teilen:

    | Feld                 | Operator    | Beispielwert    |
    | -------------------- | ----------- | --------------- |
    | **Gegenpartei**      | enthält     | "Qonto"         |
    | **IBAN**             | ist gleich  | "DE89..."       |
    | **Verwendungszweck** | enthält     | "Kontogebühren" |
    | **Betrag**           | kleiner als | 50              |
    | **Typ**              | ist gleich  | "Lastschrift"   |
    | **Transaktionscode** | ist gleich  | "RCDT"          |

    Beim Eingeben des Werts werden automatisch Vorschläge aus deinen bestehenden Bankbuchungen angezeigt.
  </Step>

  <Step title="Speichern">
    Klicke auf **Erstellen**. Die Regel ist sofort aktiv und wird bei allen zukünftigen Imports angewendet.
  </Step>
</Steps>

## Bedingungslogik

### Mehrere Bedingungen auf unterschiedlichen Feldern (UND)

Wenn eine Regel Bedingungen auf verschiedenen Feldern hat, müssen **alle** zutreffen (UND-Verknüpfung).

**Beispiel:** Gegenpartei enthält "Sparkasse" **UND** Verwendungszweck enthält "Gebühren"
→ Trifft nur auf Gebühren-Buchungen der Sparkasse zu, nicht auf reguläre Zahlungen.

### Mehrere Bedingungen auf demselben Feld (ODER)

Wenn eine Regel mehrere Bedingungen auf dem gleichen Feld hat, reicht es, wenn **eine** zutrifft (ODER-Verknüpfung).

**Beispiel:** Verwendungszweck enthält "Gebühren" **ODER** Verwendungszweck enthält "Entgeltabschluss"
→ Trifft auf beide Varianten zu.

### Kombiniert

Du kannst beides kombinieren: Gegenpartei enthält "Sparkasse" **UND** (Verwendungszweck enthält "Gebühren" **ODER** "Entgeltabschluss")

## Vorschläge

Fynn analysiert deine bereits manuell ignorierten Transaktionen und erkennt Muster. Wenn mindestens 3 Transaktionen vom selben Absender ignoriert wurden, schlägt das System eine passende Regel vor.

<Frame>
  <img alt="Vorgeschlagene Regeln basierend auf ignorierten Transaktionen" />
</Frame>

### Vorschläge enthalten

* Name und IBAN der Gegenpartei
* Anzahl der erkannten Transaktionen
* Die letzten Buchungen als Beispiele (mit Datum und Betrag)
* Vorgefüllte Bedingungen

### Vorschlag übernehmen

Klicke auf **Übernehmen**, um die vorgeschlagene Regel direkt zu erstellen. Du kannst Vorschläge auch mit dem X-Button verwerfen.

### Inline-Vorschlag nach dem Ignorieren

Wenn du eine Transaktion manuell ignorierst und weitere offene Buchungen vom selben Absender existieren, zeigt Fynn direkt einen Hinweis an:

> "Es gibt X weitere Transaktionen von \[Gegenpartei]. Regel erstellen?"

Mit einem Klick auf **Regel erstellen** wird eine passende Regel angelegt.

## Regeln verwalten

### Regeln anzeigen

Alle Regeln findest du unter **Regeln** in der Aktionsleiste der Kontobewegungen. Für jede Regel siehst du:

* Name und Bedingungen
* Status (Aktiv/Inaktiv)
* Anzahl der Treffer
* Letzter Treffer

### Regel aktivieren/deaktivieren

Verwende den Toggle-Schalter neben jeder Regel, um sie zu aktivieren oder zu deaktivieren. Deaktivierte Regeln werden beim Import nicht ausgewertet.

### Regel bearbeiten

Klicke auf das Stift-Symbol, um Name, Bedingungen und Priorität einer bestehenden Regel zu ändern.

### Regel löschen

Klicke auf das Papierkorb-Symbol. Du wirst um Bestätigung gebeten, bevor die Regel endgültig gelöscht wird.

## Regeln auf bestehende Buchungen anwenden

Neue Regeln gelten automatisch für zukünftige Imports. Um sie auch auf bereits vorhandene, offene Buchungen anzuwenden:

1. Öffne das Regel-Menü
2. Klicke auf **Regeln anwenden**
3. Bestätige die Aktion

Fynn prüft alle offenen Transaktionen gegen deine aktiven Regeln und ignoriert passende Buchungen. Du erhältst eine Zusammenfassung: "X von Y Transaktionen wurden durch Regeln ignoriert".

## Verfügbare Operatoren

| Operator        | Beschreibung                                            | Beispiel                                |
| --------------- | ------------------------------------------------------- | --------------------------------------- |
| **ist gleich**  | Exakter Abgleich (Groß-/Kleinschreibung wird ignoriert) | IBAN ist gleich "DE89..."               |
| **enthält**     | Teilstring-Suche                                        | Verwendungszweck enthält "Gebühren"     |
| **beginnt mit** | Präfix-Abgleich                                         | Verwendungszweck beginnt mit "LS RUECK" |
| **größer als**  | Numerischer Vergleich                                   | Betrag größer als 100                   |
| **kleiner als** | Numerischer Vergleich                                   | Betrag kleiner als 5                    |

## Wann werden Regeln ausgewertet?

| Zeitpunkt       | Beschreibung                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Beim Import** | Jede neue Bankbuchung wird gegen alle aktiven Regeln geprüft. Die erste passende Regel wird angewendet (nach Priorität). |
| **Manuell**     | Über "Regeln anwenden" können bestehende, offene Buchungen nachträglich geprüft werden.                                  |

<Info>
  Durch eine Regel ignorierte Transaktionen zeigen in der Detailansicht an, welche Regel den Ignore ausgelöst hat.
</Info>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Was passiert, wenn mehrere Regeln auf eine Buchung passen?">
    Regeln werden in Prioritätsreihenfolge ausgewertet (niedrigere Zahl = höhere Priorität). Die erste passende Regel wird angewendet, weitere werden nicht geprüft.
  </Accordion>

  <Accordion title="Kann ich eine durch Regel ignorierte Buchung wiederherstellen?">
    Ja. Wähle die Buchung aus und klicke auf **Wiederherstellen**. Die Buchung wird wieder als offen angezeigt. Die Regel bleibt bestehen und greift beim nächsten Import erneut.
  </Accordion>

  <Accordion title="Werden Regeln auch auf EBICS-Buchungen angewendet?">
    Ja. Regeln gelten für alle Bankbuchungen, unabhängig ob sie über GoCardless, EBICS oder camt-Import eingehen.
  </Accordion>
</AccordionGroup>


# Kontobewegungen
Source: https://docs.fynn.eu/guide/payments/bank-transactions

Bankbuchungen automatisch synchronisieren und mit offenen Rechnungen abgleichen

## Übersicht

Unter [Buchhaltung > Kontobewegungen](https://app.fynn.eu/finance/bank-transactions) siehst du alle Bankbuchungen deines Unternehmens. Fynn gleicht eingehende Zahlungen automatisch mit offenen Rechnungen ab und schlägt Zuordnungen vor.

Bankbuchungen gelangen auf zwei Wegen in Fynn:

* **Automatisch** über eine verbundene Bankverbindung — empfohlen
* **Manuell** über den Import von camt-Dateien (camt.052 / camt.053) — als Fallback

## Automatische Synchronisation über Bankverbindung

Der empfohlene Weg: Verbinde dein Geschäftskonto direkt mit Fynn und erhalte Bankbuchungen automatisch — ohne manuellen Export oder Datei-Upload.

**So funktioniert es:**

* Fynn ruft neue Buchungen regelmäßig über die verbundene Bankverbindung ab
* Eingehende Zahlungen werden automatisch mit offenen Rechnungen abgeglichen
* Vorgeschlagene Zuordnungen können mit einem Klick bestätigt werden

**Vorteile gegenüber manuellem Import:**

* Kein manueller Datei-Export aus dem Online-Banking nötig
* Buchungen erscheinen zeitnah in Fynn
* Weniger Fehlerquellen durch vollautomatischen Prozess

<Tip>
  Die Einrichtung der Bankverbindung erfolgt unter [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods). Eine Schritt-für-Schritt-Anleitung findest du in der [GoCardless-Integration](/integrations/payment-providers/go-cardless).
</Tip>

## camt-Import (camt.052 / camt.053)

Falls keine Bankverbindung eingerichtet ist oder deine Bank die automatische Synchronisation nicht unterstützt, können Bankbuchungen manuell per camt-Datei importiert werden.

Fynn unterstützt den Import von Bankbuchungen im ISO 20022 Format. Folgende Formate werden unterstützt:

| Format       | Beschreibung                       | Typischer Einsatz            |
| ------------ | ---------------------------------- | ---------------------------- |
| **camt.052** | Kontoumsatzanzeige (Vormerkposten) | Untertägige Transaktionen    |
| **camt.053** | Elektronischer Kontoauszug         | Tagesabschluss / Kontoauszug |

<Info>
  Die meisten deutschen Banken bieten den Export als camt-XML im Online-Banking oder über EBICS an.
</Info>

### Kontoauszug importieren

<Steps>
  <Step title="Kontobewegungen öffnen">
    Navigiere zu [Buchhaltung > Kontobewegungen](https://app.fynn.eu/finance/bank-transactions).
  </Step>

  <Step title="Import starten">
    Klicke auf `camt importieren` in der oberen Aktionsleiste. Es öffnet sich ein Import-Dialog.
  </Step>

  <Step title="Datei auswählen">
    Ziehe die camt-XML-Datei in das Upload-Feld oder klicke auf das Feld, um eine Datei auszuwählen.

    Folgende Anforderungen gelten:

    * **Dateiformat:** XML (camt.052 oder camt.053)
    * **Maximale Dateigröße:** 30 MB
  </Step>

  <Step title="Import bestätigen">
    Klicke auf `Importieren`. Die Datei wird hochgeladen und die Buchungen werden im Hintergrund verarbeitet. Du erhältst eine Bestätigung mit der Anzahl der gefundenen Buchungen.
  </Step>
</Steps>

<Tip>
  Bereits importierte Buchungen werden automatisch erkannt und übersprungen (Duplikaterkennung). Du kannst dieselbe Datei also bedenkenlos erneut importieren.
</Tip>

### Importierte Felder

Folgende Informationen werden aus der camt-Datei übernommen:

| Feld                    | Beschreibung                                                 |
| ----------------------- | ------------------------------------------------------------ |
| **Betrag**              | Transaktionsbetrag inkl. Vorzeichen (Gutschrift/Lastschrift) |
| **Währung**             | Währungscode (z.B. EUR)                                      |
| **Buchungsdatum**       | Datum der Buchung auf dem Konto                              |
| **Valutadatum**         | Wertstellungsdatum                                           |
| **Verwendungszweck**    | Unstrukturierte Remittance-Information                       |
| **Gegenpartei**         | Name und IBAN des Absenders/Empfängers                       |
| **End-to-End-Referenz** | Zahlungsreferenz (falls vorhanden)                           |

## Automatische Zuordnung

Unabhängig davon, ob Buchungen über die Bankverbindung oder per camt-Import eingehen — Fynn versucht automatisch, sie offenen Rechnungen zuzuordnen. Die Zuordnung basiert auf:

* **End-to-End-Referenz** — Abgleich mit der Rechnungsnummer
* **Betrag** — Übereinstimmung mit dem offenen Rechnungsbetrag
* **Kundendaten** — Abgleich der Gegenpartei mit bekannten Kunden

Nicht automatisch zugeordnete Buchungen erscheinen im Status **Offen** und können manuell zugeordnet oder ignoriert werden.

## Manuelle Zuordnung

Bei der manuellen Zuordnung suchst du eine passende Rechnung und weist sie der Bankbuchung zu. Um die richtige Rechnung sicher zu identifizieren, zeigt Fynn die **bestehende Zahlungshistorie** der Rechnung direkt in der Suchergebnis-Liste an.

### Zahlungshistorie einer Rechnung einsehen

Klicke auf den Pfeil neben einer Rechnung in den Suchergebnissen, um die bisherigen Zahlungseingänge aufzuklappen. Für jede Transaktion wird angezeigt:

| Feld            | Beschreibung                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------- |
| **Status**      | Aktueller Zahlungsstatus (Bezahlt, Ausstehend, Erstattet, Fehlgeschlagen)                           |
| **Datum**       | Zeitpunkt der Zahlung                                                                               |
| **Zahlungsweg** | Über welchen Kanal die Zahlung eingegangen ist (Stripe, PayPal, Überweisung, SEPA, Manuell, Wallet) |
| **Betrag**      | Gezahlter Betrag (bei Erstattungen mit Minus-Vorzeichen)                                            |

So erkennst du auf einen Blick, ob und in welcher Höhe bereits Zahlungen für eine Rechnung vorliegen — bevor du eine weitere Bankbuchung zuordnest. Das verhindert versehentliche Doppelzuordnungen.

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Welche camt-Versionen werden unterstützt?">
    Fynn unterstützt die gängigen Versionen der Formate camt.052 und camt.053 (ISO 20022). Dazu gehören die Versionen 002, 003, 004 und 008. Falls du eine nicht unterstützte Version verwendest, kontaktiere bitte den Support.
  </Accordion>

  <Accordion title="Was passiert bei doppeltem Import?">
    Fynn erkennt bereits importierte Buchungen anhand eines Hash-Werts über die Kernfelder (Betrag, Datum, Verwendungszweck etc.) und überspringt Duplikate automatisch.
  </Accordion>

  <Accordion title="Kann ich den Import rückgängig machen?">
    Einzelne importierte Buchungen können nicht automatisch gelöscht werden. Du kannst jedoch Buchungen ignorieren, die nicht relevant sind.
  </Accordion>

  <Accordion title="Meine Bank exportiert die Datei mit einem Namespace-Präfix — funktioniert das?">
    Ja. Fynn normalisiert das XML automatisch, unabhängig davon, ob die Namespaces mit oder ohne Präfix deklariert sind.
  </Accordion>
</AccordionGroup>


# Zahlungen
Source: https://docs.fynn.eu/guide/payments/introduction

Verwalte Zahlungen, Transaktionen und offene Beträge deiner Kunden

Fynn bietet dir eine zentrale Übersicht über alle Zahlungen deiner Kunden. Verfolge Transaktionen, verwalte offene Beträge und behalte den Überblick über den Zahlungsstatus deiner Rechnungen.

## Zahlungsübersicht

In der Zahlungsübersicht siehst du alle Transaktionen auf einen Blick:

* **Erfolgreiche Zahlungen**: Abgeschlossene Transaktionen
* **Ausstehende Zahlungen**: Noch nicht abgeschlossene Zahlungsvorgänge
* **Fehlgeschlagene Zahlungen**: Transaktionen mit Fehlern

## Zahlungsmethoden

Fynn unterstützt verschiedene Zahlungsmethoden, die du für deine Kunden aktivieren kannst:

<CardGroup>
  <Card title="SEPA-Lastschrift" icon="building-columns" href="/integrations/payment-providers/sepa">
    Automatischer Bankeinzug für wiederkehrende Zahlungen im SEPA-Raum.
  </Card>

  <Card title="Kreditkarte" icon="credit-card" href="/integrations/payment-providers/stripe">
    Visa, Mastercard und weitere Karten über Stripe.
  </Card>

  <Card title="PayPal" icon="paypal" href="/integrations/payment-providers/paypal">
    Beliebte Online-Zahlungsmethode für deine Kunden.
  </Card>

  <Card title="Überweisung" icon="money-bill-transfer" href="/integrations/payment-providers/bank-transfer">
    Klassische Banküberweisung mit automatischem Abgleich.
  </Card>
</CardGroup>

## Zahlungen zuordnen

Eingehende Zahlungen können automatisch oder manuell Rechnungen zugeordnet werden:

1. **Automatische Zuordnung**: Bei Lastschriften und Kartenzahlungen erfolgt die Zuordnung automatisch
2. **Manuelle Zuordnung**: Bei Überweisungen kannst du Zahlungen manuell zuordnen oder Vorschläge annehmen

<Tip>
  Nutze die EBICS-Integration für automatischen Kontoabgleich und intelligente Zahlungsvorschläge.
</Tip>

## Nächste Schritte

<CardGroup>
  <Card title="Zahlungsmethoden einrichten" icon="gear" href="/guide/payments/payment-methods">
    Konfiguriere die verfügbaren Zahlungsmethoden für deine Kunden.
  </Card>

  <Card title="Mahnwesen" icon="triangle-exclamation" href="/guide/dunning/introduction">
    Automatisiere den Umgang mit überfälligen Zahlungen.
  </Card>
</CardGroup>


# Zahlungen verwalten
Source: https://docs.fynn.eu/guide/payments/manage-payments

Füge Zahlungen hinzu, stoße fehlgeschlagene Zahlungen erneut an und verwalte Zahlungsgebühren

## Zahlung hinzufügen

Wenn ein Kunde eine Rechnung bezahlt, kannst du die Zahlung in Fynn manuell hinzufügen, um den Rechnungsstatus zu aktualisieren.
Dies ist relevant, wenn bspw. Überweisungen getätigt wurden, oder die Zahlungen in einem Fremd-System erfasst wurden.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Rechnung öffnen">
        Navigiere zur gewünschten Rechnung in der Rechnungsübersicht
      </Step>

      <Step title="Zahlung hinzufügen">
        Klicke auf `Zahlung hinzufügen`
      </Step>

      <Step title="Zahlungsdetails eingeben">
        Trage die Zahlungsdetails ein und bestätige mit `Speichern`.

        Entspricht der Betrag der Rechnung, wird die Rechnung automatisch auf `Bezahlt` gesetzt.
        Sofern die Benachrichtigungseinstellungen aktiviert sind, wird der Kunde über den Zahlungseingang und den aktualisierten Rechnungsstatus informiert.

        <Frame>
          <img alt="Zahlung hinzufügen" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Zahlung hinzufügen](/api-reference/invoice/add-invoice-payment) Endpunkt.

    ```bash theme={null}
    POST /invoices/{id}/payments
    ```
  </Tab>
</Tabs>

## Zahlung erneut anstoßen

Wenn eine Zahlung fehlgeschlagen ist, kannst du sie erneut anstoßen. Hierbei kann eine neue oder bestehende Zahlungsmethode verwendet werden.

Nach Änderung der Zahlungsmethode wird der ausstehende Betrag automatisch über die neue Zahlungsmethode eingezogen.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Rechnung öffnen">
        Navigiere zur gewünschten Rechnung in der Rechnungsübersicht
      </Step>

      <Step title="Zahlung erneut anstoßen">
        Klicke auf `Aktionen` > `Zahlungsart ändern`.
        Wähle eine neue Zahlungsmethode aus und bestätige mit `Ausstehenden Betrag begleichen`.

        Die neue Zahlungsmethode wird automatisch für die ausstehende Zahlung verwendet.

        <Frame>
          <img alt="Zahlungsart ändern" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Zahlung erneut anstoßen](/api-reference/invoice/set-invoice-payment-method) Endpunkt.

    ```bash theme={null}
    POST /invoices/{id}/payment-method
    ```
  </Tab>
</Tabs>

## Aktualität der Bankdaten prüfen

In der Zahlungsübersicht siehst du direkt über der Tabelle, wann deine verbundenen Bankkonten zuletzt abgeglichen wurden — zum Beispiel `vor 2 Std., 14:32`. So erkennst du auf einen Blick, ob die angezeigten Zahlungen auf dem aktuellen Stand deiner Bank sind, bevor du Rechnungen zuordnest oder mit Kunden kommunizierst.

Der Hinweis ist für alle Teammitglieder sichtbar, die Zugriff auf die Zahlungsübersicht haben. Auch wenn du die Bankbuchungen selbst nicht öffnen darfst, weißt du damit jederzeit, wie frisch die zugrunde liegenden Daten sind.

Sind noch keine Bankkonten verbunden, erscheint stattdessen der Hinweis `Keine Bankkonten verbunden`.

## Zahlungsanbieter-Gebühren

Bei Zahlungen über integrierte Zahlungsanbieter können Gebühren anfallen. Diese werden dir transparent in der Rechnungsdetailansicht angezeigt:

1. Öffne die Rechnung
2. Scrolle zum Abschnitt "Zahlungen"
3. Die Gebühren werden pro Zahlung einzeln ausgewiesen


# Zahlungsmethoden verwalten
Source: https://docs.fynn.eu/guide/payments/payment-methods

Hinzufügen, bearbeiten und entfernen von Zahlungsmethoden für deine Kunden

## Übersicht

Zahlungsmethoden sind die Grundlage für automatisierte Abrechnungen. Fynn unterstützt verschiedene Zahlungsmethoden:

<CardGroup>
  <Card title="SEPA-Lastschrift" icon="building-columns">
    Automatischer Einzug via SEPA-Mandat. Unterstützt durch EBICS und Stripe.
  </Card>

  <Card title="Kreditkarte" icon="credit-card">
    Visa, Mastercard, American Express und weitere. PCI-konform über Stripe.
  </Card>

  <Card title="PayPal" icon="paypal">
    Beliebte Zahlungsmethode für Online-Käufe. Ein PayPal-Konto pro Kunde.
  </Card>

  <Card title="Überweisung" icon="money-bill-transfer">
    Für manuelle Zahlungen. Keine automatische Abbuchung.
  </Card>
</CardGroup>

***

## Zahlungsmethode hinzufügen

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zu **Kunden** und wähle den Kunden aus, für den du eine Zahlungsmethode hinzufügen möchtest.

        Wechsle zum Tab **Stammdaten**.
      </Step>

      <Step title="Zahlungsmethode hinzufügen">
        Klicke im Bereich **Zahlungsmethoden** auf **+ Hinzufügen** und wähle den gewünschten Typ:

        <AccordionGroup>
          <Accordion title="SEPA-Mandat erfassen" icon="building-columns">
            Erfasse ein SEPA-Mandat direkt in Fynn:

            * **IBAN**: Die Bankverbindung des Kunden
            * **Kontoinhaber**: Name des Kontoinhabers
            * **Mandatsreferenz**: Wird automatisch generiert oder manuell eingegeben
            * **Unterschriftsdatum**: Datum der Mandatsunterschrift

            <Info>
              Das SEPA-Mandat wird digital gespeichert und kann jederzeit eingesehen werden.
            </Info>
          </Accordion>

          <Accordion title="Stripe Zahlungsmethode" icon="credit-card">
            Über Stripe können Kreditkarten und SEPA-Lastschriften hinzugefügt werden.

            Der Kunde erhält einen sicheren Link zur Eingabe seiner Zahlungsdaten.
          </Accordion>

          <Accordion title="PayPal hinzufügen" icon="paypal">
            Verbinde das PayPal-Konto des Kunden.

            <Warning>
              Pro Kunde kann nur ein PayPal-Konto hinterlegt werden.
            </Warning>
          </Accordion>
        </AccordionGroup>
      </Step>

      <Step title="Als Standard festlegen">
        Nach dem Hinzufügen kannst du die Zahlungsmethode als **Standard** markieren.

        Die Standard-Zahlungsmethode wird automatisch für neue Abonnements und Rechnungen verwendet.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Link an Kunde senden">
    Du kannst dem Kunden einen Link senden, über den er selbst eine Zahlungsmethode hinzufügen kann:

    <Steps>
      <Step title="Link erstellen">
        Klicke im Aktions-Menü (···) der Kundendetails auf **Zahlungsmethode anfordern**.
      </Step>

      <Step title="Link versenden">
        Wähle, ob der Link per E-Mail an den Kunden gesendet werden soll, oder kopiere den Link manuell.

        <Info>
          Der Link ist **7 Tage** gültig.
        </Info>
      </Step>

      <Step title="Kunde fügt Zahlungsmethode hinzu">
        Der Kunde kann über den Link sicher seine Zahlungsdaten eingeben.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Payment Method Link](/api-reference/paymentmethod/create-payment-method-link) Endpunkt:

    ```bash theme={null}
    POST /payment-methods/link
    ```

    ```json theme={null}
    {
      "customer": "cus_abc123",
      "sendEmail": true,
      "allowedPaymentMethodTypes": ["card", "sepa_debit"]
    }
    ```
  </Tab>
</Tabs>

***

## Zahlungsmethode entfernen

<Warning>
  Das Entfernen einer Zahlungsmethode kann Auswirkungen auf bestehende Abonnements haben.
  Fynn führt dich durch alle notwendigen Schritte.
</Warning>

### Standard-Zahlungsmethode entfernen

Wenn du die aktuelle **Standard-Zahlungsmethode** entfernst, musst du eine neue Standard-Zahlungsmethode auswählen:

<Frame>
  <img alt="Neue Standard-Zahlungsmethode auswählen" />
</Frame>

<Steps>
  <Step title="Neue Standard auswählen">
    Wähle eine der verbleibenden Zahlungsmethoden als neue Standard-Zahlungsmethode.
  </Step>

  <Step title="Bestätigen">
    Nach der Auswahl wird die neue Standard-Zahlungsmethode sofort aktiv.

    Alle Abonnements, die die "Standard-Zahlungsmethode des Kunden" verwenden, nutzen automatisch die neue Zahlungsmethode.
  </Step>
</Steps>

### Zahlungsmethode mit Abonnements

Wenn Abonnements diese Zahlungsmethode **explizit** verwenden, musst du entscheiden, wohin die Abonnements migriert werden:

<Frame>
  <img alt="Abonnements migrieren" />
</Frame>

<AccordionGroup>
  <Accordion title="Standard-Zahlungsmethode" icon="star">
    Die Abonnements werden auf die **Standard-Zahlungsmethode des Kunden** umgestellt.

    <Tip>
      Dies ist die empfohlene Option, da zukünftige Änderungen der Standard-Zahlungsmethode automatisch übernommen werden.
    </Tip>
  </Accordion>

  <Accordion title="Andere Zahlungsmethode" icon="credit-card">
    Die Abonnements werden auf eine **spezifische andere Zahlungsmethode** umgestellt.

    Diese bleibt fest zugewiesen, bis sie manuell geändert wird.
  </Accordion>
</AccordionGroup>

***

## Standard-Zahlungsmethode ändern

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Stammdaten öffnen">
        Navigiere zu **Kunden** → Kunde auswählen → Tab **Stammdaten**.
      </Step>

      <Step title="Als Standard festlegen">
        Klicke bei der gewünschten Zahlungsmethode auf das Radio-Button-Symbol, um sie als Standard zu markieren.

        <Frame>
          <img alt="Als Standard festlegen" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende den [Set Default Payment Method](/api-reference/paymentmethod/set-default-payment-method) Endpunkt:

    ```bash theme={null}
    PUT /customers/{customerId}/payment-method
    ```

    ```json theme={null}
    {
      "paymentMethodId": "pm_abc123"
    }
    ```
  </Tab>
</Tabs>

***

## SEPA-Mandate

### Mandat einsehen

Für SEPA-Zahlungsmethoden kannst du das hinterlegte Mandat jederzeit einsehen:

<Steps>
  <Step title="SEPA-Mandat Badge">
    Klicke auf den **SEPA-Mandat** Badge bei der entsprechenden Zahlungsmethode.
  </Step>

  <Step title="Mandatsdetails">
    Ein Popover zeigt alle relevanten Informationen:

    * Mandatsreferenz
    * Gläubiger-ID
    * IBAN (maskiert)
    * Kontoinhaber
    * Unterschriftsdatum
    * Mandatstyp (Einmalig/Wiederkehrend)
  </Step>
</Steps>

### SEPA-Fehler

Bei fehlgeschlagenen SEPA-Lastschriften wird die Zahlungsmethode je nach Fehlerart behandelt:

| Fehlertyp                             | Aktion                           |
| ------------------------------------- | -------------------------------- |
| **Mandatsproblem** (MD01, MD02, etc.) | Zahlungsmethode wird deaktiviert |
| **Kontoproblem** (AC01, AC04, etc.)   | Zahlungsmethode wird deaktiviert |
| **Vorübergehend** (AM04, AM05, etc.)  | Automatischer Retry wird geplant |
| **Regulatorisch** (AG01, RR01, etc.)  | Manuelle Prüfung erforderlich    |

<Info>
  Bei deaktivierten Zahlungsmethoden erhält der Kunde automatisch eine Benachrichtigung mit einem Link zum Hinzufügen einer neuen Zahlungsmethode.
</Info>

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich eine gelöschte Zahlungsmethode wiederherstellen?">
    Nein, entfernte Zahlungsmethoden werden deaktiviert und können nicht wiederhergestellt werden.

    Der Kunde muss eine neue Zahlungsmethode hinzufügen.
  </Accordion>

  <Accordion title="Was passiert mit laufenden Abonnements?">
    Beim Entfernen wirst du aufgefordert, die Abonnements zu einer anderen Zahlungsmethode oder zur Standard-Zahlungsmethode zu migrieren.

    Es gibt keine Unterbrechung der Abrechnung.
  </Accordion>

  <Accordion title="Wie lange ist der Zahlungsmethoden-Link gültig?">
    Links zum Hinzufügen einer Zahlungsmethode sind **7 Tage** gültig.

    Danach muss ein neuer Link erstellt werden.
  </Accordion>

  <Accordion title="Kann ein Kunde mehrere Zahlungsmethoden haben?">
    Ja, ein Kunde kann beliebig viele Zahlungsmethoden haben.

    **Ausnahme:** Pro Kunde ist nur ein PayPal-Konto möglich.
  </Accordion>
</AccordionGroup>


# Zahlungsplan
Source: https://docs.fynn.eu/guide/payments/payment-plans

Teile eine offene Rechnung in zinsfreie Monatsraten auf. Das Mahnwesen ruht, solange der Plan läuft.

Kann ein Kunde eine Rechnung nicht auf einmal begleichen, richtest du einen **Zahlungsplan** ein. Der offene Betrag wird dann in mehrere Raten aufgeteilt, ohne Zinsen. Solange der Plan läuft, ruht das Mahnwesen für diese Rechnung, und fällige Lastschrift-Raten zieht Fynn automatisch ein.

<Info>
  Ein Zahlungsplan ändert die Rechnung nicht: Sie bleibt eine Forderung und ist beglichen, sobald alle Raten bezahlt sind. Der Plan verteilt nur den offenen Betrag über die Zeit.
</Info>

## Zahlungsplan einrichten

<Steps>
  <Step title="Rechnung öffnen">
    Öffne die offene Rechnung, für die der Kunde in Raten zahlen soll. Ein Zahlungsplan ist für finalisierte, noch offene Rechnungen möglich, nicht für Entwürfe oder bereits bezahlte Rechnungen.

    <Frame>
      <img alt="Rechnungsdetails mit Option zum Einrichten eines Zahlungsplans" />
    </Frame>
  </Step>

  <Step title="Zahlungsplan einrichten">
    Wähle im Bereich Zahlungsplan die Option zum Einrichten. Der offene Betrag der Rechnung ist die Summe, die auf die Raten verteilt wird.

    <Frame>
      <img alt="Dialog mit Auswahl zwischen gleichmäßiger Aufteilung und manuellen Raten" />
    </Frame>
  </Step>

  <Step title="Raten aufteilen oder manuell festlegen">
    Du hast zwei Wege:

    * **Gleichmäßig aufteilen:** Gib die Anzahl der Raten (zwei bis 36) und das Datum der ersten Rate an. Fynn berechnet die Beträge und die weiteren Termine im Monatsabstand. Geht der Betrag nicht glatt auf, landet der Rundungsrest auf der letzten Rate.
    * **Manuell festlegen:** Bestimme jede Rate mit eigenem Betrag und Fälligkeitsdatum. Die Termine müssen aufsteigend und in der Zukunft liegen, und die Summe aller Raten muss dem offenen Betrag der Rechnung entsprechen.

    Standardmäßig wird für den Einzug die Zahlungsmethode der Rechnung verwendet.
  </Step>

  <Step title="Plan aktivieren">
    Bestätige die Einrichtung. Der Plan läuft ab sofort, und das Mahnwesen für diese Rechnung ruht. Der Kunde erhält beim Einrichten eine E-Mail mit der Ratenübersicht, also allen Raten samt Fälligkeit und Betrag sowie dem Gesamtbetrag. Über die API kannst du diese E-Mail mit `sendEmail: false` abwählen.

    <Frame>
      <img alt="Zahlungsplan mit Ratenübersicht und Status je Rate" />
    </Frame>
  </Step>
</Steps>

## Was passiert, während der Plan läuft

<Check>
  Solange der Plan läuft, wird die Rechnung im Mahnlauf übersprungen. Es gehen keine Zahlungserinnerungen oder Mahnungen für diese Rechnung raus.
</Check>

* **Ankündigung per E-Mail:** Sieben Tage vor jeder Fälligkeit erhält der Kunde eine E-Mail. Bei Lastschrift kündigt sie den Einzug an, bei Überweisung ist sie eine Zahlungsaufforderung mit Betrag und Termin.
* **Lastschrift wird automatisch eingezogen:** Zahlt der Kunde per Lastschrift, löst Fynn den Einzug sieben Tage vor Fälligkeit selbst aus. Du musst nichts tun.
* **Überweisung mit einem Tag Karenz:** Zahlt der Kunde per Überweisung, ordnet Fynn den Zahlungseingang der Rechnung zu. Für den Abgleich gilt ein Tag Karenz nach der Fälligkeit.

Jede bezahlte Rate zählt auf den offenen Betrag der Rechnung. Sind alle Raten bezahlt, ist die Rechnung beglichen und der Plan abgeschlossen.

## Was bei einem Planbruch passiert

Ein Plan bricht, wenn ein Lastschrift-Einzug fehlschlägt oder eine Rate über ihre Frist hinaus unbeglichen bleibt.

<Warning>
  Bricht der Plan, wird der **gesamte Restbetrag sofort fällig**. Das Mahnwesen für die Rechnung läuft ab dann wieder, und der nächste Mahnlauf berücksichtigt die Rechnung ganz normal.
</Warning>

Willst du dem Kunden trotzdem weiter entgegenkommen, kannst du den gebrochenen Plan verlängern (siehe unten). Er kehrt damit in den laufenden Zustand zurück, und das Mahnwesen ruht wieder.

## Verlängern statt neu anlegen

Braucht ein Kunde mehr Zeit oder ist eine Rate ausgefallen, verlängere den bestehenden Plan, statt einen neuen anzulegen. Beim Verlängern legst du einen neuen Zeitplan für alle noch nicht bezahlten Raten fest. Bereits bezahlte Raten bleiben unberührt, und die Summe der neuen Raten entspricht dem aktuellen Restbetrag.

<Info>
  Eine Rechnung kann nur einen aktiven Plan haben. Deshalb verlängerst du den bestehenden Plan, statt einen zweiten anzulegen. Ein gebrochener Plan läuft nach dem Verlängern wieder.
</Info>

## Kündigen

Soll ein Plan enden, kündige ihn. Der Restbetrag ist danach sofort fällig, und das Mahnwesen läuft wieder, genau wie bei einem Planbruch. Bereits bezahlte Raten bleiben verbucht.


# Rücklastschriften
Source: https://docs.fynn.eu/guide/payments/payment-returns

Bearbeite zurückgegebene SEPA-Lastschriften an einem Ort: mit automatischer Zuordnung, Wiedereinzug, Gebühren und Selbstbedienung für deine Kunden.

Wird eine SEPA-Lastschrift von der Bank zurückgegeben, legt Fynn dafür automatisch einen Vorgang an, ordnet ihn der ursprünglichen Rechnung und dem Kunden zu und schlägt anhand deiner Regeln die nächsten Schritte vor. Alle Rückläufer sammelst du an einem Ort, statt sie einzeln aus Kontoauszügen herauszusuchen.

Ein Vorgang entsteht immer dann, wenn ein Einzug scheitert, zum Beispiel wegen fehlender Deckung, eines geschlossenen Kontos, eines fehlenden Mandats oder eines Widerspruchs des Kunden.

## Übersicht der Vorgänge

Unter `Zahlungen > Rücklastschriften` findest du alle Rückläufer mit Status, Grundkategorie, Betrag und zugeordneter Rechnung. Du filterst nach Status, Kategorie, Kunde oder Zeitraum und exportierst die gefilterte Liste als CSV.

Jeder Vorgang durchläuft einen Status:

| Status               | Bedeutung                                                              |
| -------------------- | ---------------------------------------------------------------------- |
| Erkannt              | Der Rückläufer ist eingegangen, aber noch keiner Rechnung zugeordnet   |
| Zuordnung prüfen     | Die automatische Zuordnung war nicht eindeutig, du ordnest von Hand zu |
| Zugeordnet           | Rechnung, Zahlung und Kunde sind verknüpft                             |
| Bearbeitet           | Die Rückbuchung ist verbucht, der offene Betrag steht wieder aus       |
| Wiedereinzug geplant | Ein erneuter Einzug ist für einen Stichtag vorgemerkt                  |
| Wartet auf Kunde     | Der Kunde wurde benachrichtigt und kann selbst reagieren               |
| In Prüfung           | Der Vorgang liegt zur manuellen Entscheidung bei deinem Team           |
| Beigetrieben         | Der offene Betrag ist ausgeglichen, der Vorgang ist abgeschlossen      |
| Abgeschrieben        | Die Forderung wurde ausgebucht                                         |
| Übergeben            | Der Fall wurde an ein Inkasso oder einen externen Prozess übergeben    |

Die letzten drei Status schließen den Vorgang ab.

### Grundkategorien

Fynn ordnet jeden Rückläufer einer Kategorie zu, die steuert, wie er weiterbehandelt wird:

| Kategorie     | Typischer Grund                                             |
| ------------- | ----------------------------------------------------------- |
| Deckung       | Konto nicht ausreichend gedeckt, in der Regel vorübergehend |
| Konto         | Konto geschlossen, gesperrt oder erloschen                  |
| Mandat        | Kein oder kein gültiges SEPA-Mandat                         |
| Widerspruch   | Der Kunde hat der Lastschrift widersprochen                 |
| Technisch     | Format- oder Datenfehler beim Einzug                        |
| Regulatorisch | Aufsichtsrechtliche Sperre                                  |
| Unbekannt     | Kein näherer Grund von der Bank übermittelt                 |

<Info>
  Den technischen Rückgabegrund der Bank sehen nur Benutzer mit der entsprechenden Berechtigung. In Listen, im Export und für deine Kunden bleibt es bei der Kategorie.
</Info>

## Einen Vorgang bearbeiten

Öffnest du einen Vorgang, siehst du den Verlauf, die zugeordnete Rechnung und die verfügbaren Aktionen:

* **Zuordnen**: Verknüpfe den Rückläufer mit der richtigen Rechnung, falls die automatische Zuordnung nicht eindeutig war.
* **Wiedereinzug**: Starte einen erneuten Einzug sofort oder plane ihn auf einen Stichtag. Fynn prüft dabei Mandat, Vorlauffrist und einen möglichen Mahnstopp.
* **Gebühr**: Gib eine Rücklastschriftgebühr an den Kunden weiter oder erlasse sie mit einer Begründung.
* **In Prüfung geben**: Eskaliere den Vorgang zur manuellen Entscheidung.
* **Abschließen**: Schließe den Vorgang als beigetrieben, abgeschrieben oder übergeben ab, jeweils mit Begründung.

<Warning>
  Vorgänge aus einem Widerspruch des Kunden sperren eine Übergabe an Inkasso, solange der Widerspruch offen ist. Die Sperre hebst du bewusst mit einer schriftlichen Begründung auf. Der Schritt wird im Verlauf des Vorgangs festgehalten.
</Warning>

### Gebühren

Die Gebühr, die du an den Kunden weitergibst, richtet sich nach deiner Regel. Bei Privatkunden ist sie auf die nachgewiesene Bankgebühr zuzüglich einer Porto-Pauschale gedeckelt, bei Geschäftskunden ist der Betrag frei. Bei Widerspruch, technischen Fehlern und aufsichtsrechtlichen Sperren wird keine Gebühr berechnet.

## Regeln festlegen

Unter `Einstellungen > Rücklastschriften` legst du fest, wie Fynn Rückläufer automatisch behandelt. Die Regeln gelten je Kundensegment (Privat- und Geschäftskunden) und je Grundkategorie:

| Einstellung             | Optionen                                                                  |
| ----------------------- | ------------------------------------------------------------------------- |
| Wiedereinzug            | kein, automatisch nach Wartezeit, nur manuell                             |
| Maximale Versuche       | Anzahl der erneuten Einzüge, bevor der Abschluss greift                   |
| Wartezeit               | Tage bis zum nächsten Einzug                                              |
| Gebühr                  | keine, tatsächliche Bankgebühr, fester gedeckelter Betrag                 |
| Zahlungsmethode sperren | SEPA-Lastschrift des Kunden bei Rückläufer deaktivieren                   |
| Kunde benachrichtigen   | Selbstbedienungs-Link versenden                                           |
| Abschluss               | offen lassen, ausbuchen oder übergeben, wenn alle Versuche erschöpft sind |

<Note>
  Für Deckungsrückläufer ist ein automatischer Wiedereinzug sinnvoll, weil der Grund meist vorübergehend ist. Bei Widerspruch, Mandats- und Kontofehlern greift Fynn nie automatisch zum Einzug, unabhängig von deiner Regel.
</Note>

## Selbstbedienung für Kunden

Ist `Kunde benachrichtigen` aktiv, erhält der Kunde einen Link und kann ohne Anmeldung selbst reagieren. Er sieht den offenen Betrag und die Rechnungsnummer, nie den technischen Rückgabegrund. Je nach Fall stehen ihm drei Wege offen:

<Steps>
  <Step title="Wiedereinzug bestätigen">
    Der Kunde bestätigt einen erneuten Einzug und wählt bei Bedarf ein Datum. Fynn setzt es auf den frühestmöglichen Einzugstermin, wenn die Vorlauffrist es erfordert.
  </Step>

  <Step title="Neue Bankverbindung hinterlegen">
    Der Kunde hinterlegt ein neues SEPA-Mandat. Anschließend zieht Fynn alle offenen Rechnungen über die neue Verbindung ein.
  </Step>

  <Step title="Per Überweisung zahlen">
    Der Kunde erhält Empfänger-IBAN, Verwendungszweck und einen QR-Code für die Überweisung. Der Zahlungseingang wird automatisch abgeglichen.
  </Step>
</Steps>

Jede Reaktion des Kunden erscheint im Verlauf des Vorgangs, sodass dein Team den Stand jederzeit nachvollziehen kann.

## Auswertung

Unter den Auswertungen findest du eine Übersicht über Rückläufer und Beitreibung: Rücklaufquote im Zeitverlauf, Aufschlüsselung nach Grundkategorie und Zahlungsweg sowie die Beitreibungsquote und die durchschnittliche Dauer bis zum Ausgleich. Für einzelne Kunden zeigt Fynn zusätzlich einen Risikohinweis, wenn sich Rückläufer häufen.


# Einzugsplan (Wallet)
Source: https://docs.fynn.eu/guide/payments/wallet-charge-plan

Ziehe wiederkehrende Abschläge automatisch auf das Guthabenkonto deiner Kunden ein und überwache Fälligkeiten und Verzug

Mit einem Einzugsplan lädst du das Guthabenkonto (Wallet) eines Kunden regelmäßig automatisch auf, zum Beispiel als monatlichen Abschlag bei einem Stromtarif. Der Plan erzeugt zu jedem Stichtag eine Rate, zieht sie über die hinterlegte Zahlungsmethode ein oder wartet auf eine Überweisung, und eskaliert bei Verzug.

Das Guthaben wächst planmäßig und wird erst mit der Jahres- oder Schlussrechnung verrechnet. Es entsteht keine monatliche Rechnung.

## Einzugsplan anlegen

<Steps>
  <Step title="Kunde öffnen">
    Navigiere zum gewünschten Kunden und öffne den Tab `Einzugsplan`.
  </Step>

  <Step title="Plan konfigurieren">
    Klicke auf `Einzugsplan anlegen` und lege fest:

    * **Betrag** je Rate
    * **Intervall**, zum Beispiel monatlich
    * **Stichtag**: der Tag im Monat, an dem eingezogen wird. Fällt der Tag nicht in den Monat (etwa der 31. im Februar), wird der letzte Tag des Monats verwendet.
    * **Raten**: optional die Anzahl der Raten, zum Beispiel 11 oder 12. Ohne Angabe läuft der Plan unbegrenzt.
    * **Methode**: `Zahlungsmethode belasten` zieht aktiv über die Zahlungsmethode des Kunden ein. `Überweisung erwarten` legt nur die Fälligkeit an und wartet auf den Zahlungseingang.
  </Step>

  <Step title="Speichern">
    Der Plan startet zum nächsten Stichtag. Pro Kunde gibt es einen Einzugsplan; erneutes Speichern ersetzt die Konfiguration.
  </Step>
</Steps>

## Raten und Status

Jede Rate durchläuft einen eigenen Status, den du im Kunden-Tab und in der globalen Übersicht unter `Einzüge` verfolgst:

| Status         | Bedeutung                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Geplant        | Die Rate ist angelegt und wartet auf Einzug oder Zahlungseingang                                    |
| Bezahlt        | Die Rate wurde eingezogen oder durch eine Aufladung gedeckt                                         |
| Fehlgeschlagen | Ein Einzugsversuch ist gescheitert, es folgt automatisch ein neuer Versuch                          |
| Überfällig     | Die erwartete Überweisung ist bis zum Stichtag nicht eingegangen                                    |
| Eskaliert      | Nach drei gescheiterten Versuchen wurde die Rate an den Mahnprozess übergeben und der Plan pausiert |

Bei jedem Fehlschlag und bei Verzug erhält der Kunde automatisch eine E-Mail-Erinnerung. Zusätzlich erscheint bei überfälligen und eskalierten Raten ein Eintrag in Signal, damit dein Team reagieren kann.

## Automatisierung über die API

Alle Funktionen stehen auch über die API bereit, zum Beispiel für die Anbindung eines EVU-Systems. Der Einzugsplan ist eine automatische Aufladung vom Typ `scheduled`; daneben gibt es den Typ `threshold`, der auflädt, sobald das Guthaben unter einen Schwellwert fällt. Beide Typen können je Kunde und Währung parallel existieren.

```bash theme={null}
curl -X POST https://api.fynn.eu/api/wallet/auto-top-up \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customer-id>",
    "currencyCode": "EUR",
    "type": "scheduled",
    "topUpAmount": 50.00,
    "interval": "P1M",
    "chargeDay": 15,
    "installments": 11,
    "method": "bank_transfer"
  }'
```

* `POST /api/wallet/auto-top-up` legt die Regel an. `topUpAmount` ist der Betrag je Rate in Euro, `interval` eine ISO-8601-Dauer in ganzen Monaten (`P1M`, `P3M`, ...), `method` entweder `payment_method` oder `bank_transfer`.
* `GET /api/wallet/auto-top-up?customerId=...` listet die Regeln des Kunden, inklusive Typ, Status und nächstem Stichtag.
* `PUT /api/wallet/auto-top-up/{ruleId}` ändert die Regel. Ein geänderter Stichtag oder ein geändertes Intervall berechnet die nächste Fälligkeit neu.
* `DELETE /api/wallet/auto-top-up/{ruleId}` kündigt den Einzugsplan; die Raten-Historie bleibt erhalten.
* `GET /api/wallet/charges?customerId=...&status=overdue` listet Raten inklusive Fälligkeit, Versuchen und letztem Fehler.
* `GET /api/wallet/top-ups?customerId=...` listet die Aufladungen des Guthabenkontos.

Über Webhooks bleibst du über Verzug informiert: `wallet.charge.failed` wird bei jedem gescheiterten Einzugsversuch ausgelöst, `wallet.charge.overdue` bei ausbleibender Überweisung zum Stichtag und bei der Übergabe an den Mahnprozess.

<Note>
  Der Einzugsplan ist ein eigenes Feature und setzt zusätzlich das Feature Wallet-Aufladung voraus. Wenn du den Einzugsplan nutzen möchtest, wende dich an den Fynn-Support, damit beide Features für deine Organisation aktiviert werden.
</Note>


# Abonnement aktivieren
Source: https://docs.fynn.eu/guide/subscriptions/activate

Aktiviere Abonnements und wähle einzelne Positionen zur Aktivierung aus

Nach dem Erstellen befindet sich ein Abonnement im Status **Entwurf**. Um die Abrechnung zu starten, muss das Abonnement aktiviert werden.

## Aktivierung starten

Öffne das Abonnement und klicke auf den Button **Aktivieren** in der oberen Aktionsleiste.

Es öffnet sich der Aktivierungsdialog mit folgenden Optionen:

### Alle Produkte aktivieren

Standardmäßig ist die Option **Alle Produkte aktivieren** eingeschaltet. In diesem Fall werden alle Positionen des Abonnements gleichzeitig aktiviert.

<Tip>
  Wenn du nur bestimmte Positionen aktivieren möchtest, deaktiviere die Option **Alle Produkte aktivieren**. Es erscheint eine Produktauswahl, in der du gezielt einzelne Positionen auswählen kannst.
</Tip>

### Positionen auswählen

Wenn die Option **Alle Produkte aktivieren** deaktiviert ist, wird eine Produktliste angezeigt. Jede Position zeigt folgende Informationen:

* **Produktname** und Beschreibung
* **Status-Badge** (Entwurf, Aktiv, etc.)
* **Preismodell** (z.B. Pauschal, Staffelung)
* **Abrechnungsstart** — ab wann die Position abgerechnet wird

<Info>
  Wenn ein Abonnement Produkte in mehreren Phasen enthält (unterschiedliche Startdaten), werden die Positionen nach Phase gruppiert.
</Info>

#### Suche und Auswahl

* Nutze die **Suchleiste**, um Positionen nach Name oder Beschreibung zu filtern (erscheint ab 6 Positionen)
* Klicke auf **Alle auswählen**, um alle Positionen auf einmal zu markieren
* Unterprodukte werden automatisch mit dem übergeordneten Produkt ausgewählt

### Abrechnungsstart anpassen

Standardmäßig beginnt die Abrechnung zum hinterlegten Vertragsstartdatum jeder Position.

Wenn du den Abrechnungsstart manuell überschreiben möchtest, aktiviere die Option **Abrechnungsstart anpassen**. Es erscheint ein Datumsfeld, in dem du das gewünschte Startdatum auswählen kannst.

<Tip>
  Wenn du den Abrechnungsstart anpasst, wird in der Produktliste das ursprüngliche Datum durchgestrichen und das neue Datum farblich hervorgehoben angezeigt. So siehst du auf einen Blick, welche Änderung vorgenommen wird.
</Tip>

### Vertragsstart anpassen

Zusätzlich zum Abrechnungsstart kann beim Aktivieren auch das **Vertragsstartdatum** überschrieben werden.

<Info>
  Solange das Abonnement noch im Entwurf ist, wird das angepasste Vertragsstartdatum sowohl auf das Abonnement selbst als auch auf die ausgewählten Positionen (`itemIds`) angewendet. Sobald das Abonnement aktiv ist, betrifft die Änderung ausschließlich die ausgewählten Positionen.
</Info>

## Aktivierung bestätigen

Klicke auf **Abonnement aktivieren**, um die Aktivierung durchzuführen. Das Abonnement wechselt in den Status **Aktiv** und die Abrechnung beginnt zum festgelegten Datum.

<Warning>
  Die Aktivierung kann nicht rückgängig gemacht werden. Stelle sicher, dass die richtigen Positionen und das korrekte Abrechnungsstartdatum ausgewählt sind, bevor du bestätigst.
</Warning>

## Produkte nachträglich aktivieren

Wenn ein aktives Abonnement neue Positionen im Status **Entwurf** enthält (z.B. nach dem Hinzufügen neuer Produkte), kann der Aktivierungsdialog erneut geöffnet werden, um diese Positionen einzeln zu aktivieren. In diesem Fall wird die Option **Alle Produkte aktivieren** nicht angezeigt.

<Info>
  Die Aktivierung kann beliebig oft ausgeführt werden, solange das Abonnement noch Positionen im Status **Entwurf** enthält. So lassen sich Positionen schrittweise in mehreren Durchgängen aktivieren.
</Info>


# Abrechnungsgruppen
Source: https://docs.fynn.eu/guide/subscriptions/billing-groups

Fasse mehrere Abonnements zu einer gemeinsamen Rechnung zusammen

Abrechnungsgruppen ermöglichen es, mehrere Abonnements zu einer Gruppe zusammenzufassen. Somit werden die Abonnements gemeinsam abgerechnet und auf einer Rechnung zusammengefasst.

## Abrechnungsgruppe erstellen

<Steps>
  <Step title="Abrechnungsgruppen Formular öffnen">
    Klicke hierzu im Abrechnungsgruppen-Dropdown auf "Abrechnungsgruppe erstellen".
  </Step>

  <Step title="Abrechnungsgruppe konfigurieren">
    Vergebe einen eindeutigen Namen für die Abrechnungsgruppe. Diese wird nur intern verwendet und ist für Kunden nicht sichtbar.

    Wähle unter dem Punkt "Zeitpunkt" aus:

    * **Monatsanfang**: Die Abrechnung aller Abonnements erfolgt immer zum Monatsanfang.
    * **Monatsende**: Die Abrechnung aller Abonnements erfolgt immer zum Monatsende.
    * **Jahresanfang**: Die Abrechnung aller Abonnements erfolgt immer zum Jahresanfang.
    * **Jahresende**: Die Abrechnung aller Abonnements erfolgt immer zum Jahresende.
    * **Benutzerdefiniert**: Die Abrechnung aller Abonnements erfolgt an einem bestimmten Tag im Monat.

    <Frame>
      <img alt="Abrechnungsgruppe konfigurieren" />
    </Frame>
  </Step>

  <Step title="Abrechnungsgruppe erstellen">
    Klicke nun auf "Abrechnungsgruppe hinzufügen", um die Abrechnungsgruppe zu erstellen.
  </Step>
</Steps>

## Abonnement zu Abrechnungsgruppe hinzufügen

Beim [Erstellen eines Abonnements](/guide/subscriptions/create) kannst du unter den erweiterten Abrechnungsdetails eine Abrechnungsgruppe auswählen. Alle Abonnements in derselben Abrechnungsgruppe werden gemeinsam abgerechnet.

<Tip>
  Abrechnungsgruppen sind kundenspezifisch. Du kannst für jeden Kunden separate Abrechnungsgruppen erstellen.
</Tip>


# Abonnement kündigen
Source: https://docs.fynn.eu/guide/subscriptions/cancel

Kündige Abonnements und verwalte Kündigungsfristen

<Tabs>
  <Tab title="Web-App">
    Abonnements können jederzeit gekündigt werden. Die Kündigung eines Abonnements führt dazu, dass das Abonnement zum Ende des Kündigungsdatums beendet wird. Bis zu diesem Zeitpunkt können Kunden den Service weiterhin nutzen und werden entsprechend abgerechnet.

    Der Kündigungsdialog führt dich in drei Schritten durch die Kündigung. Dabei kannst du auch direkt entscheiden, was mit bereits gestellten Rechnungen passieren soll.

    <Steps>
      <Step title="Abonnement öffnen">
        Gehe zu [Abonnements](https://app.fynn.eu/subscriptions) und öffne das gewünschte Abonnement.
      </Step>

      <Step title="Positionen und Kündigungszeitpunkt wählen">
        Klicke im Menü oben rechts auf `Kündigen`. Wähle aus, ob das gesamte Abonnement oder nur einzelne Positionen gekündigt werden sollen, und lege den Kündigungszeitpunkt fest.

        <Frame>
          <img alt="Abonnement kündigen Dialog" />
        </Frame>

        **Optionen für den Kündigungszeitpunkt:**

        * **Sofort**: Das Abonnement wird sofort gekündigt und der Service wird mit sofortiger Wirkung beendet. Hierbei werden die Kündigungsfristen und Laufzeiten ignoriert.
        * **Zum Vertragsende**: Wähle eines der angezeigten Vertragsenden aus. Fynn berechnet die möglichen Termine auf Basis der Kündigungsfristen und Laufzeiten. Auch ein späteres als das nächstmögliche Vertragsende ist wählbar.
        * **Zum angegebenen Datum**: Das Abonnement wird zum angegebenen Datum außerordentlich gekündigt. Hierbei werden die Kündigungsfristen und Laufzeiten ignoriert.

        Optional kannst du einen Kündigungsgrund auswählen, wenn du in den Einstellungen Kündigungsgründe hinterlegt hast.
      </Step>

      <Step title="Belege korrigieren">
        Im zweiten Schritt siehst du die Rechnungen, die zu den gekündigten Positionen gehören. Für jede Rechnung entscheidest du, ob sie korrigiert werden soll: die gesamte Rechnung oder nur einzelne Positionen.

        Was aus der Korrektur wird, entscheidet Fynn anhand des Zahlungsstands:

        * **Offene Beträge** werden per Stornorechnung mit dem offenen Betrag verrechnet.
        * **Bereits gezahlte Beträge** werden dem Kundenkonto als Guthaben gutgeschrieben und automatisch mit zukünftigen Rechnungen verrechnet.
      </Step>

      <Step title="Kündigung bestätigen">
        Überprüfe die Zusammenfassung und bestätige die Kündigung.

        <Tip>
          Standardmäßig wird eine Kündigungsbestätigung an den Kunden gesendet. Dies kann über die Checkbox "Kündigungsbestätigung als PDF senden" deaktiviert werden. Auch der E-Mail-Versand für Storno- und Gutschriftbelege lässt sich hier steuern.
        </Tip>

        <Frame>
          <img alt="Kündigung Vorschau" />
        </Frame>

        <Note>
          Kündigung und Beleg-Anpassungen werden zusammen in einem Schritt ausgeführt. Schlägt ein Teil fehl, wird nichts davon durchgeführt. Es entstehen also keine halb ausgeführten Kündigungen.
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Abonnement kündigen](/api-reference/subscription/cancel-subscription) Endpunkt.

    ```bash theme={null}
    PUT /subscriptions/{id}/cancel
    ```

    Alternativ steht in der v2 Platform API ein Endpunkt zur Verfügung, der die Kündigung und die zugehörigen Beleg-Korrekturen atomar in einem Aufruf ausführt:

    ```bash theme={null}
    POST /api/subscriptions/{id}/cancel
    ```

    Der Request akzeptiert neben den Kündigungsparametern ein Array `invoiceCorrections`. Jeder Eintrag enthält die `invoiceId` und die zu korrigierenden Positionen (Format wie bei `POST /api/invoices/{id}/correct`). Offene Beträge werden verrechnet, bereits gezahlte Beträge landen immer als Guthaben im Kundenkonto. Schlägt ein Teil fehl, wird die gesamte Operation zurückgerollt.
  </Tab>
</Tabs>

## Kündigung widerrufen

<Tabs>
  <Tab title="Web-App">
    Die Kündigung eines Abonnements kann solange widerrufen werden, bis der Kündigungszeitpunkt erreicht ist. Bei Widerruf der Kündigung wird das Abonnement fortgesetzt und der Service wird wie gewohnt abgerechnet.

    <Steps>
      <Step title="Abonnement öffnen">
        Gehe zu [Abonnements](https://app.fynn.eu/subscriptions) und öffne das gewünschte Abonnement.
      </Step>

      <Step title="Kündigung widerrufen">
        Klicke im Menü oben Rechts auf `Kündigung widerrufen`.
      </Step>

      <Step title="Widerruf bestätigen">
        <Info>
          Bei Widerruf wird der Kunde nicht benachrichtigt. Der Widerruf der Kündigung erfolgt sofort und das Abonnement wird fortgesetzt.
        </Info>

        Klicke auf `Kündigung widerrufen`, um die Kündigung zu widerrufen. Anschließend wird die Kündigung widerrufen und das Abonnement fortgesetzt.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den Kündigung widerrufen Endpunkt.

    ```bash theme={null}
    PUT /subscriptions/{id}/revoke-cancellation
    ```
  </Tab>
</Tabs>

## Kündigung während Testphase

Abonnements die sich in einer Testphase befinden, können jederzeit gekündigt werden. Die Kündigung einer Testphase führt dazu, dass das Abonnement sofort beendet wird.

Um eine Testphase zu kündigen, wähle die Option `Sofort` aus und bestätige die Kündigung. Anschließend wird die Testphase beendet und das Abonnement wird sofort gekündigt.

## Kündigung während Testphase durch Kunden

Kunden haben die Möglichkeit, eine Testphase jederzeit im Kundenbereich zu kündigen.

Weitere Details erfährst du unter [Testphasen](/guide/subscriptions/trials).


# Abonnement erstellen
Source: https://docs.fynn.eu/guide/subscriptions/create

Erstelle neue Abonnements für deine Kunden

<Tabs>
  <Tab title="Web-App">
    In Fynn können Abonnements über die Web-App erstellt werden. Hierbei können verschiedene Optionen und Einstellungen für das Abonnement festgelegt werden.

    <Steps>
      <Step title="Abonnement erstellen">
        Klicke hierzu auf das "+" Symbol in der oberen rechten Ecke und wähle `Abonnement` aus.

        <Frame>
          <img alt="Abonnement erstellen" />
        </Frame>
      </Step>

      <Step title="Abonnement konfigurieren">
        Konfiguriere das Abonnement mit den gewünschten Einstellungen und Optionen. Hierbei können verschiedene Einstellungen und Optionen festgelegt werden, wie z.B.:

        * **Kunden**: Wähle den Kunden aus, dem das Abonnement zugeordnet werden soll.
        * **Produkte**: Wähle die Produkte aus, die im Abonnement enthalten sein sollen.
        * **Abrechnungszeitpunkt**: Wähle den Abrechnungszeitpunkt aus, zu dem das Abonnement abgerechnet werden soll.
        * **Laufzeit**: Wähle die Laufzeit des Abonnements aus.
      </Step>

      <Step title="Produkte hinzufügen">
        Klicke auf `Produkt hinzufügen`, um die gewünschten Produkte auszuwählen, die im Abonnement enthalten sein sollen.
        Wähle aus der Liste die gewünschten Produkte aus und klicke auf `Hinzufügen`, um die Produkte dem Abonnement hinzuzufügen.

        <Frame>
          <img alt="Produkte hinzufügen" />
        </Frame>

        Sofern ein Produkt mehrere Preise enthält, kannst du hier die gewünschten Preise auswählen, die im Abonnement enthalten sein sollen.

        <Frame>
          <img alt="Produkt-Preise konfigurieren" />
        </Frame>

        Anschließend werden die Produkte dem Abonnement hinzugefügt und du kannst die Mengen und weitere Einstellungen für die Produkte festlegen.

        <Frame>
          <img alt="Produkte hinzugefügt" />
        </Frame>
      </Step>

      <Step title="Abrechnungsdetails anpassen">
        Passe die Abrechnungsdetails an:

        * **Vertragsstart**: Der Vertragsstart ist relevant zur Berechnung von Kündigungsfristen und nächstmögliche Kündigungszeitpunkte, in Zusammenhang mit den Laufzeiten des Abonnements.
        * **Abrechnungsbeginn**: Der Abrechnungsbeginn ist der Zeitpunkt, zu dem das Abonnement abgerechnet wird. Standardmäßig entspricht dies dem Vertragsstart. Wird das Abonnement jedoch bspw. aus einem Bestandsystem migriert, ist hier der Zeitpunkt anzugeben, zu dem das Abonnement das nächste Mal abgerechnet werden soll. Ab diesem Zeitpunkt wird das Abrechnungsinterval festgelegt.
        * **Vertragsende**: Ist bereits zu Beginn des Abonnements bekannt, wann das Abonnement enden soll, kann hier das Vertragsende angegeben werden. Andernfalls kann ein Abonnement zukünftig manuell gekündigt werden.

        <Frame>
          <img alt="Abrechnungsdetails anpassen" />
        </Frame>
      </Step>

      <Step title="Erweiterte Abrechnungsdetails anpassen">
        Passe die erweiterten Abrechnungsdetails an:

        * **Bestellnummer/ PO-Nummer**: Gebe hier die Bestellnummer oder PO-Nummer an, die dem Abonnement zugeordnet werden soll. Die PO-Nummer wird immer auf der Rechnung angezeigt.
        * **Abrechnungsgruppe**: Mit Hilfe der Abrechnungsgruppe kannst du mehrere Abonnements zu einer Gruppe zusammenfassen. Somit werden die Abonnements gemeinsam abgerechnet und auf einer Rechnung zusammengefasst. Weitere Details findest du unter [Abrechnungsgruppen](/guide/subscriptions/billing-groups).
        * **Abonnementnummer**: Standardmäßig wird die Abonnementnummer automatisch generiert. Du kannst hier jedoch eine eigene Abonnementnummer angeben.
        * **Individueller Name**: Gebe hier einen individuellen Namen für das Abonnement an. Dieser Name wird auf der Rechnung und in der Abonnementübersicht angezeigt. Standardmäßig wird die Abonnementnummer als Name verwendet.
        * **Externe ID**: Gebe hier eine externe ID an, die dem Abonnement zugeordnet werden soll. Diese ID wird in der API und im Webhook verwendet, um das Abonnement zu identifizieren.

        <Frame>
          <img alt="Erweiterte Abrechnungsdetails anpassen" />
        </Frame>
      </Step>

      <Step title="Laufzeiten anpassen">
        Passe die Laufzeiten des Abonnements an. Du kannst beliebig viele Laufzeiten hinzufügen und die Kündigungsfristen anpassen.

        * **Vertragslaufzeit**: Wähle die Vertragslaufzeit des Abonnements aus. Standardmäßig wird die Vertragslaufzeit auf 1 Jahr festgelegt.
        * **Kündigungsfrist**: Wähle die Kündigungsfrist des Abonnements aus. Standardmäßig wird die Kündigungsfrist auf 14 Tage festgelegt.

        Diese Fristen können individuell für jedes Abonnement angepasst werden und sind releveant für die Berechnung des nächstmöglichen Kündigungszeitpunktes.

        <Frame>
          <img alt="Laufzeiten anpassen" />
        </Frame>
      </Step>

      <Step title="Abonnement erstellen">
        Überprüfe das Abonnement und klicke auf `Abonnement starten`, um das Abonnement zu erstellen. Anschließend wird das Abonnement erstellt und abgerechnet.

        Alternativ kannst du:

        * das Abonnement auch als Entwurf speichern und zu einem späteren Zeitpunkt erstellen
        * eine Testphase aktivieren
        * ein Angebot für das Abonnement erstellen
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Abonnement erstellen](/api-reference/subscription/create-subscription) Endpunkt.

    ```bash theme={null}
    POST /subscriptions
    ```
  </Tab>
</Tabs>

## Abrechnungsstart anpassen

Der Abrechnungsstart ist der Zeitpunkt, zu dem das Abonnement erstmalig abgerechnet wird. Standardmäßig entspricht der Abrechnungsstart dem Vertragsstart. Wird das Abonnement jedoch bspw. aus einem Bestandsystem migriert, ist hier der Zeitpunkt anzugeben, zu dem das Abonnement das nächste Mal abgerechnet werden soll. Ab diesem Zeitpunkt beginnt das Abrechnungsinterval.

Wird der Abrechnungsstart in die Vergangenheit gesetzt, wird das Abonnement rückwirkend abgerechnet.

<Tip>
  Die Abrechnung aller vegangenen Abrechnungszyklen erfolgt sofort und innerhalb einer Rechnung. Anschließend wird das Abonnement zum nächsten Abrechnungszeitpunkt abgerechnet.
</Tip>


# Abonnements
Source: https://docs.fynn.eu/guide/subscriptions/introduction

Erstelle und verwalte deine Abonnements

Abonnements sind das Herzstück der wiederkehrenden Abrechnung in Fynn. Mit Abonnements kannst du flexible Abrechnungsmodelle für deine Kunden erstellen und verwalten.

<CardGroup>
  <Card title="Abonnement erstellen" icon="plus" href="/guide/subscriptions/create">
    Erstelle neue Abonnements mit Produkten, Preisen und individuellen Laufzeiten.
  </Card>

  <Card title="Abonnement aktivieren" icon="bolt" href="/guide/subscriptions/activate">
    Aktiviere Abonnements und wähle Positionen und Abrechnungsstart aus.
  </Card>

  <Card title="Abonnement kündigen" icon="xmark" href="/guide/subscriptions/cancel">
    Kündige Abonnements und verwalte Kündigungsfristen.
  </Card>

  <Card title="Abonnement pausieren" icon="pause" href="/guide/subscriptions/pause">
    Pausiere Abonnements vorübergehend und setze sie fort.
  </Card>

  <Card title="Abrechnungsgruppen" icon="layer-group" href="/guide/subscriptions/billing-groups">
    Fasse mehrere Abonnements zu einer gemeinsamen Rechnung zusammen.
  </Card>
</CardGroup>

## Status-Übersicht

Jedes Abonnement durchläuft einen definierten Lebenszyklus. Der aktuelle Status bestimmt, ob und wie ein Abonnement abgerechnet wird.

| Status       | Bedeutung                                                                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `draft`      | Entwurf: Das Abonnement ist noch nicht aktiv und wird nicht abgerechnet.                                                                                 |
| `active`     | Aktiv: Das Abonnement wird regulär abgerechnet.                                                                                                          |
| `paused`     | Pausiert: Die Abrechnung ist vorübergehend ausgesetzt.                                                                                                   |
| `cancelled`  | Gekündigt: Die Kündigung wurde eingeleitet. Die Abrechnung läuft bis zum Kündigungsdatum weiter, danach wechselt der Status automatisch zu `terminated`. |
| `terminated` | Beendet: Endgültig beendet, keine weitere Abrechnung. Wird automatisch gesetzt, wenn das Kündigungsdatum oder Vertragsende erreicht ist.                 |
| `voided`     | Storniert: Das Abonnement wird aus allen Statistiken entfernt. Dies ist der stärkste "Lösch"-Status.                                                     |

### Cancelled vs. Terminated

Diese beiden Status werden häufig verwechselt, unterscheiden sich aber grundlegend:

**Cancelled** bedeutet, dass eine Kündigung eingeleitet wurde. Das Abonnement wird bis zum Kündigungsdatum weiter abgerechnet.

* Wird über die API via `PUT /subscriptions/{id}/cancel` ausgelöst
* Solange das Kündigungsdatum in der Zukunft liegt, kann die Kündigung widerrufen werden (siehe [Kündigung widerrufen](/guide/subscriptions/cancel#kündigung-widerrufen))
* Nach Erreichen des Kündigungsdatums wechselt der Status automatisch zu `terminated`

**Terminated** bedeutet, dass das Abonnement endgültig beendet ist. Es erfolgt keine weitere Abrechnung.

* Wird automatisch vom System gesetzt, wenn das Kündigungsdatum oder Vertragsende erreicht ist
* Kann nicht rückgängig gemacht werden

### Kündigungsdatum

Bei der Kündigung wird ein Kündigungsdatum festgelegt. Bis zu diesem Datum läuft die Abrechnung weiter. Es gibt drei Optionen:

| Typ             | Bedeutung                              |
| --------------- | -------------------------------------- |
| `immediate`     | Sofort wirksam                         |
| `next_possible` | Zum Ende der laufenden Vertragsperiode |
| `custom`        | Zu einem frei gewählten Datum          |

Der Ablauf nach einer Kündigung:

1. Die Kündigung wird erfasst, der Status wechselt zu `cancelled` und das Kündigungsdatum wird gesetzt
2. Die Abrechnung läuft bis zum Kündigungsdatum weiter
3. Nach Erreichen des Kündigungsdatums wird der Status automatisch auf `terminated` gesetzt

<Info>
  Wenn du per API prüfen möchtest, ob ein Kunde aktiv gekündigt hat, ist `cancelled` der relevante Status. `terminated` zeigt lediglich an, dass das Abonnement endgültig beendet ist.
</Info>

## Total Contract Value (TCV)

Der Total Contract Value (TCV) ist der Gesamtwert eines Abonnements über die gesamte Erst-Vertragslaufzeit. Der TCV ist ein wichtiger Indikator für den Wert eines Abonnements und wird häufig zur Bewertung von Abonnements verwendet.

Der TCV wird berechnet, indem der wiederkehrende Umsatz eines Abonnements über die gesamte Erst-Vertragslaufzeit summiert wird. Zudem werden Einmal-Zahlungen und Rabatte berücksichtigt.

Beispiel:

Ein Abonnement hat einen monatlichen Preis von 100€ und eine Vertragslaufzeit von 12 Monaten. Der TCV beträgt somit 1.200€.
Wenn das Abonnement einen Rabatt von 10% auf die ersten 3 Monate erhält, beträgt der TCV 1.080€.
Wird innerhalb der 1. Vertragslaufzeit ein Einmal-Zahlung von 100€ hinzugefügt (bspw. durch Consulting) beträgt der TCV 1.180€.

Wird anschleßend innerhalb der 1. Vertragslaufzeit ein Upgrade auf ein höherwertiges Abonnement durchgeführt, wird der TCV entsprechend angepasst.

<Info>
  Sind in einem Abonnement mehrere Währungen enthalten, wird der TCV in der Standard-Währung des Tenants nach dem aktuell gültigen EZB-Wechselkurs berechnet.
</Info>


# Abonnement pausieren
Source: https://docs.fynn.eu/guide/subscriptions/pause

Pausiere Abonnements vorübergehend und setze sie fort

<Tabs>
  <Tab title="Web-App">
    In Fynn können Abonnements pausiert werden, wodurch die Abrechnung vorübergehend gestoppt wird.

    Das Pausieren von Abonnements ermöglicht es Kunden, vorübergehend Kosten zu sparen, wenn sie den Service nicht nutzen. Es ist auch eine gute Möglichkeit, Kunden zu behalten, die den Service vorübergehend nicht mehr benötigen, aber nicht kündigen möchten.
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Abonnement pausieren](/api-reference/subscription/pause-subscription) Endpunkt.

    ```bash theme={null}
    PUT /subscriptions/{id}/pause
    ```
  </Tab>
</Tabs>

## Abonnement fortsetzen

<Tabs>
  <Tab title="Web-App">
    Abonnements können jederzeit fortgesetzt werden. Bei der Reaktivierung des Abonnements hast du die Möglichkeit, anzugeben, ob alle fälligen Abrechnungszyklen seit der Pausierung abgerechnet werden sollen oder ob diese ignoriert werden sollen und ein neuer Abrechnungszeitpunkt ausgewählt werden soll.

    <Steps>
      <Step title="Abonnement öffnen">
        Gehe zu [Abonnements](https://app.fynn.eu/subscriptions) und öffne das gewünschte Abonnement.
      </Step>

      <Step title="Abonnement fortsetzen">
        Klicke im Menü oben Rechts auf `Fortsetzen` und wähle die gewünschte Option aus.

        <Frame>
          <img alt="Abonnement fortsetzen" />
        </Frame>

        **Optionen:**

        * **Abrechnung fortsetzen** - Alle ausstehenden Abrechnungszyklen seit der Pausierung werden sofort abgerechnet, und der Abrechnungszeitpunkt erfolgt wie gewohnt.
        * **Bisherige Abrechnungen ignorieren** - Die ausstehenden Abrechnungszyklen seit der Pausierung werden ignoriert, und der Abrechnungszeitpunkt wird entsprechend des "Neues Startdatum" festgelegt.

        Ein Beispiel für beide Optionen findest du weiter unten.
      </Step>

      <Step title="Bestätigen">
        Klicke auf `Abrechnung fortsetzen`, um die Reaktivierung abzuschließen. Anschließend wird das Abonnement fortgesetzt und die Abrechnung entsprechend durchgeführt.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Abonnement fortsetzen](/api-reference/subscription/resume-subscription) Endpunkt.

    ```bash theme={null}
    PUT /subscriptions/{id}/resume
    ```
  </Tab>
</Tabs>

## Beispiel

| Zeitpunkt                                         | Beschreibung                                                                                                                                                                                                                                     |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Abrechnungszyklus 1                               | 01.01.2023 - 31.01.2023                                                                                                                                                                                                                          |
| Abrechnungszyklus 2                               | 01.02.2023 - 28.02.2023                                                                                                                                                                                                                          |
| Abrechnungszyklus 2                               | 01.03.2023 - 31.03.2023                                                                                                                                                                                                                          |
| Pausierung                                        | Das Abonnement wird pausiert am 15.01.2023, nachdem der erste Abrechnungszyklus vollständig abgeschlossen wurde.                                                                                                                                 |
| Reaktivierung                                     | Das Abonnement wird am 15.04.2023 fortgesetzt.                                                                                                                                                                                                   |
| Reaktivierung - Abrechung fortsetzen              | Es werden 2 Abrechnungszyklen abgerechnet: 01.02.2023 - 28.02.2023 und 01.03.2023 - 31.03.2023. Der nächste Abrechnungszeitpunkt wird auf den 01.04.2023 festgelegt.                                                                             |
| Reaktivierung - Bisherige Abrechnungen ignorieren | Der neue Abrechnungszeitpunkt wird auf den 01.04.2023 festgelegt. Damit werden die ausstehenden Abrechnungszyklen seit der Pausierung ignoriert und die Abrechnung beginnt mit dem Zyklus 01.04.2023 - 30.04.2023, 01.05.2023 - 31.05.2023, usw. |


# Abrechnung zurücksetzen
Source: https://docs.fynn.eu/guide/subscriptions/reset-billing

Setze die Abrechnung ausgewählter Abo-Positionen auf ein neues Startdatum zurück

Wurde ein Abonnement mit falscher Konfiguration oder zum falschen Zeitpunkt abgerechnet, kannst du die Rechnung stornieren und die Abrechnung der betroffenen Positionen anschließend auf ein Datum deiner Wahl zurücksetzen. Ab diesem Tag werden die Positionen wieder ganz normal abgerechnet.

## Voraussetzungen

* Die Position ist **nicht beendet**. Alle anderen Positionen kannst du zurücksetzen.
* Die Position ist **nicht verbrauchsbasiert**. Positionen mit gemessenem Verbrauch können nicht zurückgesetzt werden.
* Alle Rechnungen, die einen Zeitraum ab dem gewählten Datum abdecken, sind **vollständig storniert**. Solange eine dieser Rechnungen noch offen ist, wird der Reset mit einer Fehlermeldung abgelehnt.

<Warning>
  Der Reset ist eine reine Zustandsänderung: Er erstellt keine Gutschrift, storniert keine Belege und bewegt kein Geld. Belege stornierst oder gutschreibst du manuell in einem eigenen Schritt.
</Warning>

## Abrechnung zurücksetzen

1. Öffne das Abonnement und wähle im Aktionsmenü **Abrechnung zurücksetzen**.
2. Wähle das Datum, ab dem wieder abgerechnet werden soll.
3. Wähle die Positionen aus, die zurückgesetzt werden sollen.
4. Bestätige mit **Abrechnung zurücksetzen**.

Die ausgewählten Positionen gelten danach als bis zum gewählten Datum nicht abgerechnet. Der nächste Rechnungslauf erstellt eine neue Rechnung, deren Leistungszeitraum am gewählten Datum beginnt.

## Was passiert beim Reset?

* Der Abrechnungszustand der ausgewählten Positionen wird auf das gewählte Datum gesetzt. Das Datum wird in der Zeitzone deiner Organisation interpretiert.
* Der alte Rechnungslauf der stornierten Rechnung blockiert die erneute Abrechnung nicht mehr, bleibt aber zur Nachvollziehbarkeit erhalten.
* Wenn eine Position noch keine gültige Abrechnungshistorie hat, wird auch die Umsatzerkennung (MRR) der Position auf das neue Datum verschoben. Bereits gültig abgerechnete Zeiträume bleiben unverändert.
* Der Reset wird als Aktivität am Abonnement protokolliert.

<Tip>
  Typischer Ablauf aus der Praxis: Ein Abonnement wurde versehentlich zu früh abgerechnet. Storniere die Rechnung, setze die Abrechnung der Positionen auf den gewünschten Starttermin zurück und der nächste Rechnungslauf erstellt automatisch die korrekte Rechnung.
</Tip>


# Abonnement-Übergänge
Source: https://docs.fynn.eu/guide/subscriptions/transitions

Wechsle Produkte und Preispläne in einem Abonnement mit automatischer Proration und Gutschriften.

Mit Abonnement-Übergängen kannst du die Produkte und Preispläne eines bestehenden Abonnements ändern - z.B. für Upgrades, Downgrades oder Produktwechsel. Die Änderungen werden sauber verarbeitet mit automatischer Berechnung von Gutschriften und anteiliger Abrechnung.

<Warning>
  Gekündigte Abonnements können nicht mehr transitioniert werden. Der Übergangszeitpunkt muss in der Zukunft oder jetzt sein.
</Warning>

## Anwendungsfälle

| Szenario           | Beschreibung                                                |
| ------------------ | ----------------------------------------------------------- |
| **Upgrade**        | Kunde wechselt von Basic auf Pro Plan                       |
| **Downgrade**      | Kunde wechselt auf einen günstigeren Plan                   |
| **Produktwechsel** | Wechsel von einem Produkt zu einem anderen                  |
| **Planänderung**   | Gleiche Produkte, aber andere Preispläne                    |
| **Migration**      | Umstellung von nutzungsbasiert auf Festpreis oder umgekehrt |

***

## So funktioniert es

Ein Übergang führt folgende Schritte aus:

1. **Alte Items beenden** - Bestehende Abonnement-Items werden zum Übergangszeitpunkt beendet
2. **Gutschriften erstellen** - Optional werden Gutschriften für nicht genutzte Zeit erstellt
3. **Neue Items anlegen** - Die gewünschten Produkte werden als neue Items hinzugefügt
4. **Phase wechseln** - Eine neue Abonnement-Phase beginnt

***

## Proration (Gutschriften)

Bei der Beendigung von Festpreis-Produkten kannst du wählen, wie Gutschriften berechnet werden:

| Option                          | Beschreibung                                 |
| ------------------------------- | -------------------------------------------- |
| **Anteilig** (`creditProrated`) | Gutschrift basierend auf verbleibenden Tagen |
| **Keine** (`none`)              | Keine Gutschrift                             |

<Tip>
  Die Gutschrift wird sofort finalisiert und an den Kunden gesendet. Der Guthabenbetrag wird automatisch mit der nächsten Rechnung verrechnet.
</Tip>

<Note>
  Bei nutzungsbasierten Produkten werden **keine Gutschriften** erstellt, da diese im Nachhinein abgerechnet werden. Stattdessen wird die Nutzung bis zum Übergangszeitpunkt mit dem alten Preisplan abgerechnet.
</Note>

***

## Abrechnungszeitpunkt

Du kannst festlegen, wann die neuen Items abgerechnet werden:

| Option                         | Beschreibung                                                                                                                              |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Phasenstart** (`phaseStart`) | Rechnung wird zum Übergangszeitpunkt erstellt. Teilperioden von nutzungsbasierten Items werden ebenfalls zu diesem Zeitpunkt abgerechnet. |
| **Sofort** (`immediately`)     | Rechnung wird sofort erstellt. Teilperioden von nutzungsbasierten Items werden ebenfalls sofort abgerechnet.                              |

***

## Nutzungsbasierte Produkte

Bei nutzungsbasierten Produkten gibt es besondere Regeln:

### Keine Gutschriften

Nutzungsbasierte Produkte werden **nie** gutgeschrieben, da sie im Nachhinein abgerechnet werden. Die Proration-Einstellung wird ignoriert.

### Teilperioden-Abrechnung

Wenn ein nutzungsbasiertes Item beendet wird, erstellt das System automatisch Abrechnungsposten für die Teilperiode:

* **Zeitraum**: Letzte Abrechnung → Übergangszeitpunkt
* **Preis**: Alter Preisplan
* **Inklusiveinheiten**: Werden anteilig berechnet

**Beispiel:**

* Letzter Abrechnungszeitpunkt: 1. Februar
* Übergangszeitpunkt: 15. Februar
* Die Nutzung vom 1.-15. Februar wird mit dem alten Preisplan abgerechnet
* Ab 15. Februar gilt der neue Preisplan

### Wechsel zwischen Produkttypen

| Von             | Nach            | Gutschrift    | Teilperiode |
| --------------- | --------------- | ------------- | ----------- |
| Festpreis       | Festpreis       | Ja (optional) | Nein        |
| Festpreis       | Nutzungsbasiert | Ja (optional) | Nein        |
| Nutzungsbasiert | Festpreis       | Nein          | Ja          |
| Nutzungsbasiert | Nutzungsbasiert | Nein          | Ja          |

***

## API

Für Übergänge steht folgender API-Endpoint zur Verfügung:

| Method | Endpoint                             | Beschreibung         |
| ------ | ------------------------------------ | -------------------- |
| POST   | `/api/subscriptions/[id]/transition` | Übergang durchführen |

<Card title="API Referenz" icon="code" href="/api-reference/subscription/transition">
  Vollständige API-Dokumentation mit Request/Response-Strukturen und Beispielen
</Card>

***

## Verwandte Dokumentation

<CardGroup>
  <Card title="Abonnements verwalten" icon="repeat" href="/guide/subscriptions/introduction">
    Grundlagen zu Abonnements
  </Card>

  <Card title="Nutzungsmetriken" icon="chart-line" href="/guide/catalogue/measurements/billable-metrics">
    Nutzungsbasierte Abrechnung konfigurieren
  </Card>
</CardGroup>


# Aktivitätsprotokoll
Source: https://docs.fynn.eu/guide/tenant/activities

Verfolge Aktivitäten und hinterlasse Kommentare zu wichtigen Ereignissen.

Der Aktivitäts-Stream bietet eine zentrale Übersicht über alle Änderungen, Ereignisse und Kommentare, die vorgenommen wurden. So behältst du jederzeit den Überblick, wer was wann getan hat.

<Frame>
  <img alt="Aktivitätsprotokoll - Kommentare" />
</Frame>

## Unterstützte Objekte

Folgende Objekte werden im Aktivitäts-Stream unterstützt:

* **Abonnements**: Änderungen an Abonnements, z. B. Statuswechsel, Laufzeitanpassungen.
* **Rechnungen**: Änderungen an Rechnungen, wie Statusänderungen (z. B. bezahlt, storniert).
* **Gutschriften**: Änderungen an Gutschriften, wie Statusänderungen (z. B. bezahlt, storniert).
* **Stornos**: Änderungen an Stornos, wie Statusänderungen (z. B. bezahlt, storniert).
* **Kunden**: Verfolgen von Kundeninformationen wie Name, Adresse, etc.
* **Produkte**: Änderungen an Produkten, z. B. Preise, Details oder Attribute.

<Info>
  Der Aktivitäts-Stream ist erst seit dem 17.Dez 2024 verfügbar, alle Änderungen vor diesem Datum sind nicht im Aktivitäts-Stream verfügbar. Für den vorherigen Zeitraum wurden die Änderungen intern protokolliert.
</Info>

## Kommentare hinterlassen

<Tabs>
  <Tab title="Web-App verwenden">
    Zu jedem unterstützten Objekt kannst du Kommentare hinzufügen, um zusätzliche Informationen oder Anmerkungen zu hinterlassen. Kommentare sind besonders nützlich für:

    * Interne Abstimmungen: Notiere wichtige Details oder kläre Fragen direkt am Objekt.
    * Protokollierung: Hinterlasse eine Erklärung zu Änderungen, wie z. B. warum eine Rechnung storniert wurde.
    * Zusammenarbeit: Kommentiere mit deinem Team direkt im Kontext.

    <Warning>
      Kommentare können aktuell nicht bearbeitet oder gelöscht werden. Wir arbeiten daran, diese Funktion in Zukunft zu ermöglichen.
    </Warning>
  </Tab>

  <Tab title="API verwenden">
    Um Kommentare zu einem Objekt hinzuzufügen, kann einer der folgenden Endpunkte verwendet werden:

    * [Kunde: Kommentar hinzufügen](/api-reference/customer/add-comment)
    * [Abonnement: Kommentar hinzufügen](/api-reference/subscription/add-comment)
    * [Rechnung: Kommentar hinzufügen](/api-reference/invoice/add-comment)
  </Tab>
</Tabs>


# Aussehen & Design
Source: https://docs.fynn.eu/guide/tenant/appearance

Passe das Aussehen und Design des Warenkorbs, Kundenbereich und Dokumenten an.

Passe das Aussehen und Design des Warenkorbs, Kundenbereichs und Dokumente an, um deine Marke optimal zu präsentieren.

## Logo

Dein Logo wird für (PDF)-Dokumente, E-Mails, den Kundenbereich und den Warenkorb verwendet. Wir empfehlen eine transparente PNG- oder SVG-Datei für eine optimale Darstellung.

## Unternehmens-Farbe

Die Unternehmensfarbe wird für (PDF)-Dokumente, E-Mails, den Kundenbereich und den Warenkorb verwendet. Wähle eine Farbe, die deine Marke am besten repräsentiert und einheitlich in allen Bereichen erscheint.

## Akzent-Farbe

Die Akzentfarbe wird für (PDF)-Dokumente, E-Mails, den Kundenbereich und den Warenkorb verwendet. Sie dient dazu, wichtige Elemente hervorzuheben und das Design ansprechender zu gestalten.

## Aussehen anpassen

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Allgemein](https://app.fynn.eu/settings) und scrolle nach unten zu "Aussehen".
  </Step>

  <Step title="Passe das Aussehen an">
    <Frame>
      <img alt="Aussehen anpassen" />
    </Frame>
  </Step>

  <Step title="Klicke auf Speichern" />
</Steps>

## Beleg Vorschau

Die Vorschau von Belegen (Rechnungen, Stornos, Gutschriften) erhaltet man wie folgt:

<Steps>
  <Step title="Öffne die Beleg-Einstellungen">
    Gehe hierzu zu [Einstellungen > Belege](https://app.fynn.eu/settings/invoices) und scrolle nach unten zu "Vorlagen".
  </Step>

  <Step title="Klicke auf Bearbeiten">
    Klicke auf Bearbeiten der "Rechnung" oder "Storno" oder "Gutschrift" Vorlage, und wähle "Deutsch bearbeiten" aus.

    <Frame>
      <img alt="Beleg-Einstellungen" />
    </Frame>
  </Step>

  <Step title="Vorschau ansehen">
    Klicke hierfür auf den Tab "Vorschau" um dir die Vorschau anzusehen.

    <Frame>
      <img alt="Vorschau" />
    </Frame>
  </Step>
</Steps>


# Abrechnung
Source: https://docs.fynn.eu/guide/tenant/billing

Verwalte deine Abrechnung, Rechnungen und Zahlungen.

Passe die Abrechnungseinstellungen an, um die Darstellung und den Ablauf der Rechnungsstellung für deine Kunden zu steuern. Du kannst u.a. entscheiden, ob Rechnungen manuell freigegeben werden müssen, wie Preise angezeigt werden und ob erweiterte Details sichtbar sind.

## Fälligkeit

Lege die Standard-Fälligkeit von Rechnungen in Tagen fest. Diese Einstellung wird für alle Kunden übernommen, sofern sie nicht individuell angepasst wurde.

## Manuelle Freigabe

Aktiviere diese Option, wenn Rechnungen manuell freigegeben werden müssen.

## 0,00 € Belege generieren

Wenn diese Option aktiviert ist, werden auch Belege über 0,00 € generiert. Andernfalls werden sie unterdrückt. Dies kann nützlich sein, um Transparenz zu schaffen oder um sicherzustellen, dass alle Transaktionen dokumentiert sind.

## Abrechnungsdetails

Zeigt eine Verlinkung zu erweiterten Abrechnungs-Details in den Rechnungen an. Diese Funktion erhöht die Transparenz und hilft dem Kunden, die abgerechneten Leistungen besser zu verstehen.

## GiroCode

<Frame>
  <img alt="Fynn GiroCode" />
</Frame>

Der GiroCode ist ein QR-Code, der es deinen Kunden ermöglicht, Rechnungen einfach zu bezahlen. Dieser Code enthält alle notwendigen Zahlungsinformationen und kann mit einer Banking-App gescannt werden.

## Preise

Aktiviere diese Option, um zusätzlich den Preis pro Einheit (z.B. pro Monat oder Stück) anzuzeigen – zusätzlich zum Gesamtpreis.
Beispiel: 10,00 € / Monat / Stück

## Positionsgruppen-Format

Bestimmt, wie die Positionsgruppen auf Rechnungen benannt werden. Das Format unterstützt Abonnement-Variablen sowie Bedingungen.

**Standardformat:**

```
{{ subscription.name }}{% if subscription.poNumber %} - PO Number: {{ subscription.poNumber }}{% endif %}
```

Verfügbare Variablen: `subscription.name`, `subscription.number`, `subscription.poNumber`, `subscription.customFields.<key>`.

Die Eingabe bietet Autovervollständigung für verfügbare Variablen und zeigt eine Live-Vorschau des formatierten Gruppennamens an. Weitere Details und Beispiele findest du unter [Belegvorlagen](/guide/invoices/document-templates).

## Kundenguthaben (Wallet)

Steuere, wie Fynn mit Überzahlungen und vorhandenem Kundenguthaben umgeht.

### Überzahlungen als Guthaben verbuchen

Wenn diese Option aktiviert ist, wird der überschüssige Betrag bei einer Überzahlung automatisch dem Kundenguthaben gutgeschrieben. Der offene Rechnungsbetrag wird dabei automatisch auf null gesetzt, und das Guthaben steht für zukünftige Rechnungen zur Verfügung.

Ist die Option deaktiviert, bleibt eine Überzahlung als Differenz bestehen und muss manuell verarbeitet werden.

### Guthaben automatisch auf offene Rechnungen anrechnen

Wenn aktiviert, wird vorhandenes Kundenguthaben automatisch auf offene Rechnungen angerechnet. Die Verrechnung beginnt bei der ältesten fälligen Rechnung und arbeitet sich chronologisch vor.

Diese Einstellung ist standardmäßig aktiviert. Du kannst sie global deaktivieren oder pro Kunde individuell unter **Kunden > Einstellungen** überschreiben.

<Info>
  Beide Einstellungen können pro Kunde individuell überschrieben werden. Mehr dazu unter [Kundenguthaben](/guide/invoices/wallet-balance).
</Info>

## Abrechnung deaktivieren

Diese Funktion deaktiviert die Abrechnung aller Abonnements. Es werden keine neuen Rechnungen mehr erstellt oder versendet. Diese Option ist besonders nützlich, wenn Migrationen durchgeführt werden.

⸻

Einstellungen anpassen

<Steps>
  <Step title="Öffne die Abrechnungseinstellungen">
    Gehe hierzu zu [Einstellungen > Abrechnung](https://app.fynn.eu/settings/billing).
  </Step>

  <Step title="Passe die gewünschten Optionen an">
    Aktiviere oder deaktiviere die gewünschten Funktionen wie z.B. "Manuelle Freigabe", "GiroCode anzeigen" oder "0,00 € Belege generieren".

    <Frame>
      <img alt="Abrechnungseinstellungen" />
    </Frame>
  </Step>

  <Step title="Klicke auf Speichern">
    Speichere deine Änderungen oben rechts.
  </Step>
</Steps>

Möchtest du noch weitere Abschnitte wie „Rechnungsnummern“, „Steuern“ oder „Währungen“ dokumentieren?


# Erste Konfiguration
Source: https://docs.fynn.eu/guide/tenant/configure

Richte Fynn ein und beginne mit der Abrechnung deiner Produkte und Dienstleistungen

Willkommen bei Fynn! Diese Anleitung führt dich durch die ersten Schritte, um dein Unternehmen einzurichten und mit der Abrechnung zu beginnen.

<Frame>
  <img alt="Fynn Setup Checkliste" />
</Frame>

## Grundlegende Schritte

Diese Schritte sind notwendig, um Fynn vollumfänglich nutzen zu können.

### Unternehmen vervollständigen

<Note>
  Dieser Schritt ist **notwendig**, um Rechnungen erstellen zu können.
</Note>

Vervollständige deine Unternehmensdaten, damit diese korrekt auf deinen Rechnungen erscheinen.

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe zu [Einstellungen > Organisation](https://app.fynn.eu/settings/organization)
  </Step>

  <Step title="Vervollständige deine Unternehmensdaten">
    Fülle folgende Informationen aus:

    * **Firmenname**: Der vollständige Name deines Unternehmens
    * **Adresse**: Straße, Hausnummer, PLZ, Ort und Land
    * **Steuernummer / USt-IdNr.**: Für die korrekte Rechnungsstellung
    * **E-Mail-Adresse**: Kontakt-E-Mail für deine Kunden
    * **Telefonnummer**: Optional, aber empfohlen
  </Step>

  <Step title="Logo hochladen">
    Lade dein Unternehmenslogo hoch. Dieses wird auf Rechnungen, im Kundenportal und in E-Mails angezeigt.
  </Step>

  <Step title="Speichern">
    Klicke auf **Speichern**, um deine Änderungen zu übernehmen.
  </Step>
</Steps>

### Zahlungsmethoden hinzufügen

<Note>
  Dieser Schritt ist **notwendig**, um Zahlungen von deinen Kunden einziehen zu können.
</Note>

Richte mindestens eine Zahlungsmethode ein, um Zahlungen von deinen Kunden zu akzeptieren.

<Steps>
  <Step title="Zahlungsanbieter verbinden">
    Verbinde einen oder mehrere Zahlungsanbieter mit Fynn:

    <CardGroup>
      <Card title="SEPA-Lastschrift" icon="building-columns" href="/integrations/payment-providers/sepa">
        Automatischer Bankeinzug für wiederkehrende Zahlungen.
      </Card>

      <Card title="Stripe" icon="credit-card" href="/integrations/payment-providers/stripe">
        Kreditkarten und weitere Zahlungsmethoden.
      </Card>

      <Card title="PayPal" icon="paypal" href="/integrations/payment-providers/paypal">
        Beliebte Online-Zahlungsmethode.
      </Card>

      <Card title="Überweisung" icon="money-bill-transfer" href="/integrations/payment-providers/bank-transfer">
        Klassische Banküberweisung.
      </Card>
    </CardGroup>
  </Step>

  <Step title="Zahlungsmethoden aktivieren">
    Gehe zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods) und aktiviere die gewünschten Zahlungsmethoden für deine Kunden.

    [Mehr zur Konfiguration der Zahlungsmethoden](/guide/tenant/payment-methods)
  </Step>
</Steps>

### Mitarbeiter einladen

Lade dein Team ein, um gemeinsam mit Fynn zu arbeiten.

<Steps>
  <Step title="Öffne die Benutzereinstellungen">
    Gehe zu [Einstellungen > Benutzer](https://app.fynn.eu/settings/users)
  </Step>

  <Step title="Benutzer einladen">
    Klicke auf das **+** Symbol und gib die E-Mail-Adresse des neuen Benutzers ein.
  </Step>

  <Step title="Rolle zuweisen">
    Wähle eine passende Rolle für den Benutzer:

    * **Administrator**: Voller Zugriff auf alle Funktionen und Einstellungen
    * **Buchhaltung**: Zugriff auf Rechnungen, Zahlungen und Buchhaltung
    * **Benutzer**: Standard-Zugriff auf Kunden, Produkte und Abonnements

    [Mehr zu Benutzern & Berechtigungen](/guide/tenant/users)
  </Step>
</Steps>

***

## Abrechnung beginnen

Beginne mit der Abrechnung deiner Produkte und Dienstleistungen mit nur wenigen Klicks.

### Produkt anlegen

Erstelle dein erstes Produkt im Katalog.

<Steps>
  <Step title="Öffne den Katalog">
    Gehe zu [Katalog > Produkte](https://app.fynn.eu/catalogue/products)
  </Step>

  <Step title="Neues Produkt erstellen">
    Klicke auf **+ Produkt erstellen** und fülle die Produktdetails aus:

    * **Name**: Der Name des Produkts
    * **Beschreibung**: Eine kurze Beschreibung
    * **Preis**: Der Verkaufspreis
    * **Abrechnungsintervall**: Monatlich, jährlich oder einmalig
  </Step>
</Steps>

<Tip>
  Nutze [Produktgruppen](/guide/catalogue/product-groups), um ähnliche Produkte zu organisieren und Upgrades/Downgrades zu ermöglichen.
</Tip>

[Mehr zur Produktverwaltung](/guide/catalogue/products)

### Kunde anlegen

Lege deinen ersten Kunden an.

<Steps>
  <Step title="Öffne die Kundenverwaltung">
    Gehe zu [Kunden](https://app.fynn.eu/customers)
  </Step>

  <Step title="Neuen Kunden erstellen">
    Klicke auf **+ Kunde erstellen** und fülle die Kundendaten aus:

    * **Name**: Firmenname oder Privatperson
    * **E-Mail-Adresse**: Für Rechnungsversand und Kommunikation
    * **Adresse**: Rechnungsadresse
    * **Zahlungsmethode**: Die bevorzugte Zahlungsmethode
  </Step>
</Steps>

[Mehr zur Kundenverwaltung](/guide/customers/introduction)

### Abonnement erstellen

Erstelle dein erstes Abonnement für einen Kunden.

<Steps>
  <Step title="Kunden auswählen">
    Öffne den gewünschten Kunden und klicke auf **+ Abonnement erstellen**.
  </Step>

  <Step title="Produkte hinzufügen">
    Wähle die Produkte aus, die der Kunde abonnieren möchte.
  </Step>

  <Step title="Abonnement starten">
    Wähle das Startdatum und bestätige das Abonnement.
  </Step>
</Steps>

<Check>
  Nach dem Erstellen des Abonnements wird automatisch eine Rechnung generiert und an den Kunden versendet.
</Check>

[Mehr zu Abonnements](/guide/subscriptions/introduction)

***

## Erweiterte Integration

Integriere deine Anwendung mit Fynn und nutze die umfangreichen Möglichkeiten der API.

### Webhooks einrichten

Mit Webhooks wirst du in Echtzeit über Ereignisse in Fynn informiert.

<Steps>
  <Step title="Öffne die Webhook-Einstellungen">
    Gehe zu [Einstellungen > Webhooks](https://app.fynn.eu/settings/webhooks)
  </Step>

  <Step title="Webhook erstellen">
    Klicke auf **+ Webhook erstellen** und konfiguriere:

    * **URL**: Die Endpunkt-URL deiner Anwendung
    * **Ereignisse**: Wähle die Ereignisse, über die du informiert werden möchtest
  </Step>
</Steps>

[Mehr zu Webhooks](/guide/webhooks/introduction)

### API-Schlüssel generieren

Erstelle API-Schlüssel, um programmatisch auf Fynn zuzugreifen.

<Steps>
  <Step title="Öffne die API-Einstellungen">
    Gehe zu [Einstellungen > API-Schlüssel](https://app.fynn.eu/settings/api-tokens)
  </Step>

  <Step title="Neuen API-Schlüssel erstellen">
    Klicke auf **+ API-Schlüssel erstellen** und vergib einen Namen.
  </Step>

  <Step title="Schlüssel sicher speichern">
    <Warning>
      Der API-Schlüssel wird nur einmal angezeigt. Speichere ihn sicher ab, da er nicht erneut abgerufen werden kann.
    </Warning>
  </Step>
</Steps>

[API-Referenz](/api-reference)

***

## Nächste Schritte

<CardGroup>
  <Card title="Buchhaltung einrichten" icon="calculator" href="/integrations/accounting/datev">
    Verbinde Fynn mit DATEV für automatische Buchhaltung.
  </Card>

  <Card title="Mahnwesen konfigurieren" icon="triangle-exclamation" href="/guide/dunning/introduction">
    Automatisiere den Umgang mit überfälligen Zahlungen.
  </Card>

  <Card title="Checkout erstellen" icon="cart-shopping" href="/guide/checkout/checkout-links">
    Erstelle Checkout-Links für den Direktverkauf.
  </Card>

  <Card title="Kundenportal anpassen" icon="user" href="/guide/customers/customer-portal">
    Passe das Self-Service-Portal für deine Kunden an.
  </Card>
</CardGroup>


# Währungen
Source: https://docs.fynn.eu/guide/tenant/currencies

Währungen verwalten und automatisch umrechnen

In Fynn kannst du ganz einfach verschiedene Währungen für deine Abrechnungen einrichten.

<Tip>
  Standardmäßig ist die Währung auf Euro eingestellt.
</Tip>

<Tip>
  <b>Automatische Währungsumrechnung</b><br />
  Es können mehrere Währungen in einer Rechnung verwendet werden. Die Umrechnung erfolgt automatisch auf Basis des aktuellen EZB-Wechselkurses.
  Weitere Details findest unter [Multi-Währungen](/guide/tenant/currencies#multi-waehrungen).
</Tip>

## Währung hinzufügen

Um eine neue Währung hinzuzufügen, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Allgemein](https://app.fynn.eu/settings/)
  </Step>

  <Step title="Scrolle zum Bereich Währungen" />

  <Step title="Öffne eines der Dropdowns und klicke auf Währung hinzufügen">
    <Frame>
      <img alt="Währung hinzufügen" />
    </Frame>
  </Step>

  <Step title="Wähle die neue Währung aus" />

  <Step title="Klicke auf das Check Icon um dies zu speichern" />
</Steps>

## Standardwährung auswählen

Die Standardwährung wird in der Oberfläche vorausgewählt und erleichtert somit die Arbeit. Um die Standardwährung zu ändern, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Allgemein](https://app.fynn.eu/settings/)
  </Step>

  <Step title="Scrolle zum Bereich Währungen" />

  <Step title="Klicke auf das Dropdown der Standard-Währung, die du als Standard festlegen möchtest">
    <Frame>
      <img alt="Standardwährung ändern" />
    </Frame>
  </Step>

  <Step title="Wähle die neue Standardwährung aus" />

  <Step title="Klicke auf Speichern" />
</Steps>

## Erlaubte Währungen

Erlaubte Währungen sind die Währungen, die in Fynn für die Abrechnung verwendet werden können. Um eine Währung zu entfernen, entferne sie einfach aus der Liste der erlaubten Währungen.
Bestehende Belege und Rechnungen werden nicht automatisch umgerechnet, wenn die Währung entfernt wird. Die Währung wird jedoch in der Oberfläche nicht mehr zur Neu-Auswahl angeboten.

<Frame>
  <img alt="Erlaubte Währungen" />
</Frame>

## Multi-Währungen

Fynn unterstützt die Verwendung von mehreren Währungen in einer Rechnung. Die Umrechnung erfolgt automatisch auf Basis des aktuellen EZB-Wechselkurses.

Die Ziel-Währung entspricht der Währung, die bei der Rechnungs-Anlage ausgewählt wurde. Wurde die Rechnung durch die Abonnement-Abrechnung
angelegt, wurde die Währung des Kunden verwendet.

Die entsprechenden Währungskurse werden in Echtzeit von der Europäischen Zentralbank (EZB) abgerufen und in der Rechnung tabellarisch dargestellt.

<Frame>
  <img alt="Multi-Währungen" />
</Frame>


# Benutzerdefinierte Attribute
Source: https://docs.fynn.eu/guide/tenant/custom-fields

Erstelle benutzerdefinierte Attribute für verschiedene Objekte.

Benutzerdefinierte Attribute ermöglichen es dir, zusätzliche Informationen zu verschiedenen Objekten zu speichern. Diese Attribute können je nach Einstellung sowohl in der API als auch in der Benutzeroberfläche angezeigt und bearbeitet werden.

Diese können für <a href="/guide/customers/introduction">Kunden</a>, <a href="/guide/catalogue/products">Produkte</a> und <a href="/guide/subscriptions/introduction">Abonnements</a> definiert werden.
Zudem sind folgende Typen von benutzerdefinierten Attributen möglich:

* Text
* Zahl
* Datum
* Auswahloptionen
* Mehrfachauswahl
* Liste
* Checkbox (Ja/Nein)

## Use Cases

Benutzerdefinierte Attribute können für verschiedene Zwecke verwendet werden, wie z.B.:

* Speichern von zusätzlichen Informationen zu Kunden, wie z.B. Geburtsdatum, interne Kundennummer, etc.
* Speichern von zusätzlichen Informationen zu Produkten, wie z.B. Hersteller, Gewicht, etc.
* Speichern von zusätzlichen Informationen zu Abonnements, wie z.B. Vertragsnummer, etc.
* Speichern von erlaubten Features für ein Produkt am Abonnement

Dies sind nur einige Beispiele, wie benutzerdefinierte Attribute verwendet werden können. Die Verwendung hängt von den spezifischen Anforderungen deines Unternehmens ab.

## Benutzerdefinierte Attribute erstellen

<Steps>
  <Step title="Gehe zu den Einstellungen > Allgemein">
    Scrolle nach unten zu "Benutzerdefinierte Attribute".
  </Step>

  <Step title="Klicke auf 'Neues Attribut erstellen'">
    <Frame>
      <img alt="Benutzerdefinierte Attribute erstellen" />
    </Frame>
  </Step>

  <Step title="Attribut konfigurieren">
    Konfiguriere das Attribut nach deinen Anforderungen.

    <Frame>
      <img alt="Benutzerdefinierte Attribute konfigurieren" />
    </Frame>
  </Step>
</Steps>

## Benutzerdefinierte Attribute löschen

Solltest du ein benutzerdefiniertes Attribut nicht mehr benötigen, kannst du es löschen.
Die Daten bleiben erhalten, jedoch wird das Attribut nicht mehr angezeigt und kann nicht mehr bearbeitet werden.

## Benutzerdefinierte Attribute bearbeiten

Benutzerdefinierte Attribute können an Kunden, Produkte und Abonnements angehängt werden. Diese können in der Benutzeroberfläche bearbeitet werden.

<Frame>
  <img alt="Benutzerdefinierte Attribute setzen" />
</Frame>

## API verwenden

Benutzerdefinierte Attribute können ebenfalls über die API gesetzt und abgerufen werden. Hierzu muss lediglich das `customFields` Feld in den entsprechenden Objekten verwendet werden.

### Auswahloptionen / Mehrfachauswahl

Standardmäßig wird als Wert & Anzeigename der Anzeigename als Schlüssel verwendet.
Sollte dies nicht gewünscht sein, kann bei Anlage der Benutzerdefinierten Attribute unter dem Punkt `choices` ein Array übergeben werden, wo Wert & Anzeigename definiert werden können.

```json Beispiel JSON Payload theme={null}
{
    "name": "My custom field",
    "slug": "custom_field",
    "type": "list",
    "choices": {
        "value1": "Anzeigename 1",
        "value2": "Anzeigename 2"
    }
}
```


# Go-Live
Source: https://docs.fynn.eu/guide/tenant/go-live-checklist

Best Practices und wichtige Schritte für einen erfolgreichen Produktivstart mit Fynn.

Du planst den Go-Live mit Fynn? Diese Checkliste hilft dir, alle wichtigen Vorbereitungen zu treffen und nichts zu vergessen.

<Note>
  Für die Produktivumgebung ist ein Vertrag mit unserem Sales-Team erforderlich. [Kontaktiere uns](mailto:sales@fynn.eu) oder [buche einen Termin](https://cal.com/team/fynn/fynn-documentation).
</Note>

<Tip>
  Die meisten Einstellungen sind bereits in der [Ersten Konfiguration](/guide/tenant/first-configuration) beschrieben. Diese Checkliste dient als Übersicht für den finalen Go-Live.
</Tip>

***

## Produkte aus der Testumgebung übernehmen

Du hast Produkte in der Sandbox-Umgebung konfiguriert? Diese kannst du einfach in die Produktivumgebung importieren:

<Steps>
  <Step title="API-Token in der Testumgebung erstellen">
    Erstelle in der [Sandbox-Umgebung](https://preview.fynn.eu) unter Einstellungen > API einen API-Token.
  </Step>

  <Step title="Import starten">
    Gehe in der Produktivumgebung zu [Katalog > Produkte](https://app.fynn.eu/catalogue/products) und wähle im Aktionen-Menü (oben rechts) **Testumgebung Import**.
  </Step>

  <Step title="Produkte auswählen">
    * Gib den API-Token aus der Testumgebung ein
    * Wähle die Produkte aus, die importiert werden sollen
    * Ordne benutzerdefinierte Felder zu (neu erstellen oder vorhandene verwenden)
    * Ordne Kostenstellen zu
    * Produkte, Preise und Konfigurationen werden kopiert
  </Step>
</Steps>

***

## Zahlungsanbieter (PSP) einrichten

### SEPA-Lastschrift

Für den Einzug per SEPA-Lastschrift benötigst du:

<Steps>
  <Step title="Gläubiger-ID beantragen">
    Beantrage deine Gläubiger-Identifikationsnummer bei der [Deutschen Bundesbank](https://extranet.bundesbank.de/scp/beantragungCI/lizenz.xhtml).

    Die Beantragung ist online möglich und dauert nur wenige Minuten.
  </Step>

  <Step title="SEPA-Verfügungsrahmen bei deiner Bank">
    Kläre mit deiner Hausbank den SEPA-Verfügungsrahmen (Limits) für Lastschrifteinzüge.
  </Step>

  <Step title="SEPA in Fynn verbinden">
    Hinterlege deine Bankdaten und Gläubiger-ID unter [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods).

    [Zur SEPA-Anleitung](/integrations/payment-providers/sepa)
  </Step>
</Steps>

### Kreditkarte (Stripe)

<Steps>
  <Step title="Stripe-Konto erstellen">
    Du kannst dein Stripe-Konto direkt während der Verbindung in Fynn erstellen.
  </Step>

  <Step title="Unternehmensverifizierung abschließen">
    Stripe benötigt Unternehmensdokumente zur Verifizierung (Handelsregisterauszug, Ausweisdokument).

    **Dauer:** 1-5 Werktage
  </Step>

  <Step title="Stripe in Fynn verbinden">
    [Zur Stripe-Anleitung](/integrations/payment-providers/stripe)
  </Step>
</Steps>

### PayPal

<Steps>
  <Step title="PayPal Business-Konto">
    Erstelle ein [PayPal Business-Konto](https://www.paypal.com/de/business) falls noch nicht vorhanden.
  </Step>

  <Step title="PayPal in Fynn verbinden">
    [Zur PayPal-Anleitung](/integrations/payment-providers/paypal)
  </Step>
</Steps>

***

## Fynn konfigurieren

### Unternehmensdaten

Unter [Einstellungen > Organisation](https://app.fynn.eu/settings) hinterlegst du:

* Vollständiger Firmenname
* Adresse (Straße, PLZ, Ort, Land)
* Steuernummer und USt-IdNr.
* Kontakt-E-Mail und Telefon
* Firmenlogo
* Bankverbindung (für Rechnungen)

### Nummernkreise

Lege unter [Einstellungen > Nummernkreise](https://app.fynn.eu/settings/number-ranges) fest:

* Rechnungsnummern (z.B. `RE-2024-00001`)
* Gutschriftennummern
* Kundennummern

[Mehr zu Nummernkreisen](/guide/tenant/number-ranges)

### E-Mail-Vorlagen

Passe unter [Einstellungen > Benachrichtigungen](https://app.fynn.eu/settings/notifications) die E-Mail-Vorlagen an:

* Rechnungsversand
* Zahlungsbestätigung
* Zahlungserinnerung / Mahnung
* Willkommens-E-Mail

[Mehr zu Benachrichtigungen](/guide/notifications/introduction)

### Dokumentvorlagen

Falls du das Layout deiner Dokumente anpassen möchtest, konfiguriere unter [Einstellungen > Aussehen & Design](https://app.fynn.eu/settings/design) die Vorlagen für:

* Rechnung
* Stornierung
* Gutschrift

### Mahnwesen

Konfiguriere unter [Einstellungen > Mahnwesen](https://app.fynn.eu/settings/payment-failures) deine Mahnstufen und Fristen.

[Mehr zum Mahnwesen](/guide/dunning/introduction)

***

## Zahlungsmethoden aktivieren

Nach dem Verbinden der Zahlungsanbieter müssen die gewünschten Zahlungsmethoden unter [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods) aktiviert werden.

***

## Kontoabgleich einrichten

Für die automatische Zahlungszuordnung verbinde dein Bankkonto unter [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods) > **Bankkonto** > **Kontoabgleich**. Eingehende Zahlungen werden automatisch den offenen Rechnungen zugeordnet.

***

## Buchhaltung

Falls du eine Buchhaltungssoftware nutzt:

* DATEV-Export einrichten
* Kontenrahmen prüfen
* Erlöskonten zuordnen

[Mehr zur Buchhaltung](/guide/accounting/introduction)

***

## Kundenbereich

Unter [Einstellungen > Kundenbereich](https://app.fynn.eu/settings/hosted-services) kannst du das Self-Service-Portal für deine Kunden konfigurieren - z.B. welche Funktionen verfügbar sind, Branding und eigene Domain.

***

## Team einladen

Lade dein Team unter [Einstellungen > Benutzer](https://app.fynn.eu/settings/users) ein und vergib passende Rollen.

Falls du granulare Berechtigungen benötigst, erstelle unter [Einstellungen > Gruppen](https://app.fynn.eu/settings/groups) Benutzergruppen mit spezifischen Rechten.

[Mehr zu Benutzerrollen](/guide/tenant/users)

***

## Abrechnungseinstellungen

Unter [Einstellungen > Abrechnung](https://app.fynn.eu/settings/billing) kannst du festlegen:

* **Manuelle Rechnungsfreigabe**: Rechnungen müssen vor dem Versand manuell freigegeben werden
* Automatische Rechnungserstellung und -versand konfigurieren

<Tip>
  Die manuelle Freigabe ist besonders nützlich, wenn du beim Go-Live volle Kontrolle über die ersten Rechnungen behalten möchtest - zum Beispiel um deine Konfiguration zu verifizieren oder um interne Freigabeprozesse abzubilden.
</Tip>

***

## Vor dem Go-Live testen

<Check>
  Teste alle Prozesse in der [Sandbox-Umgebung](https://preview.fynn.eu) bevor du live gehst.
</Check>

Teste mindestens:

* Kunde anlegen mit Zahlungsmethode
* Abonnement erstellen und aktivieren
* Rechnung generieren und versenden
* Zahlung einziehen
* E-Mail-Vorlagen auf Inhalt und Design prüfen

***

## Checkliste

* Produkte aus Testumgebung importiert
* Gläubiger-ID beantragt (für SEPA)
* SEPA-Verfügungsrahmen mit Bank geklärt (für SEPA)
* Zahlungsanbieter verbunden (SEPA, Stripe, PayPal, etc.)
* Zahlungsmethoden aktiviert
* Kontoabgleich für automatische Zahlungszuordnung eingerichtet
* Unternehmensdaten vollständig hinterlegt
* Logo hochgeladen
* Nummernkreise konfiguriert
* E-Mail-Vorlagen angepasst
* Dokumentvorlagen angepasst (falls erforderlich)
* Abrechnungseinstellungen geprüft (manuelle Freigabe?)
* Mahnwesen eingerichtet
* Kundenbereich konfiguriert
* Buchhaltungsintegration konfiguriert
* Team eingeladen und Benutzergruppen erstellt
* Testdurchlauf in Sandbox erfolgreich

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich Produkte aus der Testumgebung übernehmen?">
    Ja! Unter **Katalog > Produkte > Aktionen > Testumgebung Import** kannst du Produkte, Preise und Konfigurationen aus der Sandbox importieren. Du benötigst dafür einen API-Token aus der Testumgebung.
  </Accordion>

  <Accordion title="Wie lange dauert die Stripe-Verifizierung?">
    Die Unternehmensverifizierung bei Stripe dauert in der Regel 1-5 Werktage. Stripe benötigt Unternehmensdokumente (Handelsregisterauszug, Ausweisdokument). Starte die Verifizierung rechtzeitig vor dem geplanten Go-Live.
  </Accordion>

  <Accordion title="Kann ein Kunde mehrere Zahlungsmethoden haben?">
    Ja, Kunden können mehrere Zahlungsmethoden hinterlegen (z.B. SEPA und Kreditkarte). **Ausnahme:** Pro Kunde kann nur ein PayPal-Konto hinterlegt werden.
  </Accordion>

  <Accordion title="Was passiert bei SEPA-Fehlern?">
    * **Mandatsprobleme** (MD01, MD02): Zahlungsmethode wird deaktiviert
    * **Kontoprobleme** (AC01, AC04): Zahlungsmethode wird deaktiviert
    * **Temporäre Probleme** (AM04, AM05): Automatischer Retry wird geplant
    * **Regulatorische Probleme** (AG01, RR01): Manuelle Prüfung erforderlich
  </Accordion>

  <Accordion title="Kann ich Rechnungen ohne Zahlungsmethode finalisieren?">
    Nein, für die Finalisierung einer Rechnung muss eine gültige Zahlungsmethode hinterlegt sein. Falls die Zahlungsmethode ungültig ist, erscheint ein Dialog zur Auswahl einer neuen. **Überweisung** ist immer als Fallback verfügbar.
  </Accordion>

  <Accordion title="Was kostet SMS-Versand für Mahnungen?">
    SMS-Versand ist ein kostenpflichtiges Feature: **0,10€ pro SMS** (max. 160 Zeichen).
  </Accordion>

  <Accordion title="Kann ich Kunden löschen?">
    Ein Kunde kann nur gelöscht werden, wenn er keine aktiven Abonnements, Rechnungen, Bestellungen oder Zahlungen hat. Alternativ kannst du Kunden **archivieren** - diese können später wiederhergestellt werden.
  </Accordion>

  <Accordion title="Werden Mahngebühren in den Buchhaltungsexport übernommen?">
    Mahngebühren werden aktuell noch nicht in den Buchhaltungsexport (z.B. DATEV) übernommen. Diese müssen manuell verbucht werden.
  </Accordion>
</AccordionGroup>

***

## Weitere Hilfe

Bei Fragen zum Go-Live: [Termin buchen](https://cal.com/team/fynn/fynn-documentation) oder [Support kontaktieren](mailto:hi@fynn.eu)


# Nummernkreise
Source: https://docs.fynn.eu/guide/tenant/number-ranges

Nummernkreise

Standardmäßig sind die Nummernkreise bereits eingerichtet. Solltest du allerdings eigene Nummernkreise benötigen, kannst du diese entsprechend konfigurieren.

Für jeden Belegtyp (z.B. Rechnung, Angebot, Bestellung, etc.) und Dokumente kann ein eigener Nummernkreis eingerichtet werden. Folgende Typen sind verfügbar:

* Kunden
* Abonnements
* Rechnungen
* Gutschriften
* Mahnungen / Zahlungserinnerungen
* Zahlungen
* Stornos
* DATEV Debitorennummern
* Mandatsreferenz (SEPA-Lastschrift)

## Nummernkreise einrichten

### Platzhalter

Um deine Nummern individuell anzupassen, stehen dir verschiedene Platzhalter zur Verfügung:

* `{number}`: Eine fortlaufende Nummer, die automatisch generiert wird.
* `{day}`: Der Tag des Monats (z.B. 10).
* `{month}`: Der Monat (z.B. 09).
* `{year}`: Das Jahr (z.B. 22).
* `{yearLong}`: Das vollständige Jahr (z.B. 2022).
* `{customerNumber}`: Die Kundennummer.

### Nummernvergabe

Fynn bietet dir zwei verschiedene Verfahren zur Nummernvergabe:

* <b>Fortlaufende Nummer</b>: Deine Nummer basiert auf einer fortlaufenden Sequenz.
* <b>Zufälliger String</b>: Deine Nummer wird mit zufälligen Zahlen und Buchstaben generiert.

Mit diesen Optionen kannst du sicherstellen, dass deine Dokumentennummern genau deinen Anforderungen entsprechen.

### Nummernformatierung

Im Feld "Format" kannst du das Format für die Nummern festlegen. Zum Beispiel könntest du für Rechnungen das Format `RE-{number}` verwenden.

## Nummernkreise anpassen

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Nummernkreise](https://app.fynn.eu/settings/number-ranges)
  </Step>

  <Step title="Konfiguriere die Nummernkreise">
    <Frame>
      <img alt="Nummernkreise" />
    </Frame>
  </Step>

  <Step title="Klicke auf Speichern" />
</Steps>

<Note>
  Einmal vergebene Nummernkreise werden nicht erneut vergeben, unabhängig davon ob die "Aktuelle Nummer" zurückgesetzt wird.
</Note>


# Passkeys
Source: https://docs.fynn.eu/guide/tenant/passkeys

Melde dich mit Face ID, Touch ID oder einem Hardware-Sicherheitsschlüssel an — sicher und ohne Passwort.

## Übersicht

Passkeys sind eine sichere und bequeme Alternative zum klassischen Passwort-Login. Sie nutzen die biometrische Authentifizierung deines Geräts (Face ID, Touch ID, Windows Hello) oder einen Hardware-Sicherheitsschlüssel (z. B. YubiKey), um dich bei Fynn anzumelden.

**Vorteile von Passkeys:**

* **Sicherer als Passwörter** — Passkeys basieren auf Public-Key-Kryptografie und können nicht erraten oder gestohlen werden
* **Phishing-resistent** — Passkeys sind an die Domain gebunden und funktionieren nicht auf gefälschten Websites
* **Kein Passwort nötig** — Login mit einem Fingertipp oder Blick

<Info>
  Passkeys ergänzen den bestehenden Passwort-Login. Du kannst dich weiterhin mit deinem Passwort anmelden, auch wenn ein Passkey eingerichtet ist.
</Info>

## Passkey einrichten

<Steps>
  <Step title="Kontoeinstellungen öffnen">
    Klicke auf deinen Avatar oder Namen in der oberen Navigation und wähle **Mein Profil**. Navigiere dann zum Tab **Sicherheit**.
  </Step>

  <Step title="Passkey hinzufügen">
    Klicke im Bereich **Passkeys** auf **Passkey hinzufügen**. Dein Browser fordert dich auf, einen Passkey zu erstellen.
  </Step>

  <Step title="Authentifizierung bestätigen">
    Bestätige die Erstellung mit deinem Gerät:

    * **Mac**: Touch ID oder Systempasswort
    * **iPhone/iPad**: Face ID oder Touch ID
    * **Windows**: Windows Hello (Fingerabdruck, Gesichtserkennung oder PIN)
    * **Hardware-Schlüssel**: Berühre den Sicherheitsschlüssel
  </Step>

  <Step title="Passkey benennen">
    Vergib einen aussagekräftigen Namen für den Passkey (z. B. „MacBook Pro Büro" oder „YubiKey"). So erkennst du später, welches Gerät oder welcher Schlüssel hinterlegt ist.
  </Step>
</Steps>

<Tip>
  Du kannst mehrere Passkeys für verschiedene Geräte einrichten. So kannst du dich sowohl am Laptop als auch am Smartphone mit einem Passkey anmelden.
</Tip>

## Mit Passkey anmelden

<Steps>
  <Step title="Login-Seite öffnen">
    Öffne die Fynn Login-Seite unter [app.fynn.eu](https://app.fynn.eu).
  </Step>

  <Step title="Passkey-Login wählen">
    Klicke auf **Mit Passkey anmelden**. Dein Browser erkennt automatisch, welche Passkeys für diese Seite verfügbar sind.
  </Step>

  <Step title="Authentifizieren">
    Bestätige den Login mit deinem Gerät (Face ID, Touch ID, Sicherheitsschlüssel). Du wirst sofort angemeldet — ohne E-Mail oder Passwort.
  </Step>
</Steps>

## Passkeys verwalten

Im Bereich **Mein Profil > Sicherheit** siehst du alle eingerichteten Passkeys mit folgenden Informationen:

| Feld                  | Beschreibung                                   |
| --------------------- | ---------------------------------------------- |
| **Name**              | Der von dir vergebene Name des Passkeys        |
| **Erstellt am**       | Datum der Einrichtung                          |
| **Zuletzt verwendet** | Datum der letzten Anmeldung mit diesem Passkey |

### Passkey entfernen

Klicke neben dem Passkey auf das Löschen-Symbol, um ihn zu entfernen. Nach dem Entfernen kann dieser Passkey nicht mehr für die Anmeldung verwendet werden.

<Warning>
  Wenn du deinen letzten Passkey entfernst, stelle sicher, dass du dich noch mit deinem Passwort anmelden kannst.
</Warning>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Welche Geräte und Browser unterstützen Passkeys?">
    Passkeys werden von allen modernen Browsern und Betriebssystemen unterstützt:

    * **macOS / iOS**: Safari, Chrome, Firefox (ab macOS 13 / iOS 16)
    * **Windows**: Chrome, Edge, Firefox (ab Windows 10)
    * **Android**: Chrome (ab Android 9)

    Hardware-Sicherheitsschlüssel (FIDO2/WebAuthn) werden ebenfalls unterstützt.
  </Accordion>

  <Accordion title="Funktionieren Passkeys geräteübergreifend?">
    Das hängt von deinem Ökosystem ab. Apple synchronisiert Passkeys über iCloud Keychain auf alle Apple-Geräte. Google synchronisiert über den Google Password Manager. Für geräteübergreifende Nutzung (z. B. Mac und Windows) empfehlen wir, auf jedem Gerät einen eigenen Passkey einzurichten oder einen Hardware-Sicherheitsschlüssel zu verwenden.
  </Accordion>

  <Accordion title="Was passiert, wenn ich mein Gerät verliere?">
    Wenn du dein Gerät verlierst, kannst du dich weiterhin mit deinem Passwort anmelden. Entferne den Passkey des verlorenen Geräts anschließend in den Kontoeinstellungen.
  </Accordion>

  <Accordion title="Kann ich Passkey und Passwort gleichzeitig nutzen?">
    Ja. Passkeys ergänzen den Passwort-Login. Beide Methoden funktionieren parallel. Auf der Login-Seite kannst du wählen, ob du dich mit Passkey oder Passwort anmelden möchtest.
  </Accordion>

  <Accordion title="Sind Passkeys sicherer als Passwörter?">
    Ja. Passkeys basieren auf asymmetrischer Kryptografie (WebAuthn-Standard). Der private Schlüssel verlässt dein Gerät nie. Es gibt kein gemeinsames Geheimnis, das abgefangen werden kann — Phishing, Credential Stuffing und Brute-Force-Angriffe sind damit ausgeschlossen.
  </Accordion>
</AccordionGroup>


# Zahlungsmethoden
Source: https://docs.fynn.eu/guide/tenant/payment-methods

Zahlungsmethoden

Du kannst verschiedene Zahlungsmethoden einrichten,
um deinen Kunden eine bequeme und sichere Möglichkeit zur Bezahlung anzubieten.

## Verfügbare Zahlungsmethoden

Folgende Zahlungsmethoden stehen zur Verfügung:

* <b>SEPA-Lastschrift</b>: Kunden können Zahlungen über SEPA-Lastschriftverfahren vornehmen.
* <b>Überweisung</b>: Kunden können Zahlungen per Überweisung tätigen.
* <b>Kreditkarte</b>: Kunden können mit Kreditkarten bezahlen, darunter Visa, Mastercard, American Express usw.
* <b>PayPal</b>: Kunden können ihre PayPal-Konten verwenden, um Zahlungen zu tätigen.

## Zahlungsanbieter einrichten

Um Zahlungsmethoden zu aktivieren, musst du zuerst die Zahlungsanbieter einrichten.

<CardGroup>
  <Card
    title="GoCardless"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        xmlnsXlink="http://www.w3.org/1999/xlink"
        version="1.1"
        id="Layer_1"
        x="0px"
        y="0px"
        viewBox="0 0 1000 1000"
        style={{ enableBackground: "new 0 0 1000 1000" }}
        xmlSpace="preserve"
    >
        <style
            type="text/css"
            dangerouslySetInnerHTML={{
                __html: "\n\t.st0{fill:#F1F252;}\n\t.st1{fill:#1C1B18;}\n"
            }}
        />
        <rect className="st0" width={1000} height={1000} rx={256} />
        <path
            className="st1"
            d="M507.9,242.1c55.2,0,86.2,9,86.2,9l91.7,187.2l-0.8,0.8l-118-70.4c-68.4-40.7-118-62.1-158.4-60.5  c-42.7,0.8-68.3,35.2-68.3,85c1.5,127.5,122.7,284.5,243.1,284.5c49.1,0,74.7-15.8,89.7-34.9L494.8,447.3v-0.8h244.8  c3.3,17.5,5.2,35.3,5.4,53.1c0,143.1-109.5,258.3-244.6,258.3C364.7,757.9,255,642.7,255,499.6C254.8,357.3,364.3,242.1,507.9,242.1  z"
        />
    </svg>
    }
    href="/integrations/payment-providers/go-cardless"
  >
    GoCardless ist der Global-Leader für Lastschrift-Zahlungen.
  </Card>

  <Card
    title="Stripe Payments"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        width={50}
        height={30}
        viewBox="0 0 512 214"
        preserveAspectRatio="xMidYMid"
    >
        <script xmlns="" />
        <path
            d="M35.982 83.484c0-5.546 4.551-7.68 12.09-7.68 10.808 0 24.461 3.272 35.27 9.103V51.484c-11.804-4.693-23.466-6.542-35.27-6.542C19.2 44.942 0 60.018 0 85.192c0 39.252 54.044 32.995 54.044 49.92 0 6.541-5.688 8.675-13.653 8.675-11.804 0-26.88-4.836-38.827-11.378v33.849c13.227 5.689 26.596 8.106 38.827 8.106 29.582 0 49.92-14.648 49.92-40.106-.142-42.382-54.329-34.845-54.329-50.774zm96.142-66.986l-34.702 7.395-.142 113.92c0 21.05 15.787 36.551 36.836 36.551 11.662 0 20.195-2.133 24.888-4.693V140.8c-4.55 1.849-27.022 8.391-27.022-12.658V77.653h27.022V47.36h-27.022l.142-30.862zm71.112 41.386L200.96 47.36h-30.72v124.444h35.556V87.467c8.39-10.951 22.613-8.96 27.022-7.396V47.36c-4.551-1.707-21.191-4.836-29.582 10.524zm38.257-10.524h35.698v124.444h-35.698V47.36zm0-10.809l35.698-7.68V0l-35.698 7.538V36.55zm109.938 8.391c-13.938 0-22.898 6.542-27.875 11.094l-1.85-8.818h-31.288v165.83l35.555-7.537.143-40.249c5.12 3.698 12.657 8.96 25.173 8.96 25.458 0 48.64-20.48 48.64-65.564-.142-41.245-23.609-63.716-48.498-63.716zm-8.533 97.991c-8.391 0-13.37-2.986-16.782-6.684l-.143-52.765c3.698-4.124 8.818-6.968 16.925-6.968 12.942 0 21.902 14.506 21.902 33.137 0 19.058-8.818 33.28-21.902 33.28zM512 110.08c0-36.409-17.636-65.138-51.342-65.138-33.85 0-54.33 28.73-54.33 64.854 0 42.808 24.179 64.426 58.88 64.426 16.925 0 29.725-3.84 39.396-9.244v-28.445c-9.67 4.836-20.764 7.823-34.844 7.823-13.796 0-26.027-4.836-27.591-21.618h69.547c0-1.85.284-9.245.284-12.658zm-70.258-13.511c0-16.071 9.814-22.756 18.774-22.756 8.675 0 17.92 6.685 17.92 22.756h-36.694z"
            fill="#6772E5"
        />
        <script xmlns="" />
        <script xmlns="" id="bw-fido2-page-script" />
    </svg>}
    href="/integrations/payment-providers/stripe"
  >
    Stripe ist ein Zahlungsanbieter, der es Unternehmen ermöglicht, Kreditkarten-Zahlungen zu akzeptieren.
  </Card>

  <Card
    title="PayPal"
    icon={
        <svg
            xmlns="http://www.w3.org/2000/svg"
            height={30}
            viewBox="-.02682843 0 123.63183286 30.17842908"
            width={75}
        >
            <script xmlns="" />
            <path
                d="m46.211 6.749h-6.839a.95.95 0 0 0 -.939.802l-2.766 17.537a.57.57 0 0 0 .564.658h3.265a.95.95 0 0 0 .939-.803l.746-4.73a.95.95 0 0 1 .938-.803h2.165c4.505 0 7.105-2.18 7.784-6.5.306-1.89.013-3.375-.872-4.415-.972-1.142-2.696-1.746-4.985-1.746zm.789 6.405c-.374 2.454-2.249 2.454-4.062 2.454h-1.032l.724-4.583a.57.57 0 0 1 .563-.481h.473c1.235 0 2.4 0 3.002.704.359.42.469 1.044.332 1.906zm19.654-.079h-3.275a.57.57 0 0 0 -.563.481l-.145.916-.229-.332c-.709-1.029-2.29-1.373-3.868-1.373-3.619 0-6.71 2.741-7.312 6.586-.313 1.918.132 3.752 1.22 5.031.998 1.176 2.426 1.666 4.125 1.666 2.916 0 4.533-1.875 4.533-1.875l-.146.91a.57.57 0 0 0 .562.66h2.95a.95.95 0 0 0 .939-.803l1.77-11.209a.568.568 0 0 0 -.561-.658zm-4.565 6.374c-.316 1.871-1.801 3.127-3.695 3.127-.951 0-1.711-.305-2.199-.883-.484-.574-.668-1.391-.514-2.301.295-1.855 1.805-3.152 3.67-3.152.93 0 1.686.309 2.184.892.499.589.697 1.411.554 2.317zm22.007-6.374h-3.291a.954.954 0 0 0 -.787.417l-4.539 6.686-1.924-6.425a.953.953 0 0 0 -.912-.678h-3.234a.57.57 0 0 0 -.541.754l3.625 10.638-3.408 4.811a.57.57 0 0 0 .465.9h3.287a.949.949 0 0 0 .781-.408l10.946-15.8a.57.57 0 0 0 -.468-.895z"
                fill="#253b80"
            />
            <path
                d="m94.992 6.749h-6.84a.95.95 0 0 0 -.938.802l-2.766 17.537a.569.569 0 0 0 .562.658h3.51a.665.665 0 0 0 .656-.562l.785-4.971a.95.95 0 0 1 .938-.803h2.164c4.506 0 7.105-2.18 7.785-6.5.307-1.89.012-3.375-.873-4.415-.971-1.142-2.694-1.746-4.983-1.746zm.789 6.405c-.373 2.454-2.248 2.454-4.062 2.454h-1.031l.725-4.583a.568.568 0 0 1 .562-.481h.473c1.234 0 2.4 0 3.002.704.359.42.468 1.044.331 1.906zm19.653-.079h-3.273a.567.567 0 0 0 -.562.481l-.145.916-.23-.332c-.709-1.029-2.289-1.373-3.867-1.373-3.619 0-6.709 2.741-7.311 6.586-.312 1.918.131 3.752 1.219 5.031 1 1.176 2.426 1.666 4.125 1.666 2.916 0 4.533-1.875 4.533-1.875l-.146.91a.57.57 0 0 0 .564.66h2.949a.95.95 0 0 0 .938-.803l1.771-11.209a.571.571 0 0 0 -.565-.658zm-4.565 6.374c-.314 1.871-1.801 3.127-3.695 3.127-.949 0-1.711-.305-2.199-.883-.484-.574-.666-1.391-.514-2.301.297-1.855 1.805-3.152 3.67-3.152.93 0 1.686.309 2.184.892.501.589.699 1.411.554 2.317zm8.426-12.219-2.807 17.858a.569.569 0 0 0 .562.658h2.822c.469 0 .867-.34.939-.803l2.768-17.536a.57.57 0 0 0 -.562-.659h-3.16a.571.571 0 0 0 -.562.482z"
                fill="#179bd7"
            />
            <path
                d="m7.266 29.154.523-3.322-1.165-.027h-5.563l3.866-24.513a.316.316 0 0 1 .314-.268h9.38c3.114 0 5.263.648 6.385 1.927.526.6.861 1.227 1.023 1.917.17.724.173 1.589.007 2.644l-.012.077v.676l.526.298a3.69 3.69 0 0 1 1.065.812c.45.513.741 1.165.864 1.938.127.795.085 1.741-.123 2.812-.24 1.232-.628 2.305-1.152 3.183a6.547 6.547 0 0 1 -1.825 2c-.696.494-1.523.869-2.458 1.109-.906.236-1.939.355-3.072.355h-.73c-.522 0-1.029.188-1.427.525a2.21 2.21 0 0 0 -.744 1.328l-.055.299-.924 5.855-.042.215c-.011.068-.03.102-.058.125a.155.155 0 0 1 -.096.035z"
                fill="#253b80"
            />
            <path
                d="m23.048 7.667c-.028.179-.06.362-.096.55-1.237 6.351-5.469 8.545-10.874 8.545h-2.752c-.661 0-1.218.48-1.321 1.132l-1.409 8.936-.399 2.533a.704.704 0 0 0 .695.814h4.881c.578 0 1.069-.42 1.16-.99l.048-.248.919-5.832.059-.32c.09-.572.582-.992 1.16-.992h.73c4.729 0 8.431-1.92 9.513-7.476.452-2.321.218-4.259-.978-5.622a4.667 4.667 0 0 0 -1.336-1.03z"
                fill="#179bd7"
            />
            <path
                d="m21.754 7.151a9.757 9.757 0 0 0 -1.203-.267 15.284 15.284 0 0 0 -2.426-.177h-7.352a1.172 1.172 0 0 0 -1.159.992l-1.564 9.906-.045.289a1.336 1.336 0 0 1 1.321-1.132h2.752c5.405 0 9.637-2.195 10.874-8.545.037-.188.068-.371.096-.55a6.594 6.594 0 0 0 -1.017-.429 9.045 9.045 0 0 0 -.277-.087z"
                fill="#222d65"
            />
            <path
                d="m9.614 7.699a1.169 1.169 0 0 1 1.159-.991h7.352c.871 0 1.684.057 2.426.177a9.757 9.757 0 0 1 1.481.353c.365.121.704.264 1.017.429.368-2.347-.003-3.945-1.272-5.392-1.399-1.593-3.924-2.275-7.155-2.275h-9.38c-.66 0-1.223.48-1.325 1.133l-3.907 24.765a.806.806 0 0 0 .795.932h5.791l1.454-9.225z"
                fill="#253b80"
            />
            <script xmlns="" />
            <script xmlns="" id="bw-fido2-page-script" />
        </svg>
    }
    href="/integrations/payment-providers/paypal"
  >
    PayPal ist ein weltweit führender Zahlungsanbieter für Online-Zahlungen.
  </Card>

  <Card
    title="SEPA-Lastschrift"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        height={30}
        viewBox="-.28266667 -10.16017133 891.07166667 253.68217133"
        width={60}
    >
        <script xmlns="" />
        <path
            d="m197.703 77.694h-60.973q0-15.005-3.52-20.137-5.44-7.583-30.029-7.587-23.875 0-31.615 4.369-7.722 4.39-7.726 19.079 0 13.294 6.854 17.5 4.918 2.977 13 3.5l12.294.867q39.534 2.616 49.373 3.682 31.263 3.151 45.324 16.621 11.061 10.511 13.176 27.469a191.207 191.207 0 0 1 1.229 22.929q0 29.412-5.612 43.056-10.177 25.043-45.765 31.671-14.915 2.8-45.607 2.806-51.221 0-71.374-6.117-24.73-7.506-32.621-30.4-4.4-12.752-4.381-42.473h60.967v5.069q0 15.861 9.108 20.4a35.743 35.743 0 0 0 15.239 3.316h22.418q17.155 0 21.885-1.762 8.41-3.3 11.042-10.657a40.749 40.749 0 0 0 1.4-11.724q0-16.076-11.724-19.58-4.4-1.384-40.784-3.845-29.231-2.087-40.6-4.03-29.941-5.6-39.9-23.072-8.761-14.857-8.751-44.943 0-22.894 4.73-36.712t15.246-20.986q15.429-11.019 39.439-12.939 19.993-1.742 44.354-1.757 38.379 0 54.7 4.392 39.8 10.692 39.8 59.9 0 4.035-.594 12.1m268.101 165.823v-243.5h122.1q25.12 0 38.307 4.1 30.122 9.433 40.454 38.641 5.343 15.332 5.347 46.154 0 37.05-5.89 53.254-11.748 32.051-48.294 36.87-4.292.723-36.545 1.252l-10.875.362h-39.069v62.867zm65.539-119.35h40.858q19.43-.7 23.666-3.019c3.872-2.129 6.474-6.4 7.768-12.791q1.245-6.379 1.243-18.991 0-15.45-2.477-22.919-3.534-10.483-16.941-12.786-2.657-.348-12.712-.357h-41.4zm280.56 77.268h-87.623l-11.775 42.082h-67.8l73.166-243.5h98.857l74.059 243.5h-66.38zm-13.013-47.434-30.71-105.553-29.8 105.553z"
            fill="#10298e"
        />
        <path
            d="m375.353 34.281a86.153 86.153 0 0 1 67.01 31.954l14.126-30.289a123.816 123.816 0 0 0 -85.328-33.767c-51.64 0-95.814 31.193-113.938 75.344h-27.548l-16.269 34.87h35.436q-.422 4.875-.441 9.772a117.841 117.841 0 0 0 .6 11.849h-17.805l-16.264 34.88h43.13c18.643 43.033 62.265 73.243 113.094 73.243a124.152 124.152 0 0 0 69.076-20.791v-42.745a86.218 86.218 0 0 1 -137.131-9.707h90.309l16.262-34.88h-119.856a87.87 87.87 0 0 1 -.51-21.625h130.453l16.26-34.866h-135.443a86.367 86.367 0 0 1 74.778-43.246"
            fill="#ffbe00"
        />
        <path
            d="m375.353 35.325a85.022 85.022 0 0 1 66.2 31.573l1.053 1.3.714-1.517 14.124-30.29.315-.691-.543-.519a125.936 125.936 0 0 0 -156.172-12.744 121.519 121.519 0 0 0 -44.786 54.692l.965-.649h-28.221l-.278.6-16.264 34.877-.7 1.489h37.084l-1.043-1.136q-.422 4.919-.441 9.86c0 3.914.2 7.944.6 11.956l1.043-1.15h-18.466l-.278.6-16.274 34.877-.691 1.489h44.772l-.96-.631c19.441 44.874 64.213 73.873 114.054 73.873a125.107 125.107 0 0 0 69.648-20.958l.459-.306v-46.093l-1.827 2.087a85.181 85.181 0 0 1 -135.471-9.591l-.872 1.623h90.982l.278-.6 16.264-34.885.7-1.484h-121.51l1.039.9a86.817 86.817 0 0 1 -.506-21.374l-1.043.941h131.126l.278-.6 16.26-34.875.7-1.489h-137.09l.9 1.572a85.721 85.721 0 0 1 73.878-42.727m-74.778 43.246h135.439l-.951-1.489-16.255 34.875.946-.6h-131.4l-.1.946a90.248 90.248 0 0 0 .519 21.876l.139.9h120.76l-.946-1.493-16.26 34.875.941-.6h-92.252l1.067 1.614a87.289 87.289 0 0 0 138.8 9.832l-1.837-.691v42.745l.464-.863a123.084 123.084 0 0 1 -68.484 20.605c-49.011 0-93.022-28.508-112.13-72.617l-.278-.626h-43.821l.955 1.5 16.253-34.901-.951.612h18.971l-.12-1.159c-.394-3.942-.6-7.9-.6-11.743 0-2.954.148-6.126.441-9.683l.093-1.132h-36.568l.941 1.489 16.265-34.875-.941.6h28.243l.264-.649a119.518 119.518 0 0 1 44.03-53.751 123.856 123.856 0 0 1 153.558 12.535l-.232-1.206-14.117 30.297 1.762-.223a87.318 87.318 0 0 0 -143.517 11.432l-.909 1.572z"
            fill="#10298e"
        />
        <script xmlns="" />
        <script xmlns="" id="bw-fido2-page-script" />
    </svg>
    }
    href="/integrations/payment-providers/sepa"
  >
    Die SEPA-Lastschrift-Integration ermöglicht es dir, Lastschrift-Zahlungen in Euro über deine Hausbank zu akzeptieren.
  </Card>

  <Card
    title="Überweisung"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 452.9 101.10000000000001"
        width={60}
        height={30}
    >
        <script xmlns="" />
        <path d="M79.7 0H57.4c0 18.3-8.4 35-23 46l-8.8 6.6 34.2 46.6h28.1L56.4 56.3C71.3 41.5 79.7 21.5 79.7 0zM0 0h22.8v99.2H0zM94.5 0H116v99.2H94.5zM304.6 28.7c-8.2 0-16 2.5-21.2 9.6v-7.7H263v68.6h20.7v-36c0-10.4 7-15.5 15.4-15.5 9 0 14.2 5.4 14.2 15.4v36.2h20.5V55.6c0-16-12.7-26.9-29.2-26.9zM181 30.6V35c-5.8-4-12.8-6.3-20.4-6.3-20 0-36.2 16.2-36.2 36.2s16.2 36.2 36.2 36.2c7.6 0 14.6-2.3 20.4-6.3v4.4h20.5V30.6zm-18.7 51.9c-10.3 0-18.6-7.9-18.6-17.6s8.3-17.6 18.6-17.6 18.6 7.9 18.6 17.6-8.3 17.6-18.6 17.6zM233.3 39.5v-8.9h-21v68.6h21.1v-32c0-10.8 11.7-16.6 19.8-16.6h.2v-20c-8.3 0-16 3.6-20.1 8.9zM397.6 30.6V35c-5.8-4-12.8-6.3-20.4-6.3-20 0-36.2 16.2-36.2 36.2s16.2 36.2 36.2 36.2c7.6 0 14.6-2.3 20.4-6.3v4.4h20.5V30.6zm-18.7 51.9c-10.3 0-18.6-7.9-18.6-17.6s8.3-17.6 18.6-17.6 18.6 7.9 18.6 17.6c.1 9.7-8.3 17.6-18.6 17.6zM434 32.6c0-1-.7-1.6-1.8-1.6h-1.9v5.2h.9v-1.9h1l.8 1.9h1l-.9-2.1c.6-.3.9-.8.9-1.5zm-1.8.8h-1v-1.6h1c.6 0 .9.3.9.8s-.2.8-.9.8z" />
        <path d="M431.9 28.8c-2.7 0-4.9 2.2-4.9 4.9.1 2.7 2.2 4.9 4.9 4.9s4.9-2.2 4.9-4.9-2.2-4.9-4.9-4.9zm0 8.9c-2.2 0-3.9-1.8-3.9-4s1.8-4 3.9-4c2.2 0 3.9 1.8 3.9 4s-1.8 4-3.9 4zM440 74.9c-7.1 0-12.9 5.8-12.9 12.9s5.8 12.9 12.9 12.9 12.9-5.8 12.9-12.9c0-7.2-5.8-12.9-12.9-12.9z" />
        <script xmlns="" />
        <script xmlns="" id="bw-fido2-page-script" />
    </svg>
    }
    href="/integrations/payment-providers/bank-transfer"
  >
    Mit Hilfe von Klarna kannst du den Zahlungsstatus von Überweisungen automatisiert überwachen.
  </Card>
</CardGroup>

## Zahlungsmethoden freigeben

Nach der Einrichtung der Zahlungsanbieter kannst du die Zahlungsmethoden aktivieren, die du deinen Kunden anbieten möchtest.

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods)
  </Step>

  <Step title="Konfiguriere die Zahlungsmethoden">
    <Frame>
      <img alt="Konfiguriere die Zahlungsmethoden" />
    </Frame>

    <Warning>
      <b>Zahlungsmethode deaktivieren</b><br />
      Bei der Deaktivierung einer Zahlungsmethode wird sie aus dem Kunden-Portal und dem Checkout entfernt.
      Bestehende Abonnements, die diese Zahlungsmethode verwenden, werden nicht beeinflusst.
    </Warning>
  </Step>

  <Step title="Die Einstellungen werden automatisch gespeichert" />
</Steps>

<Tip>
  Die freigegebenen Zahlungsmethoden sind sowohl im Kunden-Portal als auch im Checkout verfügbar.
  In naher Zukunft wird es möglich sein, Zahlungsmethoden für bestimmte Produkte und [Checkout-Links](/guide/checkout/introduction) zu konfigurieren.
</Tip>


# Vertriebskanäle
Source: https://docs.fynn.eu/guide/tenant/sales-channels

Mehrere Marken unter einer Organisation: pro Kanal eigenes Logo, eigene Farben, eigene Domain, eigene Zahlungsmethoden und ein eigener Kundenbereich.

Ein Vertriebskanal ist eine deiner Marken. Wenn du unter einer Firma mehrere Marken führst, zum Beispiel „myLife AG" und „myLife Branch", legst du für jede einen eigenen Kanal an. Jeder Kanal tritt mit eigenem Logo, eigenen Farben, eigener Domain und eigenem Kundenbereich auf. Deine Kunden, Abos, Rechnungen und Produkte bleiben dabei gemeinsam, du verwaltest also weiterhin alles an einem Ort.

Jede Organisation startet mit einem Kanal namens `default`. Den legst du nie selbst an, und wenn du nur eine Marke führst, genügt er vollständig. Erst wenn eine zweite Marke dazukommt, legst du einen weiteren Kanal an.

<Info>
  Ein Vertriebskanal trennt das **Auftreten** deiner Marken, nicht deine Daten. Ein Kunde gehört zu einem Kanal und sieht dessen Branding, taucht aber weiterhin in deiner gemeinsamen Kundenliste auf.
</Info>

## Wann sich ein weiterer Kanal lohnt

Ein zweiter Kanal ist sinnvoll, sobald sich deine Marken nach außen unterscheiden sollen, zum Beispiel:

* eigene Domain pro Marke, etwa `shop-a.example.com` und `shop-b.example.com`
* eigenes Logo, eigene Farben oder eigene Rechtstexte
* andere Zahlungsmethoden, etwa nur SEPA-Lastschrift im B2B und zusätzlich Karte und PayPal im B2C
* eigene Coupon-Regeln für B2B und B2C

## Den Kanal wechseln

Die Kanal-Einstellungen findest du in den **Einstellungen** unter **Vertriebskanal**. Über den Switcher oben in der Gruppe wählst du, welchen Kanal du gerade bearbeitest. Alles, was du darunter änderst, gilt für genau diesen Kanal.

<Frame>
  <img alt="Geöffneter Vertriebskanal-Switcher mit Kanalliste und der Aktion Neuer Vertriebskanal" />
</Frame>

Der Wechsel erfolgt ohne Neuladen, und dein zuletzt gewählter Kanal bleibt aktiv, während du zwischen den Seiten navigierst.

## Einen Kanal anlegen

Wähle im Switcher **Neuer Vertriebskanal**. Es genügt ein Marken-Name, alles Weitere konfigurierst du anschließend.

<Frame>
  <img alt="Dialog Neuer Vertriebskanal mit Feld Marken-Name und Erweitert-Bereich" />
</Frame>

Der **Marken-Name** ist der Name, unter dem die Marke auftritt, etwa „Acme B2B". Er erscheint in E-Mails, auf Rechnungen und im Checkout. Optional vergibst du unter **Erweitert** einen technischen Namen wie `b2b-shop`. Lässt du das Feld leer, leitet Fynn ihn aus dem Marken-Namen ab. Später lässt er sich nicht mehr ändern.

Sobald der Kanal angelegt ist, erhält er automatisch eine eigene Adresse, über die sein Checkout sofort erreichbar ist. Eine eigene Domain ist damit optional.

## Was du pro Kanal einstellst

Jeder Kanal hat eigene Seiten für sein Auftreten:

<Columns>
  <Card title="Marke & Domain" icon="tag">
    Name, Website und Telefon der Marke sowie ihre Domain.
  </Card>

  <Card title="Aussehen & Branding" icon="palette">
    Logo und Farben für Checkout, Kundenbereich und Dokumente.
  </Card>

  <Card title="Belegvorlagen" icon="file-lines">
    Logo-Position und Fußzeile der Rechnungen und Angebote.
  </Card>

  <Card title="Zahlungsmethoden" icon="credit-card">
    Welche Zahlarten dieser Kanal im Checkout anbietet.
  </Card>

  <Card title="Coupons" icon="ticket">
    Ob Kunden in diesem Kanal Coupons einlösen können.
  </Card>

  <Card title="Kundenbereich" icon="user">
    Was Kunden im Self-Service sehen und selbst tun dürfen.
  </Card>

  <Card title="E-Mail & Absender" icon="envelope">
    Absender, Sendedomain und das Layout der E-Mails.
  </Card>

  <Card title="Weiterleitungs-URLs" icon="arrow-right-arrow-left">
    Wohin Kunden nach der Zahlung zurückkommen.
  </Card>
</Columns>

## Marke & Domain

Hier pflegst du die Eckdaten der Marke und verwaltest ihre Domain.

<Frame>
  <img alt="Seite Marke und Domain mit Stammdaten und verifizierter eigener Domain" />
</Frame>

Der **Marken-Name** erscheint überall dort, wo der Kunde die Marke sieht: im Checkout, im Absender deiner E-Mails, im Kopf deiner Rechnungen und im Kundenbereich. Die **Website** dient als Rücksprung-Link aus Checkout und Bestätigungs-Mails, das **Telefon** erscheint als Kontakt in E-Mails, Rechnungen und im Kundenbereich. Die Wallet zeigt dir direkt daneben an, wo welche Angabe erscheint.

### Die Standard-Domain

Jeder Kanal hat von Anfang an eine eigene Adresse, zum Beispiel `billing-demo.fynndemo.com`. Über sie ist der Checkout dauerhaft erreichbar. Diese Adresse ist fest und lässt sich nicht ändern oder entfernen, sie bleibt also immer als Rückfallebene bestehen.

### Eine eigene Domain verbinden

Damit Checkout und Kundenbereich unter deiner Marke laufen, verbindest du eine eigene Domain wie `shop.example.com`. Dafür legst du einen einzigen DNS-Eintrag an, das passende TLS-Zertifikat wird automatisch ausgestellt und erneuert. Ein zusätzlicher Nachweis ist nicht nötig.

<Steps>
  <Step title="Domain eintragen">
    Trage deinen Hostnamen ein, zum Beispiel `shop.example.com`, und bestätige. Die Domain erscheint mit dem Status **Ausstehend**, und die Wallet zeigt dir den nötigen DNS-Eintrag an.
  </Step>

  <Step title="DNS-Eintrag setzen">
    Lege bei deinem DNS-Anbieter den angezeigten CNAME-Eintrag an. Den genauen Zielwert siehst du in der Wallet, er sieht etwa so aus:

    | Typ     | Name               | Wert                      |
    | ------- | ------------------ | ------------------------- |
    | `CNAME` | `shop.example.com` | `cname.customerfront.app` |

    Falls die Wallet weitere Einträge zur Bestätigung anzeigt, lege auch diese unverändert an.
  </Step>

  <Step title="Verifizieren">
    Sobald die DNS-Einträge greifen, klickst du auf **Verifizieren**, und die Wallet prüft den Status sofort. Die Prüfung läuft zusätzlich automatisch im Hintergrund: Fynn schaltet die Domain frei, sobald sie bereit ist, auch ohne dein Zutun.
  </Step>
</Steps>

#### Die beiden Status

Die Wallet zeigt dir zwei Angaben zur Domain: die eine, ob die Domain dir zugeordnet ist, die andere, ob ihr Sicherheitszertifikat ausgestellt ist. Erst wenn beides erfüllt ist, wird die Domain produktiv geschaltet.

| Angabe     | Was sie dir sagt                                                | Verlauf                                    |
| ---------- | --------------------------------------------------------------- | ------------------------------------------ |
| **Domain** | Ob der DNS-Eintrag erkannt und die Domain dir zugeordnet wurde. | `Ausstehend`, dann `Verifiziert`           |
| **TLS**    | Ob das Sicherheitszertifikat ausgestellt ist.                   | `Ausstehend`, `Wird geprüft`, dann `Aktiv` |

Sobald das Zertifikat **aktiv** ist, ist die Domain live, und Kunden, die darüber kommen, sehen automatisch diesen Kanal.

<Check>
  **Aktiv** bedeutet: Das Zertifikat ist ausgestellt und deine Domain ist live. Weitere Schritte sind nicht nötig.
</Check>

#### Fehlerbehebung

<AccordionGroup>
  <Accordion title="Der Status bleibt auf „Ausstehend“">
    Der DNS-Eintrag ist noch nicht überall angekommen. Das kann je nach Anbieter ein paar Minuten bis Stunden dauern. Mit `dig CNAME shop.example.com` prüfst du, ob der Eintrag schon greift, danach klickst du erneut auf **Verifizieren**.
  </Accordion>

  <Accordion title="Bei TLS steht „Fehler“">
    Das Zertifikat konnte nicht ausgestellt werden. Meist liegt es an einem abweichenden oder doppelten Eintrag, einem alten A- oder AAAA-Eintrag auf demselben Host oder einer CAA-Regel, die das Zertifikat blockiert. Entferne kollidierende Einträge und setze den CNAME genau auf den angezeigten Wert.
  </Accordion>

  <Accordion title="Eine eigene Domain entfernen">
    Entfernst du die eigene Domain, übernimmt automatisch die Standard-Adresse des Kanals. Der Checkout bleibt durchgehend erreichbar.
  </Accordion>
</AccordionGroup>

<Warning>
  Eine Domain gehört immer zu genau einem Kanal. Über sie entscheidet Fynn, welcher Kanal einen Besucher empfängt, deshalb lässt sie sich nicht an zwei Kanäle gleichzeitig hängen.
</Warning>

## Aussehen & Branding

Hier gibst du dem Kanal sein Gesicht: ein Logo und zwei Farben, die in Checkout, Kundenbereich, E-Mails und Dokumenten auftauchen.

<Frame>
  <img alt="Seite Aussehen und Branding mit Logo-Upload und Farbwählern" />
</Frame>

Für das Logo eignet sich am besten ein transparentes PNG oder SVG. Die **Unternehmens-Farbe** ist die Hauptfarbe der Marke, die **Akzent-Farbe** setzt einzelne Elemente in Szene. Diese Werte überschreiben für diese Marke das, was im `default`-Kanal hinterlegt ist.

## Belegvorlagen

Damit Rechnungen und Angebote zur Marke passen, stellst du hier die **Logo-Position** und die **Fußzeile** der PDFs ein. Die übergreifenden Layout-Vorlagen und das PDF-Styling bleiben weiterhin zentral unter [Aussehen & Design](/guide/tenant/appearance).

<Frame>
  <img alt="Seite Belegvorlagen mit Logo-Position und Fußbereich" />
</Frame>

## Zahlungsmethoden

Hier entscheidest du, welche Zahlarten der Kanal im Checkout zeigt. Lässt du die Auswahl leer, sind alle Methoden erlaubt, deren Anbieter du eingerichtet hast. Wählst du gezielt Methoden aus, beschränkst du den Kanal genau auf diese. So bietet dein B2B-Kanal zum Beispiel nur SEPA-Lastschrift an, während der B2C-Kanal zusätzlich Karte und PayPal zeigt.

<Frame>
  <img alt="Seite Zahlungsmethoden mit der erlaubten Methoden-Auswahl und verbundenen Gateways" />
</Frame>

Wählbar sind nur Methoden, deren Zahlungsanbieter aktiv ist. Welche Anbieter du angebunden hast, verwaltest du übergreifend unter [Zahlungsmethoden](/guide/tenant/payment-methods).

## Coupons

Hier legst du fest, ob deine Kunden in diesem Kanal überhaupt Coupons einlösen können. Steht der Schalter aus, sind Coupons im ganzen Kanal gesperrt, egal was an einem einzelnen Checkout-Link erlaubt ist. Ein Checkout-Link kann Coupons also weiter einschränken, aber nie gegen den Kanal erlauben.

<Frame>
  <img alt="Seite Coupons mit dem Schalter für den ganzen Kanal" />
</Frame>

| Kanal    | Checkout-Link | Coupon einlösbar        |
| -------- | ------------- | ----------------------- |
| erlaubt  | erlaubt       | ja                      |
| erlaubt  | gesperrt      | nein                    |
| gesperrt | erlaubt       | nein, der Kanal gewinnt |
| gesperrt | gesperrt      | nein                    |

Bei neuen Kanälen sind Coupons standardmäßig erlaubt. Schaltest du sie aus, sind sie in keinem Checkout-Link dieses Kanals mehr einlösbar.

## Kundenbereich

Im Kundenbereich melden sich deine Kunden an und verwalten ihre Daten selbst. Hier bestimmst du, was sie dort sehen und dürfen.

<Frame>
  <img alt="Kundenbereich-Einstellungen mit Aktivierungs-Schalter, sichtbaren Bereichen und Kündigungsregeln" />
</Frame>

Zuerst schaltest du den Kundenbereich für diesen Kanal ein oder aus. Ist er deaktiviert, können sich Kunden dieses Kanals nicht anmelden. Darunter bestimmst du, welche Bereiche sichtbar sind, etwa Rechnungen, Adressen, Zahlungsmethoden, laufende Abos oder die Ansprechpartner, und ob Kunden ihre Abos selbst kündigen dürfen, sofort oder erst zum Ende der Testphase. Unter **Rechtstexte** hinterlegst du die Links zu AGB und Datenschutz, die im Checkout und im Kundenbereich erscheinen.

Welches Branding und welchen Kundenbereich ein Kunde sieht, ergibt sich aus der Domain, über die er zugreift.

## E-Mail & Absender

Damit E-Mails zur Marke passen, stellst du hier den **Absender** ein, also den Namen, unter dem deine Mails verschickt werden. Über die **Sendedomain** verschickst du aus deiner eigenen Adresse statt über Fynn (mehr dazu unter [Eigene E-Mail-Domain](/guide/notifications/custom-email-domain)). Mit **Kopf und Fuß** der Mail-Vorlage gibst du den E-Mails dieses Kanals ihren Rahmen.

<Frame>
  <img alt="Seite E-Mail und Absender mit Absender, Sendedomain und Mail-Vorlage" />
</Frame>

## Weiterleitungs-URLs

Nach der Zahlung schickst du den Kunden zurück auf eine eigene Seite, zum Beispiel auf deine Dankesseite. Lässt du ein Feld leer, landet der Kunde auf der Standardseite der Kundenfront.

<Frame>
  <img alt="Seite Weiterleitungs-URLs mit den Ziel-URLs je Zahlungsstatus" />
</Frame>

| Feld         | Wohin der Kunde kommt                                      |
| ------------ | ---------------------------------------------------------- |
| Erfolg       | Nach erfolgreicher Zahlung.                                |
| Abbruch      | Wenn der Kunde beim Anbieter abbricht.                     |
| Fehler       | Wenn der Anbieter ablehnt.                                 |
| Ausstehend   | Solange die Zahlung noch läuft, etwa bei SEPA-Lastschrift. |
| API-Rückkehr | Nach einer per API eingerichteten Zahlungsmethode.         |

Mehr zur API-Rückkehr-URL steht in der [Entwickler-Dokumentation](/guide/developers/sales-channels#weiterleitungs-urls-und-returnurl).

## Welchen Kanal ein Kunde sieht

Das übernimmt Fynn automatisch. Kommt ein Kunde über die Domain eines Kanals, sieht er dessen Marke. Im Checkout bringt der Warenkorb seinen Kanal bereits mit. Lässt sich nichts davon eindeutig zuordnen, greift der `default`-Kanal. Die genauen Regeln samt Headern findest du in der [Entwickler-Dokumentation](/guide/developers/sales-channels#kanal-auflösung).

## Was gemeinsam bleibt

Kunden, Abos, Rechnungen, Produkte und Preise gehören weiterhin der ganzen Organisation, nicht einem einzelnen Kanal. Jeder Kunde ist genau einem Kanal zugeordnet, und du kannst diese Zuordnung jederzeit ändern. Sie entscheidet nur darüber, welches Branding der Kunde in Bestätigungen und im Kundenbereich sieht.

## Einen Kanal löschen

Einen Kanal löschst du, sobald keine Kunden, Checkout-Links oder Preispläne mehr auf ihn zeigen. Solange noch etwas darauf verweist, ordnest du es zuerst einem anderen Kanal zu, danach lässt sich der Kanal löschen. Der `default`-Kanal bleibt immer bestehen, er ist der Anker deiner Organisation.

## Für Entwickler

<Card title="Vertriebskanäle über die API" icon="code" href="/guide/developers/sales-channels">
  Kanal-Auflösung, das Feld am Kunden, die Endpunkte für Kanäle und eigene Domains und das Webhook-Verhalten, mit Codebeispielen.
</Card>


# Suche
Source: https://docs.fynn.eu/guide/tenant/search

Finde schnell und einfach Kunden, Rechnungen, Abonnements und mehr — mit Vorschau-Panels und Kontext-Hervorhebung.

Die globale Suche ermöglicht es dir, schnell und einfach die gewünschten Informationen zu finden. Du kannst nach Kunden, Abonnements, Rechnungen, Produkten, Transaktionen und vielem mehr suchen.

## Suche öffnen

Öffne die globale Suche über einen der folgenden Wege:

* **Tastenkombination**: `Ctrl+K` (Windows/Linux) oder `Cmd+K` (Mac)
* **Suchfeld**: Klicke auf das Suchfeld in der oberen Navigation

## Vorschau-Panels

Beim Navigieren durch die Suchergebnisse wird rechts ein **Vorschau-Panel** angezeigt. Dort siehst du die wichtigsten Informationen zum ausgewählten Ergebnis — ohne die aktuelle Seite zu verlassen.

**Vorschau verfügbar für:**

| Bereich                   | Angezeigte Informationen                        |
| ------------------------- | ----------------------------------------------- |
| **Kunden**                | Name, Kundennummer, Adresse, aktive Abonnements |
| **Rechnungen**            | Betrag, Status, Kunde, Positionen               |
| **Abonnements**           | Produkte, Status, nächste Abrechnung            |
| **Produkte & Preispläne** | Details und Konfiguration                       |
| **Transaktionen**         | Betrag, Status, Zahlungsmethode                 |
| **Mahnungen**             | Stufe, offener Betrag, verknüpfte Rechnung      |
| **Rabatte**               | Konfiguration und Einlösungen                   |
| **Aufgaben**              | Status und Details                              |

## Kontext-Hervorhebung

Die Suchergebnisse zeigen an, **in welchem Feld** der Suchbegriff gefunden wurde. So erkennst du auf einen Blick, ob der Treffer im Namen, in der Kundennummer, in der Adresse oder in einem anderen Feld liegt.

## Suchbare Felder

Die Suche durchsucht je nach Bereich unterschiedliche Felder:

* **Kunden**: Name, Kundennummer, E-Mail, Rechnungsadresse, Lieferadresse
* **Rechnungen**: Rechnungsnummer, Kundenname
* **Abonnements**: Abonnementnummer, Kundenname, Produktbezeichnung
* **Produkte**: Produktname, Artikelnummer
* **Transaktionen**: Transaktionsnummer, Kundenname

<Tip>
  Nutze die Pfeiltasten, um durch die Ergebnisse zu navigieren, und drücke `Enter`, um das ausgewählte Ergebnis zu öffnen.
</Tip>


# Web-Oberfläche anpassen
Source: https://docs.fynn.eu/guide/tenant/ui-defaults

Passe die Web-Oberfläche an, um Arbeitsprozesse zu optimieren.

## Standardwerte Web-App

Um die Arbeit mit der Web-App zu erleichtern, kann für einige Auswahlfelder ein Standardwert festgelegt werden.
Dies erleichtert den Arbeitsprozess und reduziert die Anzahl der manuellen Eingaben.

Um Standardwerte zusetzen, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Allgemein](https://app.fynn.eu/settings)
  </Step>

  <Step title="Scrolle zum Bereich Standardwerte" />

  <Step title="Wähle die Standardwerte aus">
    <Frame>
      <img alt="Standardwerte" />
    </Frame>
  </Step>

  <Step title="Klicke auf Speichern" />
</Steps>

Anschließend werden in den entsprechenden Auswahlfeldern die Standardwerte vorausgewählt.

## Schreibgeschützte Kunden

In der Web-Oberfläche können Kunden grundsätzlich schreibgeschützt gesetzt werden.
Dies bedeutet, dass keine Änderungen an den Kundendaten vorgenommen werden und keine Kunden angelegt werden können.

Dies ist bspw. sinnvoll, wenn du verhindern möchtest, dass Mitarbeiter Kunden-Stammdaten ändern die über eine Schnittstelle mit der API synchronisiert werden.

<Info>
  Bitte beachte, dass die Einstellung nur für Benutzer der Web-Oberfläche gilt. Für API-Schlüssel können weiterhin Änderungen an den Kunden vorgenommen werden.
</Info>

Um einen Kunden schreibgeschützt zu setzen, folge diesen Schritten:

<Steps>
  <Step title="Öffne den Einstellungen">
    Gehe hierzu zu [Einstellungen > Allgemein](https://app.fynn.eu/settings)
  </Step>

  <Step title="Scrolle zum Bereich Web-Oberfläche" />

  <Step title="Setze den Kunden schreibgeschützt">
    <Frame>
      <img alt="Kunde schreibgeschützt" />
    </Frame>
  </Step>

  <Step title="Klicke auf Speichern" />
</Steps>


# Benutzer & Berechtigungen
Source: https://docs.fynn.eu/guide/tenant/users

Lerne, wie du Benutzer zu deiner Organisation einlädst, ihre Berechtigungen verwaltest und sie sperrst oder entsperrst.

## Benutzer einladen

Du kannst unbegrenzt viele Benutzer zu deiner Organisation einladen.

Um Benutzer aus deiner Organisation einzuladen, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Benutzer](https://app.fynn.eu/settings/users)
  </Step>

  <Step title="Füge einen neuen Benutzer hinzu, indem du auf das + Symbol klickst">
    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Wähle die Rolle des Benutzers aus">
    Wähle zwischen den Rollen `Administrator`, `Mitarbeiter` und `Lesend` aus.

    * `Administrator`: Hat Lese- und Schreibzugriff auf alle Funktionen und Ressourcen, sowie auf die Einstellungen.
    * `Mitarbeiter`: Hat Lese- und Schreibzugriff auf alle Funktionen und Ressourcen, jedoch keinen Zugriff auf die Einstellungen.
    * `Lesend`: Hat nur Lesezugriff auf alle Ressourcen.
  </Step>

  <Step title="Klicke auf Benutzer einladen" />
</Steps>

Anschließend erhält der Benutzer eine E-Mail-Einladung, um sich bei deiner Organisation mit einem Passwort zu registrieren.

## Benutzereinladung entfernen

Um eine Benutzereinladung aus deiner Organisation zu entfernen, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Benutzer](https://app.fynn.eu/settings/users)
  </Step>

  <Step title="Klicke auf das Mülleimer-Symbol neben der Benutzereinladung, die du entfernen möchtest" />

  <Step title="Klicke auf das Papierkorb-Symbol, um die Benutzereinladung zu entfernen">
    Anschließend muss die Aktion bestätigt werden.

    <Note>
      Die Einladung wird aus deiner Organisation entfernt und der Benutzer kann sich nicht mehr registrieren.
    </Note>
  </Step>
</Steps>

## Berechtigungen

Fynn wird mit drei Standardrollen ausgeliefert, die du für deine Benutzer verwenden kannst. Diese Rollen sind:

| Rolle         | Beschreibung                                                                                                                                                                                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Administrator | Hat Lese- und Schreibzugriff auf alle Funktionen und Ressourcen, sowie auf die Einstellungen.                                                                                                                                                                                                                                  |
| Buchhaltung   | Hat Lese- und Schreibzugriff auf folgende Bereiche:<br />\* Kunden<br />\* Partner<br />\* Produkte<br />\* Preisaktualisierung<br />\* Abo-Feature-Zuweisung<br />\* Abonnements<br />\* Warenkorb<br />\* gesamte Rechnungsstellung<br />\* gesamter Buchhaltungsbereich<br />\* Mahnwesen<br />\* Einstellungen Buchhaltung |
| Benutzer      | Hat Lese- und Schreibzugriff auf folgende Bereiche:<br />\* Kunden<br />\* Partner<br />\* Produkte<br />\* Abo-Feature-Zuweisung<br />\* Abbonements<br />\* Warenkorb<br />\* Angebote<br />\* Rechnungen<br />\* Zahlungen<br />\* Berichte                                                                                 |

Die Rollen können für jeden Benutzer individuell angepasst werden.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Öffne die Einstellungen">
        Gehe hierzu zu [Einstellungen > Benutzer](https://app.fynn.eu/settings/users)
      </Step>

      <Step title="Klicke auf das Auswahlfeld der Rolle des Benutzers">
        <Frame>
          <img />
        </Frame>
      </Step>

      <Step title="Wähle die neue Rolle des Benutzers aus" />

      <Step title="Rolle erfolgreich geändert 🎉">
        Die Rolle ist nun sofort geändert und der Benutzer hat die entsprechenden Berechtigungen nach der nächsten Navigation in der Anwendung.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Rolle anpassen](/api-reference/account/update-account-role) Endpunkt.

    ```bash theme={null}
    PUT /accounts/{accountId}/role
    ```
  </Tab>
</Tabs>

<Info>
  Du kannst die Berechtigungen für deinen Account nicht selbst ändern. Wenn du die Berechtigungen für deinen Account ändern möchtest, kontaktiere bitte einen anderen Administrator deiner Organisation.
</Info>

## Benutzer sperren

Wenn ein Benutzer keinen Zugriff mehr auf die Organisation haben soll, kann der Benutzer gesperrt werden.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Öffne die Einstellungen">
        Gehe hierzu zu [Einstellungen > Benutzer](https://app.fynn.eu/settings/users)
      </Step>

      <Step title="Klicke auf das Schloss-Symbol, um den Benutzer zu sperren">
        <Note>
          Der Benutzer wird gesperrt und kann nicht mehr auf die Daten zugreifen.
          In den Audit-Logs wird weiterhin der Benutzer referenziert, um die Historie der Änderungen zu dokumentieren.
          Der Benutzer erhält keine Benachrichtigung über die Sperrung.
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Benutzer sperren](/api-reference/account/deactivate-account) Endpunkt.

    ```bash theme={null}
    PUT /accounts/{accountId}/deactivate
    ```
  </Tab>
</Tabs>

## Benutzer entsperren

Wenn ein Benutzer wieder Zugriff auf die Organisation haben soll, kann der Benutzer entsperrt werden.

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Öffne die Einstellungen">
        Gehe hierzu zu [Einstellungen > Benutzer](https://app.fynn.eu/settings/users)
      </Step>

      <Step title="Klicke auf das Schloss-Symbol, um den Benutzer zu entsperren">
        <Note>
          Der Benutzer wird entsperrt und kann wieder auf die Daten zugreifen.
          Der Benutzer erhält keine Benachrichtigung über die Entsperrung.
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    Verwende hierfür den [Benutzer entsperren](/api-reference/account/reactivate-account) Endpunkt.

    ```bash theme={null}
    PUT /accounts/{accountId}/reactivate
    ```
  </Tab>
</Tabs>

## Rollen anlegen

Fynn bietet die Möglichkeit, benutzerdefinierte Rollen zu erstellen, um spezifische Berechtigungen für verschiedene Benutzergruppen festzulegen.

<Steps>
  <Step title="Öffne die Einstellungen">
    Gehe hierzu zu [Einstellungen > Benutzer](https://app.fynn.eu/settings/users)
  </Step>

  <Step title="Klicke auf das im Bereich Rollen auf der rechten Seite auf Rolle hinzufügen">
    <Frame>
      <img />
    </Frame>

    Wähle einen Namen für die Rolle, hake alle Berechtigungen für diese Rollen an und klicke auf "Rolle hinzufügen".
  </Step>

  <Step title="Rolle verwenden">
    Die neue Rolle kann jetzt einem bestehenden oder neuen Benutzer hinzugefügt werden.
  </Step>
</Steps>

## Rollen bearbeiten

<Note>
  Rollen können aktuell nicht bearbeitet werden. Wenn du eine Rolle bearbeiten möchtest, kontaktiere bitte den Support.
</Note>


# Webhooks
Source: https://docs.fynn.eu/guide/webhooks/introduction

Konfiguriere Webhooks und erhalte Benachrichtigungen.

<Frame>
  <img alt="Fynn Webhooks Einstellungen" />
</Frame>

Mit Webhooks kannst du externe Systeme in Echtzeit über Ereignisse in Fynn benachrichtigen lassen. Webhooks werden per `POST`-Request an deine hinterlegte URL gesendet und enthalten strukturierte JSON-Daten zum jeweiligen Ereignis.

Webhooks lassen sich unter [**Einstellungen → Webhooks**](https://app.fynn.eu/settings/webhooks) konfigurieren.

***

## Sicherheit: `X-Webhook-Signature`

Jede Webhook-Anfrage enthält einen Header `X-Webhook-Signature`, der wie folgt generiert wird:

```
hash_hmac('sha256', $body, $webhookSecret)
```

* `$body`: Der **ungeänderte JSON Body** der Webhook-Anfrage (als String)
* `$webhookSecret`: Dein geheimer Schlüssel für diesen Webhook

Den Secret findest du unter:
[**Einstellungen → Webhooks → Details**](https://app.fynn.eu/settings/webhooks)

<Warning>
  Wir empfehlen dringend, die Signatur zu validieren, um sicherzustellen, dass die Anfrage wirklich von Fynn stammt.
</Warning>

***

### Beispiele

<Tabs>
  <Tab title="PHP">
    ```php theme={null}
    $webhookSecret = 'dein_webhook_secret';
    $body = file_get_contents('php://input');
    $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

    $expectedSignature = hash_hmac('sha256', $body, $webhookSecret);

    if (!hash_equals($expectedSignature, $signature)) {
        http_response_code(401);
        exit('Invalid signature');
    }

    // Verarbeitung ...
    http_response_code(200);
    echo 'OK';
    ```
  </Tab>

  <Tab title=".NET (C#)">
    ```csharp theme={null}
    using System.Security.Cryptography;
    using System.Text;

    string body = await new StreamReader(Request.Body).ReadToEndAsync();
    string signature = Request.Headers["X-Webhook-Signature"];
    string secret = "dein_webhook_secret";

    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
    {
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
        var expected = BitConverter.ToString(hash).Replace("-", "").ToLower();

        if (expected != signature)
        {
            return Results.Unauthorized();
        }
    }

    // Verarbeitung ...
    return Results.Ok();
    ```
  </Tab>

  <Tab title="Node.JS">
    ```js theme={null}
        const crypto = require('crypto');
        const express = require('express');
        const app = express();

        app.use(express.text({ type: 'application/json' }));

        app.post('/webhook', (req, res) => {
            const webhookSecret = 'dein_webhook_secret';
            const signature = req.headers['x-webhook-signature'];
            const expected = crypto
            .createHmac('sha256', webhookSecret)
            .update(req.body)
            .digest('hex');

            if (signature !== expected) {
                return res.status(401).send('Invalid signature');
            }

            // Verarbeitung ...
            res.send('OK');
        });
    ```
  </Tab>
</Tabs>

## Unterstützte Events

### Produkt

* `product.created`
* `product.updated`
* `product.deleted`
* `product.archived`

### Rabattcodes

* `coupon.created`
* `coupon.updated`
* `coupon.deleted`
* `coupon.toggled`

### Kunden

* `customer.created`
* `customer.updated`
* `customer.archived`
* `customer.unarchived`
* `customer.deleted`
* `customer.merged` — Wird ausgelöst, wenn mehrere Kunden zu einem zusammengeführt wurden.
* `customer.parent.assigned` — Wird ausgelöst, wenn ein Parent-Kunde in der [Organisationsstruktur](/guide/customers/organization-hierarchy) zugewiesen wurde.
* `customer.parent.removed` — Wird ausgelöst, wenn ein Parent-Kunde aus der [Organisationsstruktur](/guide/customers/organization-hierarchy) entfernt wurde.
* `payment_method.created`
* `payment_method.updated`

### Rechnungen

* `invoice.created`
* `invoice.finalized` — Wird ausgelöst, nachdem die Rechnung finalisiert und die Zahlungsabwicklung initialisiert wurde. Die Rechnung hat zu diesem Zeitpunkt den Status `STATUS_UNPAID`.
* `invoice.credited`
* `invoice.updated`
* `invoice.refunded`
* `invoice.canceled`
* `invoice.paid`
* `invoice.closed`
* `invoice.unpaid`
* `invoice.remindered`
* `invoice.requires_approval`
* `invoice.payment_method.updated`
* `invoice.pdf.generation_requested`
* `invoice.letter.dispatched` — Wird ausgelöst, sobald eine Rechnung als Brief an den Druckdienstleister übergeben wurde.
* `invoice.letter.delivered` — Wird ausgelöst, sobald die Zustellung des Briefs bestätigt ist.

### Preispläne

* `price_plan.archived`

### Abonnements

* `subscription.activated`
* `subscription.billed`
* `subscription.created`
* `subscription.changed`
* `subscription.invoice_address.updated`
* `subscription.delivery_address.updated`
* `subscription.payment_method.updated`
* `subscription.item.instant_metered`
* `subscription.item.metered`
* `subscription.item.quantity_changed`
* `subscription.products.ordered`
* `subscription.trial_expired`
* `subscription.trial_extended`
* `subscription.updated`
* `subscription.paused`
* `subscription.voided`
* `subscription.resumed`
* `subscription.canceled`
* `subscription.cancellation_revoked`
* `subscription.terminated`
* `subscription.phase.created`
* `subscription.phase.completed`
* `subscription.transferred`
* `subscription_item.terminated`

### Mahnwesen

* `dunning_document.created`
* `dunning_document.paid`
* `dunning_document.canceled`

### Warenkorb

* `cart.completed`
* `cart.paid`

### Bankkonten

* `bank_account.synced`

### Guthaben-Auszahlung

* `wallet.payout.executed`: Wird ausgelöst, wenn eine Guthaben-[Auszahlung](/guide/invoices/wallet-payout) von der Bank ausgeführt und über den Kontoumsatz bestätigt wurde.
* `wallet.payout.failed`: Wird ausgelöst, wenn die Einreichung einer Guthaben-Auszahlung fehlgeschlagen ist. Das Guthaben wurde automatisch zurückgebucht.

### Features & Entitlements

* `feature.created`
* `feature.activated`
* `feature.archived`
* `entitlement.state.updated`

***

## Hinweise

Die Events werden bei einem Fehler **bis zu 3x** wiederholt.


# Übersicht
Source: https://docs.fynn.eu/integrations/overview

Wir bieten dir eine Vielzahl von Integrationen zu 3rd-Party-Tools und -Services, um die Funktionalität der Fynn-Plattform zu erweitern.

## Zahlungsanbieter

<CardGroup>
  <Card
    title="GoCardless"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        xmlnsXlink="http://www.w3.org/1999/xlink"
        version="1.1"
        id="Layer_1"
        x="0px"
        y="0px"
        viewBox="0 0 1000 1000"
        style={{ enableBackground: "new 0 0 1000 1000" }}
        xmlSpace="preserve"
    >
        <style
            type="text/css"
            dangerouslySetInnerHTML={{
                __html: "\n\t.st0{fill:#F1F252;}\n\t.st1{fill:#1C1B18;}\n"
            }}
        />
        <rect className="st0" width={1000} height={1000} rx={256} />
        <path
            className="st1"
            d="M507.9,242.1c55.2,0,86.2,9,86.2,9l91.7,187.2l-0.8,0.8l-118-70.4c-68.4-40.7-118-62.1-158.4-60.5  c-42.7,0.8-68.3,35.2-68.3,85c1.5,127.5,122.7,284.5,243.1,284.5c49.1,0,74.7-15.8,89.7-34.9L494.8,447.3v-0.8h244.8  c3.3,17.5,5.2,35.3,5.4,53.1c0,143.1-109.5,258.3-244.6,258.3C364.7,757.9,255,642.7,255,499.6C254.8,357.3,364.3,242.1,507.9,242.1  z"
        />
    </svg>
    }
    href="/integrations/payment-providers/go-cardless"
  >
    GoCardless ist der Global-Leader für Lastschrift-Zahlungen.
  </Card>

  <Card
    title="Stripe Payments"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        width={50}
        height={30}
        viewBox="0 0 512 214"
        preserveAspectRatio="xMidYMid"
    >
        <script xmlns="" />
        <path
            d="M35.982 83.484c0-5.546 4.551-7.68 12.09-7.68 10.808 0 24.461 3.272 35.27 9.103V51.484c-11.804-4.693-23.466-6.542-35.27-6.542C19.2 44.942 0 60.018 0 85.192c0 39.252 54.044 32.995 54.044 49.92 0 6.541-5.688 8.675-13.653 8.675-11.804 0-26.88-4.836-38.827-11.378v33.849c13.227 5.689 26.596 8.106 38.827 8.106 29.582 0 49.92-14.648 49.92-40.106-.142-42.382-54.329-34.845-54.329-50.774zm96.142-66.986l-34.702 7.395-.142 113.92c0 21.05 15.787 36.551 36.836 36.551 11.662 0 20.195-2.133 24.888-4.693V140.8c-4.55 1.849-27.022 8.391-27.022-12.658V77.653h27.022V47.36h-27.022l.142-30.862zm71.112 41.386L200.96 47.36h-30.72v124.444h35.556V87.467c8.39-10.951 22.613-8.96 27.022-7.396V47.36c-4.551-1.707-21.191-4.836-29.582 10.524zm38.257-10.524h35.698v124.444h-35.698V47.36zm0-10.809l35.698-7.68V0l-35.698 7.538V36.55zm109.938 8.391c-13.938 0-22.898 6.542-27.875 11.094l-1.85-8.818h-31.288v165.83l35.555-7.537.143-40.249c5.12 3.698 12.657 8.96 25.173 8.96 25.458 0 48.64-20.48 48.64-65.564-.142-41.245-23.609-63.716-48.498-63.716zm-8.533 97.991c-8.391 0-13.37-2.986-16.782-6.684l-.143-52.765c3.698-4.124 8.818-6.968 16.925-6.968 12.942 0 21.902 14.506 21.902 33.137 0 19.058-8.818 33.28-21.902 33.28zM512 110.08c0-36.409-17.636-65.138-51.342-65.138-33.85 0-54.33 28.73-54.33 64.854 0 42.808 24.179 64.426 58.88 64.426 16.925 0 29.725-3.84 39.396-9.244v-28.445c-9.67 4.836-20.764 7.823-34.844 7.823-13.796 0-26.027-4.836-27.591-21.618h69.547c0-1.85.284-9.245.284-12.658zm-70.258-13.511c0-16.071 9.814-22.756 18.774-22.756 8.675 0 17.92 6.685 17.92 22.756h-36.694z"
            fill="#6772E5"
        />
        <script xmlns="" />
        <script xmlns="" id="bw-fido2-page-script" />
    </svg>}
    href="/integrations/payment-providers/stripe"
  >
    Stripe ist ein Zahlungsanbieter, der es Unternehmen ermöglicht, Kreditkarten-Zahlungen zu akzeptieren.
  </Card>

  <Card
    title="PayPal"
    icon={
        <svg
            xmlns="http://www.w3.org/2000/svg"
            height={30}
            viewBox="-.02682843 0 123.63183286 30.17842908"
            width={75}
        >
            <script xmlns="" />
            <path
                d="m46.211 6.749h-6.839a.95.95 0 0 0 -.939.802l-2.766 17.537a.57.57 0 0 0 .564.658h3.265a.95.95 0 0 0 .939-.803l.746-4.73a.95.95 0 0 1 .938-.803h2.165c4.505 0 7.105-2.18 7.784-6.5.306-1.89.013-3.375-.872-4.415-.972-1.142-2.696-1.746-4.985-1.746zm.789 6.405c-.374 2.454-2.249 2.454-4.062 2.454h-1.032l.724-4.583a.57.57 0 0 1 .563-.481h.473c1.235 0 2.4 0 3.002.704.359.42.469 1.044.332 1.906zm19.654-.079h-3.275a.57.57 0 0 0 -.563.481l-.145.916-.229-.332c-.709-1.029-2.29-1.373-3.868-1.373-3.619 0-6.71 2.741-7.312 6.586-.313 1.918.132 3.752 1.22 5.031.998 1.176 2.426 1.666 4.125 1.666 2.916 0 4.533-1.875 4.533-1.875l-.146.91a.57.57 0 0 0 .562.66h2.95a.95.95 0 0 0 .939-.803l1.77-11.209a.568.568 0 0 0 -.561-.658zm-4.565 6.374c-.316 1.871-1.801 3.127-3.695 3.127-.951 0-1.711-.305-2.199-.883-.484-.574-.668-1.391-.514-2.301.295-1.855 1.805-3.152 3.67-3.152.93 0 1.686.309 2.184.892.499.589.697 1.411.554 2.317zm22.007-6.374h-3.291a.954.954 0 0 0 -.787.417l-4.539 6.686-1.924-6.425a.953.953 0 0 0 -.912-.678h-3.234a.57.57 0 0 0 -.541.754l3.625 10.638-3.408 4.811a.57.57 0 0 0 .465.9h3.287a.949.949 0 0 0 .781-.408l10.946-15.8a.57.57 0 0 0 -.468-.895z"
                fill="#253b80"
            />
            <path
                d="m94.992 6.749h-6.84a.95.95 0 0 0 -.938.802l-2.766 17.537a.569.569 0 0 0 .562.658h3.51a.665.665 0 0 0 .656-.562l.785-4.971a.95.95 0 0 1 .938-.803h2.164c4.506 0 7.105-2.18 7.785-6.5.307-1.89.012-3.375-.873-4.415-.971-1.142-2.694-1.746-4.983-1.746zm.789 6.405c-.373 2.454-2.248 2.454-4.062 2.454h-1.031l.725-4.583a.568.568 0 0 1 .562-.481h.473c1.234 0 2.4 0 3.002.704.359.42.468 1.044.331 1.906zm19.653-.079h-3.273a.567.567 0 0 0 -.562.481l-.145.916-.23-.332c-.709-1.029-2.289-1.373-3.867-1.373-3.619 0-6.709 2.741-7.311 6.586-.312 1.918.131 3.752 1.219 5.031 1 1.176 2.426 1.666 4.125 1.666 2.916 0 4.533-1.875 4.533-1.875l-.146.91a.57.57 0 0 0 .564.66h2.949a.95.95 0 0 0 .938-.803l1.771-11.209a.571.571 0 0 0 -.565-.658zm-4.565 6.374c-.314 1.871-1.801 3.127-3.695 3.127-.949 0-1.711-.305-2.199-.883-.484-.574-.666-1.391-.514-2.301.297-1.855 1.805-3.152 3.67-3.152.93 0 1.686.309 2.184.892.501.589.699 1.411.554 2.317zm8.426-12.219-2.807 17.858a.569.569 0 0 0 .562.658h2.822c.469 0 .867-.34.939-.803l2.768-17.536a.57.57 0 0 0 -.562-.659h-3.16a.571.571 0 0 0 -.562.482z"
                fill="#179bd7"
            />
            <path
                d="m7.266 29.154.523-3.322-1.165-.027h-5.563l3.866-24.513a.316.316 0 0 1 .314-.268h9.38c3.114 0 5.263.648 6.385 1.927.526.6.861 1.227 1.023 1.917.17.724.173 1.589.007 2.644l-.012.077v.676l.526.298a3.69 3.69 0 0 1 1.065.812c.45.513.741 1.165.864 1.938.127.795.085 1.741-.123 2.812-.24 1.232-.628 2.305-1.152 3.183a6.547 6.547 0 0 1 -1.825 2c-.696.494-1.523.869-2.458 1.109-.906.236-1.939.355-3.072.355h-.73c-.522 0-1.029.188-1.427.525a2.21 2.21 0 0 0 -.744 1.328l-.055.299-.924 5.855-.042.215c-.011.068-.03.102-.058.125a.155.155 0 0 1 -.096.035z"
                fill="#253b80"
            />
            <path
                d="m23.048 7.667c-.028.179-.06.362-.096.55-1.237 6.351-5.469 8.545-10.874 8.545h-2.752c-.661 0-1.218.48-1.321 1.132l-1.409 8.936-.399 2.533a.704.704 0 0 0 .695.814h4.881c.578 0 1.069-.42 1.16-.99l.048-.248.919-5.832.059-.32c.09-.572.582-.992 1.16-.992h.73c4.729 0 8.431-1.92 9.513-7.476.452-2.321.218-4.259-.978-5.622a4.667 4.667 0 0 0 -1.336-1.03z"
                fill="#179bd7"
            />
            <path
                d="m21.754 7.151a9.757 9.757 0 0 0 -1.203-.267 15.284 15.284 0 0 0 -2.426-.177h-7.352a1.172 1.172 0 0 0 -1.159.992l-1.564 9.906-.045.289a1.336 1.336 0 0 1 1.321-1.132h2.752c5.405 0 9.637-2.195 10.874-8.545.037-.188.068-.371.096-.55a6.594 6.594 0 0 0 -1.017-.429 9.045 9.045 0 0 0 -.277-.087z"
                fill="#222d65"
            />
            <path
                d="m9.614 7.699a1.169 1.169 0 0 1 1.159-.991h7.352c.871 0 1.684.057 2.426.177a9.757 9.757 0 0 1 1.481.353c.365.121.704.264 1.017.429.368-2.347-.003-3.945-1.272-5.392-1.399-1.593-3.924-2.275-7.155-2.275h-9.38c-.66 0-1.223.48-1.325 1.133l-3.907 24.765a.806.806 0 0 0 .795.932h5.791l1.454-9.225z"
                fill="#253b80"
            />
            <script xmlns="" />
            <script xmlns="" id="bw-fido2-page-script" />
        </svg>
    }
    href="/integrations/payment-providers/paypal"
  >
    PayPal ist ein weltweit führender Zahlungsanbieter für Online-Zahlungen.
  </Card>

  <Card
    title="SEPA-Lastschrift"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        height={30}
        viewBox="-.28266667 -10.16017133 891.07166667 253.68217133"
        width={60}
    >
        <script xmlns="" />
        <path
            d="m197.703 77.694h-60.973q0-15.005-3.52-20.137-5.44-7.583-30.029-7.587-23.875 0-31.615 4.369-7.722 4.39-7.726 19.079 0 13.294 6.854 17.5 4.918 2.977 13 3.5l12.294.867q39.534 2.616 49.373 3.682 31.263 3.151 45.324 16.621 11.061 10.511 13.176 27.469a191.207 191.207 0 0 1 1.229 22.929q0 29.412-5.612 43.056-10.177 25.043-45.765 31.671-14.915 2.8-45.607 2.806-51.221 0-71.374-6.117-24.73-7.506-32.621-30.4-4.4-12.752-4.381-42.473h60.967v5.069q0 15.861 9.108 20.4a35.743 35.743 0 0 0 15.239 3.316h22.418q17.155 0 21.885-1.762 8.41-3.3 11.042-10.657a40.749 40.749 0 0 0 1.4-11.724q0-16.076-11.724-19.58-4.4-1.384-40.784-3.845-29.231-2.087-40.6-4.03-29.941-5.6-39.9-23.072-8.761-14.857-8.751-44.943 0-22.894 4.73-36.712t15.246-20.986q15.429-11.019 39.439-12.939 19.993-1.742 44.354-1.757 38.379 0 54.7 4.392 39.8 10.692 39.8 59.9 0 4.035-.594 12.1m268.101 165.823v-243.5h122.1q25.12 0 38.307 4.1 30.122 9.433 40.454 38.641 5.343 15.332 5.347 46.154 0 37.05-5.89 53.254-11.748 32.051-48.294 36.87-4.292.723-36.545 1.252l-10.875.362h-39.069v62.867zm65.539-119.35h40.858q19.43-.7 23.666-3.019c3.872-2.129 6.474-6.4 7.768-12.791q1.245-6.379 1.243-18.991 0-15.45-2.477-22.919-3.534-10.483-16.941-12.786-2.657-.348-12.712-.357h-41.4zm280.56 77.268h-87.623l-11.775 42.082h-67.8l73.166-243.5h98.857l74.059 243.5h-66.38zm-13.013-47.434-30.71-105.553-29.8 105.553z"
            fill="#10298e"
        />
        <path
            d="m375.353 34.281a86.153 86.153 0 0 1 67.01 31.954l14.126-30.289a123.816 123.816 0 0 0 -85.328-33.767c-51.64 0-95.814 31.193-113.938 75.344h-27.548l-16.269 34.87h35.436q-.422 4.875-.441 9.772a117.841 117.841 0 0 0 .6 11.849h-17.805l-16.264 34.88h43.13c18.643 43.033 62.265 73.243 113.094 73.243a124.152 124.152 0 0 0 69.076-20.791v-42.745a86.218 86.218 0 0 1 -137.131-9.707h90.309l16.262-34.88h-119.856a87.87 87.87 0 0 1 -.51-21.625h130.453l16.26-34.866h-135.443a86.367 86.367 0 0 1 74.778-43.246"
            fill="#ffbe00"
        />
        <path
            d="m375.353 35.325a85.022 85.022 0 0 1 66.2 31.573l1.053 1.3.714-1.517 14.124-30.29.315-.691-.543-.519a125.936 125.936 0 0 0 -156.172-12.744 121.519 121.519 0 0 0 -44.786 54.692l.965-.649h-28.221l-.278.6-16.264 34.877-.7 1.489h37.084l-1.043-1.136q-.422 4.919-.441 9.86c0 3.914.2 7.944.6 11.956l1.043-1.15h-18.466l-.278.6-16.274 34.877-.691 1.489h44.772l-.96-.631c19.441 44.874 64.213 73.873 114.054 73.873a125.107 125.107 0 0 0 69.648-20.958l.459-.306v-46.093l-1.827 2.087a85.181 85.181 0 0 1 -135.471-9.591l-.872 1.623h90.982l.278-.6 16.264-34.885.7-1.484h-121.51l1.039.9a86.817 86.817 0 0 1 -.506-21.374l-1.043.941h131.126l.278-.6 16.26-34.875.7-1.489h-137.09l.9 1.572a85.721 85.721 0 0 1 73.878-42.727m-74.778 43.246h135.439l-.951-1.489-16.255 34.875.946-.6h-131.4l-.1.946a90.248 90.248 0 0 0 .519 21.876l.139.9h120.76l-.946-1.493-16.26 34.875.941-.6h-92.252l1.067 1.614a87.289 87.289 0 0 0 138.8 9.832l-1.837-.691v42.745l.464-.863a123.084 123.084 0 0 1 -68.484 20.605c-49.011 0-93.022-28.508-112.13-72.617l-.278-.626h-43.821l.955 1.5 16.253-34.901-.951.612h18.971l-.12-1.159c-.394-3.942-.6-7.9-.6-11.743 0-2.954.148-6.126.441-9.683l.093-1.132h-36.568l.941 1.489 16.265-34.875-.941.6h28.243l.264-.649a119.518 119.518 0 0 1 44.03-53.751 123.856 123.856 0 0 1 153.558 12.535l-.232-1.206-14.117 30.297 1.762-.223a87.318 87.318 0 0 0 -143.517 11.432l-.909 1.572z"
            fill="#10298e"
        />
        <script xmlns="" />
        <script xmlns="" id="bw-fido2-page-script" />
    </svg>
    }
    href="/integrations/payment-providers/sepa"
  >
    Die SEPA-Lastschrift-Integration ermöglicht es dir, Lastschrift-Zahlungen in Euro über deine Hausbank zu akzeptieren.
  </Card>

  <Card
    title="Überweisung"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 452.9 101.10000000000001"
        width={60}
        height={30}
    >
        <script xmlns="" />
        <path d="M79.7 0H57.4c0 18.3-8.4 35-23 46l-8.8 6.6 34.2 46.6h28.1L56.4 56.3C71.3 41.5 79.7 21.5 79.7 0zM0 0h22.8v99.2H0zM94.5 0H116v99.2H94.5zM304.6 28.7c-8.2 0-16 2.5-21.2 9.6v-7.7H263v68.6h20.7v-36c0-10.4 7-15.5 15.4-15.5 9 0 14.2 5.4 14.2 15.4v36.2h20.5V55.6c0-16-12.7-26.9-29.2-26.9zM181 30.6V35c-5.8-4-12.8-6.3-20.4-6.3-20 0-36.2 16.2-36.2 36.2s16.2 36.2 36.2 36.2c7.6 0 14.6-2.3 20.4-6.3v4.4h20.5V30.6zm-18.7 51.9c-10.3 0-18.6-7.9-18.6-17.6s8.3-17.6 18.6-17.6 18.6 7.9 18.6 17.6-8.3 17.6-18.6 17.6zM233.3 39.5v-8.9h-21v68.6h21.1v-32c0-10.8 11.7-16.6 19.8-16.6h.2v-20c-8.3 0-16 3.6-20.1 8.9zM397.6 30.6V35c-5.8-4-12.8-6.3-20.4-6.3-20 0-36.2 16.2-36.2 36.2s16.2 36.2 36.2 36.2c7.6 0 14.6-2.3 20.4-6.3v4.4h20.5V30.6zm-18.7 51.9c-10.3 0-18.6-7.9-18.6-17.6s8.3-17.6 18.6-17.6 18.6 7.9 18.6 17.6c.1 9.7-8.3 17.6-18.6 17.6zM434 32.6c0-1-.7-1.6-1.8-1.6h-1.9v5.2h.9v-1.9h1l.8 1.9h1l-.9-2.1c.6-.3.9-.8.9-1.5zm-1.8.8h-1v-1.6h1c.6 0 .9.3.9.8s-.2.8-.9.8z" />
        <path d="M431.9 28.8c-2.7 0-4.9 2.2-4.9 4.9.1 2.7 2.2 4.9 4.9 4.9s4.9-2.2 4.9-4.9-2.2-4.9-4.9-4.9zm0 8.9c-2.2 0-3.9-1.8-3.9-4s1.8-4 3.9-4c2.2 0 3.9 1.8 3.9 4s-1.8 4-3.9 4zM440 74.9c-7.1 0-12.9 5.8-12.9 12.9s5.8 12.9 12.9 12.9 12.9-5.8 12.9-12.9c0-7.2-5.8-12.9-12.9-12.9z" />
        <script xmlns="" />
        <script xmlns="" id="bw-fido2-page-script" />
    </svg>
    }
    href="/integrations/payment-providers/bank-transfer"
  >
    Mit Hilfe von Klarna kannst du den Zahlungsstatus von Überweisungen automatisiert überwachen.
  </Card>
</CardGroup>

## Buchhaltungssoftware

<CardGroup>
  <Card title="DATEV" href="/integrations/accounting/datev">
    Die DATEV-Integration ermöglicht es dir, Kundenstämme, Buchungen und Rechnungen aus Fynn in dein DATEV-System zu übertragen.
  </Card>
</CardGroup>

## CRM Integrationen

<CardGroup>
  <Card
    title="HubSpot"
    icon={<svg
        xmlns="http://www.w3.org/2000/svg"
        width={60}
        height={30}
        viewBox="0 0 512 149"
        preserveAspectRatio="xMidYMid"
    >
        <script xmlns="" />
        <path
            d="M.06 27.679h17.852v39.662h37.651V27.679h17.875v97.358H55.563V84.542H17.912v40.495H.06V27.679zM129.993 93.326c0 8.15-6.64 14.782-14.788 14.782-8.151 0-14.787-6.632-14.787-14.782V51.41h-16.93v41.916c0 17.487 14.229 31.711 31.717 31.711 17.484 0 31.712-14.224 31.712-31.711V51.41h-16.924v41.916M194.179 51.901c-8.398 0-14.26 2.437-19.921 7.994V27.679h-16.985v59.705c0 22.348 16.158 37.653 34.311 37.653 20.181 0 37.863-15.578 37.863-36.567 0-20.723-16.305-36.569-35.268-36.569zm.422 57.423c-11.509 0-20.31-9.612-20.31-20.854 0-11.244 8.801-20.859 20.31-20.859 9.752 0 18.558 9.615 18.558 20.859 0 11.242-8.806 20.854-18.558 20.854zM257.974 56.18c0-8.538 5.689-11.245 11.917-11.245 5.014 0 11.649 3.792 15.979 8.398l11.103-13.001c-5.549-7.448-16.788-12.596-25.998-12.596-18.421 0-31.694 10.7-31.694 28.444 0 32.91 40.497 22.478 40.497 40.902 0 5.682-5.551 10.698-11.913 10.698-10.026 0-13.278-4.876-17.881-10.024l-12.327 12.729c7.86 9.617 17.608 14.495 29.257 14.495 17.47 0 31.556-10.835 31.556-27.767 0-36.566-40.496-25.188-40.496-41.033M343.184 50.947c-18.151 0-34.311 15.296-34.311 37.649v59.859h16.984v-32.369c5.662 5.553 11.521 7.994 19.922 7.994 18.962 0 35.269-15.844 35.269-36.567 0-20.992-17.687-36.566-37.864-36.566zm3.018 57.425c-11.508 0-20.31-9.625-20.31-20.859 0-11.244 8.802-20.859 20.31-20.859 9.75 0 18.557 9.615 18.557 20.859 0 11.234-8.807 20.859-18.557 20.859zM506.069 109.324c-10.018 0-12.862-4.332-12.862-10.971V68.965h15.572V54.069h-15.572v-19.64l-17.195 7.718v59.863c0 15.306 10.56 23.027 25.045 23.027 2.167 0 5.15-.14 6.777-.541l4.199-15.438c-1.896.131-4.062.266-5.964.266"
            fill="#45535E"
        />
        <path
            d="M461.278 69.831c-3.256-5.602-7.836-10.093-13.562-13.474-4.279-2.491-8.716-4.072-13.716-4.751v-17.8c5-2.123 8.103-6.822 8.103-12.304 0-7.472-5.992-13.527-13.458-13.527-7.472 0-13.569 6.055-13.569 13.527 0 5.482 2.924 10.181 7.924 12.304v17.808c-4 .578-8.148 1.825-11.936 3.741-7.737-5.876-33.107-25.153-47.948-36.412.352-1.269.623-2.577.623-3.957 0-8.276-6.702-14.984-14.981-14.984S333.78 6.71 333.78 14.986c0 8.275 6.706 14.985 14.985 14.985 2.824 0 5.436-.826 7.69-2.184l3.132 2.376 43.036 31.008c-2.275 2.089-4.394 4.465-6.089 7.131C393.099 73.737 391 79.717 391 86.24v1.361c0 4.579.87 8.902 2.352 12.963 1.305 3.546 3.213 6.77 5.576 9.685l-14.283 14.318a11.501 11.501 0 0 0-12.166 2.668 11.499 11.499 0 0 0-3.388 8.19c.001 3.093 1.206 6 3.394 8.187a11.5 11.5 0 0 0 8.188 3.394 11.51 11.51 0 0 0 8.191-3.394 11.514 11.514 0 0 0 3.39-8.187c0-1.197-.185-2.365-.533-3.475l14.763-14.765c2.024 1.398 4.21 2.575 6.56 3.59 4.635 2.004 9.751 3.225 15.35 3.225h1.026c6.19 0 12.029-1.454 17.518-4.428 5.784-3.143 10.311-7.441 13.731-12.928 3.438-5.502 5.331-11.581 5.331-18.269v-.334c0-6.579-1.523-12.649-4.722-18.21zm-18.038 30.973c-4.007 4.453-8.613 7.196-13.82 7.196h-.858c-2.974 0-5.883-.822-8.731-2.317-3.21-1.646-5.65-3.994-7.647-6.967-2.064-2.918-3.184-6.104-3.184-9.482v-1.026c0-3.321.637-6.47 2.243-9.444 1.717-3.251 4.036-5.779 7.12-7.789 3.028-1.996 6.262-2.975 9.864-2.975h.335c3.266 0 6.358.644 9.276 2.137 2.973 1.592 5.402 3.767 7.285 6.628 1.829 2.862 2.917 5.949 3.267 9.312.055.699.083 1.415.083 2.099 0 4.564-1.744 8.791-5.233 12.628z"
            fill="#F8761F"
        />
        <script xmlns="" />
        <script xmlns="" id="bw-fido2-page-script" />
    </svg>
    }
    href="/integrations/crm/hubspot"
  >
    Die HubSpot-Integration ermöglicht es dir, deine HubSpot-Kontakte und -Deals mit deiner Abonnement-Plattform zu synchronisieren.
  </Card>
</CardGroup>

## Automatisierung

<AutomationIntegrationsCardGroup />


# Stripe Payments
Source: https://docs.fynn.eu/integrations/payment-providers/stripe

Wir bieten dir eine Vielzahl von Integrationen zu 3rd-Party-Tools und -Services, um die Funktionalität der Fynn-Plattform zu erweitern.

<Frame>
  <img />
</Frame>

Die Zahlungsmethode Stripe Payments ermöglicht es den Kunden, ihre Rechnungen einfach und sicher per Kreditkarte zu begleichen. Hier erfährst Du mehr über die Vorteile von Stripe Payments und wie Du es mit Fynn verbinden kannst:

## Vorteile von Stripe

* **Einfache und sichere Zahlungen**: Stripe Payments bietet eine einfache und sichere Möglichkeit für Kunden, Rechnungen mit Kreditkarte zu bezahlen, was die Zahlungsabwicklung für beide Seiten erleichtert.

* **Schnelle Transaktionsabwicklung**: Mit Stripe Payments werden Zahlungen in Echtzeit verarbeitet, was eine schnelle Abwicklung von Transaktionen ermöglicht und sicherstellt, dass Rechnungen sofort beglichen werden.

* **Vielfältige Zahlungsmöglichkeiten**: Stripe unterstützt eine Vielzahl von Kreditkarten, darunter Visa, Mastercard, American Express und mehr, was Kunden eine breite Palette von Zahlungsoptionen bietet.

* **Automatische Abrechnung und Abrechnung**: Durch die Integration von Stripe Payments können Unternehmen automatische Abrechnungen einrichten und Zahlungen problemlos verfolgen und verwalten, was den Verwaltungsaufwand reduziert und Fehler minimiert.

## Stripe verbinden

<Check>
  Für die Verbindung von Stripe benötigst du kein Konto. Dieses kannst du direkt während des Einrichtungsprozesses erstellen.
</Check>

Um Stripe mit Fynn zu verbinden, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Zahlungsmethoden-Einstellungen">
    Gehe hierzu zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods).
  </Step>

  <Step title="Klicke auf Verbinden">
    Klicke neben dem Stripe Logo auf den Button "Verbinden". Du wirst nun zur Stripe-Website weitergeleitet, wo du dich mit deinem Stripe-Konto anmelden oder ein neues Konto erstellen kannst.

    <Frame>
      <img alt="Stripe verbinden" />
    </Frame>
  </Step>

  <Step title="Stripe Konto anlegen oder anmelden">
    Wenn du bereits ein Stripe-Konto hast, kannst du dich mit deinen Anmeldedaten einloggen. Andernfalls kannst du ein neues Konto erstellen, indem du auf "Erstellen Sie ein Konto" klickst und die erforderlichen Informationen eingibst.

    <Frame>
      <img alt="Stripe Konto anlegen oder anmelden" />
    </Frame>
  </Step>

  <Step title="Stripe ist erfolgreich verbunden 🎉">
    Nachdem du dich bei Stripe angemeldet oder ein neues Konto erstellt hast, wirst du zur Fynn-Plattform zurückgeleitet und eine Bestätigung erhalten, dass Stripe erfolgreich verbunden wurde.

    <Frame>
      <img alt="Stripe erfolgreich verbunden" />
    </Frame>
  </Step>

  <Step title="(optional) Kreditkarten Zahlungsmethode aktivieren">
    Nachdem Stripe erfolgreich verbunden wurde, kannst du die Kreditkarten-Zahlungsmethode aktivieren, indem du auf den Schalter neben "Kreditkarte" klickst.

    Näheres hierzu findest du unter [Zahlungsmethoden freigeben](/guide/tenant/payment-methods#zahlungsmethoden-freigeben).

    <Frame>
      <img alt="Kreditkarten Zahlungsmethode aktivieren" />
    </Frame>
  </Step>
</Steps>

## Stripe Migration starten

<Steps>
  <Step title="Stripe Migration öffnen">
    Klicke hierzu auf das "Einstellungs"-Symbol neben dem Stripe Logo und wähle "Migration starten" aus.

    <Frame>
      <img alt="Stripe Migration starten" />
    </Frame>
  </Step>

  <Step title="Stripe Migration starten">
    Ein Migrations-Assistent öffnet sich. Du wirst nun durch den Migrationsprozess geführt, um deine bestehenden Zahlungsmethoden und Kunden von deinem alten Zahlungsanbieter zu Stripe zu migrieren.

    **Migrationsablauf**

    * Für alle Kunden, die in Fynn angelegt sind, wird im verbundenen Stripe-Konto der passende Kunde auf Basis der in Fynn hinterlegten E-Mail Adresse gesucht
    * Wird ein passender Kunde in Stripe gefunden, werden alle Zahlungsmethoden abgerufen. Diese werden dann in Fynn migriert, sofern sie den folgenden Kriterien entsprechen:
      * die Zahlungsmethode ist eine "Kreditkarte"
      * die Kreditkarte ist nicht abgelaufen
      * die Kreditkarte ist noch nicht einem beliebigen Kunden in Fynn zugeordnet

    <Info>
      Wurde die Zahlungsmethode erfolgreich migriert, wird der Kunde über das Hinzufügen einer neuen Zahlungsmethode informiert.
      Ist dies nicht gewünscht, empfehlen wir die Benachrichtigung "Zahlungsmethode hinzugefügt" in den Einstellungen zu deaktivieren.
    </Info>

    Klicke hierfür auf "Migration starten".

    <Frame>
      <img alt="Stripe Migration Assistent" />
    </Frame>
  </Step>

  <Step title="Migration abgeschlossen 🎉">
    Nachdem du den Migrationsprozess abgeschlossen hast, erhältst du eine Bestätigung, dass die Migration erfolgreich abgeschlossen wurde.

    Hier erhältst du eine Übersicht über alle Zahlungsmethoden und Kunden, die erfolgreich migriert wurden.
    Außerdem erhältst du eine Übersicht, welche Zahlungsmethoden nicht migriert werden konnten und aus welchem Grund.
  </Step>
</Steps>

## Migration der Kundendaten

<Info>
  Es werden keine Kunden aus dem Stripe-Account zu Fynn migriert.
</Info>

## Migration der Produkte

<Info>
  Es werden keine Produkte aus dem Stripe-Account zu Fynn migriert.
</Info>

## Migration der Abonnements

<Info>
  Es werden keine Abonnements aus dem Stripe-Account zu Fynn migriert.
</Info>

<Info>
  Bereits in Stripe angelegte Abonnements können parallel zu Abonnements in Fynn weitergeführt werden. Wir empfehlen jedoch, die Abonnements zu migrieren, um alle Daten zentral zu verwalten.
  Um doppelte Abrechnungen bei der Migration zu verhindern, sollte bei Abo-Anlage in Fynn der Wert in der Abo-Anlage Maske unter "Abrechnung" > "Abrechnungsbeginn" auf das Datum gesetzt werden, ab dem die Abrechnung in Fynn erfolgen soll.
</Info>


# Willkommen
Source: https://docs.fynn.eu/introduction

Willkommen bei Fynn! Hier findest du alles, was du brauchst, um loszulegen.

Fynn ist eine Plattform zur Abrechnung deines Business. Verkaufe Produkte, erstelle maßgeschneiderte Abonnements, automatisiere Rechnungen und verwalte Zahlungen mühelos.
Behalte deine Kunden im Blick, optimiere Verkäufe und nutze unsere leistungsstarke API, um deine individuellen Anwendungen zu kreieren und zu erweitern.

Mit uns werden individuelle Abonnementkonditionen und -modelle zum Kinderspiel.

## Los geht's 🚀

<CardGroup>
  <Card title="Organisation einrichten" icon="pen-to-square" href="guide/tenant/configure">
    Richte deine Organisation ein und füge dein Team hinzu.
  </Card>

  <Card title="Kunden" icon="user" href="guide/customers/introduction">
    Erstelle und verwalte deine Kunden.
  </Card>

  <Card title="Abonnements" icon="rotate" href="guide/subscriptions/introduction">
    Erstelle und verwalte Abonnements.
  </Card>

  <Card title="Rechnungen" icon="receipt" href="guide/invoices/introduction">
    Erstelle und verwalte Rechnungen, Gutschriften und Stornos.
  </Card>

  <Card title="Zahlungen" icon="credit-card" href="guide/payments/introduction">
    Verwalte Zahlungen und Zahlungsmethoden.
  </Card>

  <Card title="Angebote" icon="tag" href="guide/offers/introduction">
    Erstelle und verwalte Angebote.
  </Card>
</CardGroup>

## Weitere Schritte

<CardGroup>
  <Card title="Checkout" icon="cart-shopping" href="guide/checkout/checkout-links">
    Verkaufe Abonnements und Produkte mit unserem Checkout.
  </Card>

  <Card title="Gutscheine & Rabatte" icon="percent" href="guide/discounts/introduction">
    Erstelle und verwalte Gutscheine und Rabatte.
  </Card>

  <Card title="Zahlungsausfälle" icon="sack-xmark" href="guide/dunning/introduction">
    Konfiguriere Zahlungsausfälle und Mahnungen.
  </Card>

  <Card title="Buchhaltung" icon="calculator" href="guide/accounting/introduction">
    Buchhaltungseinstellungen und Integrationen konfigurieren.
  </Card>

  <Card title="Benachrichtigungen" icon="bell" href="guide/notifications/introduction">
    Konfiguriere Benachrichtigungen und E-Mails.
  </Card>
</CardGroup>

## Werkzeuge

<CardGroup>
  <Card title="KI-Assistent" icon="wand-magic-sparkles" href="guide/ai-assistant/introduction">
    Finde Daten, navigiere und erstelle Berichte per Chat.
  </Card>
</CardGroup>

## Entwickler

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="guide/webhooks/introduction">
    Konfiguriere Webhooks und erhalte Benachrichtigungen.
  </Card>

  <Card title="API-Referenz" icon="code" href="/api-reference">
    Entdecke unsere API-Referenz.
  </Card>
</CardGroup>


# Authentication
Source: https://docs.fynn.eu/api-reference/authentication

All API endpoints are authenticated using Bearer tokens and picked up from the specification file.

Authentication is a crucial aspect of interacting with the Fynn API. This guide will walk you through the process of setting up and managing API keys for authentication, as well as authenticating requests both as a platform and as a customer.

## Setting Up API Keys

To interact with the Fynn API, you need to generate an API key. Follow these steps to create an API key:

1. Log in to your Fynn account (or sign up for a new account if you don't have one) at [https://app.fynn.eu](https://app.fynn.eu).
2. Navigate to the Developer Settings page by clicking on the settings icon on the top-right side and selecting "Settings" > "Developer" or visit [https://app.fynn.eu/settings/developer](https://app.fynn.eu/settings/developer).
3. Click on the "Add API Key" button.
4. Provide a name for your API key to help you identify its purpose.
5. \[optional] Define the expiration date for the API key. If you don't set an expiration date, the API key will never expire.
6. Click "Generate" to create the API key.
7. Your API key will be displayed. Make sure to copy and securely store it, as it will not be shown again.

## Deleting API Keys

To delete an API key, follow these steps:

1. Go to the Developer Settings page.
2. Locate the API key you wish to delete.
3. Click on the "Delete" button next to the API key.
4. Confirm the deletion when prompted.

<Warning>
  <p>Deleting an API key will immediately revoke access to the API for any application or service using it. Make sure to update your applications and services with a new API key before deleting the old one.</p>
</Warning>

## Authenticating Requests

To authenticate your requests to the Fynn API, include your API key in the request headers as follows:

```plaintext theme={null}
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

<Note>
  The same Bearer token connects AI Tools to Fynn through the [MCP server](/guide/developers/mcp-server).
</Note>

## Authenticating as a Customer

Customers can authenticate themselves with the API to access their own data, such as payment methods and subscription details.
This is done by making a POST request to our api:

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
  --url https://[preview.]coreapi.io/customers/{id}/authenticate \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={null}
  {
      "data": {
      "accessToken": "xxx",
      "refreshToken": "xxx"
      }
  }
  ```
</CodeGroup>

Replace `YOUR_API_KEY` with your actual API key.

### Limitations

When authenticated as a customer, access is restricted to the customer's own data. This means that only operations related to the authenticated customer, such as managing payment methods, subscriptions, or viewing account details, are permitted.

Have a look on following permissions on the API routes:

* `ROLE_CUSTOMER`
* `customer:self:read`
* `customer:payment-method:add`
* `customer:payment-method:read`


# Add comment
Source: https://docs.fynn.eu/api-reference/customer/add-comment

post /customers/{id}/comment
Add comment

<sup>Required permissions: `customer:write`</sup>



# Archive customer
Source: https://docs.fynn.eu/api-reference/customer/archive-customer

put /customers/{id}/archive
Archives a customer. The customer is not visible anymore in the customer list.

<sup>Required permissions: `customer:write`</sup>



# Generate customer authentication
Source: https://docs.fynn.eu/api-reference/customer/authenticate-customer

post /customers/{id}/authenticate
Generates authentication tokens and a pre-authenticated link to the customer portal. Use this to allow customers to access their portal without entering credentials, or to make API calls on behalf of the customer.

Generates authentication tokens and a pre-authenticated link to the customer portal.

## Use Cases

* **Customer Portal Access**: Generate a link that allows customers to access their portal without entering credentials
* **API on Behalf of Customer**: Use the access token to make API calls on behalf of the customer
* **Email Integration**: Include the customer area link in emails to provide seamless access

## Response

The endpoint returns:

| Field              | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `accessToken`      | JWT access token for API authentication on behalf of the customer |
| `refreshToken`     | JWT refresh token to obtain new access tokens                     |
| `customerAreaLink` | Pre-authenticated short link to the customer portal               |

## Example Response

```json theme={null}
{
    "data": {
        "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "customerAreaLink": "https://example.customerfront.app/customer-area/login?token=abc123"
    }
}
```

<Warning>
  The `customerAreaLink` contains a short-lived token. Generate a new link if the customer needs to access the portal at a later time.
</Warning>

<Tip>
  Use the `accessToken` to make API calls on behalf of the customer, for example to retrieve their entitlements or subscriptions.
</Tip>


# Create customer
Source: https://docs.fynn.eu/api-reference/customer/create-customer

post /customers
Create customer

<sup>Required permissions: `customer:write`</sup>



# Delete customer
Source: https://docs.fynn.eu/api-reference/customer/delete-customer

delete /customers/{id}
Deletes a customer. The customer can only be deleted if there are no invoices, active subscriptions or booked payments related to this customer. Otherwise you can only archive the customer.

<sup>Required permissions: `customer:write`</sup>



# Get customer
Source: https://docs.fynn.eu/api-reference/customer/get-customer

get /customers/{id}
Get customer

<sup>Required permissions: `customer:read`, `customer:self:read`</sup>



# Get customer children
Source: https://docs.fynn.eu/api-reference/customer/get-customer-children

get /customers/{customerId}/children
Returns a list of direct child customers for the specified customer, including subscription metrics. When the `customer.hierarchy` feature is not enabled, an empty array is returned.

<sup>Required permissions: `customer:read`</sup>

Returns a list of direct child customers for the specified parent customer. Each child entry includes basic customer information and the count of active subscriptions (`activeSubscriptionCount`).

When the `customer.hierarchy` feature is not enabled, this endpoint returns an empty array.

## Response Fields

| Field                     | Description                                                                  |
| ------------------------- | ---------------------------------------------------------------------------- |
| `id`                      | The child customer ID                                                        |
| `customerNumber`          | The customer number                                                          |
| `name`                    | The display name                                                             |
| `companyName`             | The company name                                                             |
| `email`                   | The primary email address                                                    |
| `status`                  | The customer status (`STATUS_ACTIVE`, `STATUS_ARCHIVED`, `STATUS_SUSPENDED`) |
| `activeSubscriptionCount` | Number of active subscriptions for this child customer                       |


# Get customer hierarchy
Source: https://docs.fynn.eu/api-reference/customer/get-customer-hierarchy

get /customers/{customerId}/hierarchy
Returns the full hierarchy tree for the specified customer, starting from the root of the hierarchy. The tree is built recursively with each node containing its children. The `isCurrentCustomer` flag marks which node in the tree is the customer from the request.

This endpoint requires the `customer.hierarchy` feature to be enabled.

<sup>Required permissions: `customer:read`</sup>

Returns the full hierarchy tree for any customer in the organization structure. Regardless of whether a parent or child customer ID is provided, the response always starts from the root of the hierarchy and includes all descendants as a nested tree.

The `isCurrentCustomer` flag on each node indicates which customer in the tree corresponds to the ID specified in the request path.

## Example Response

```json theme={null}
{
    "root": {
        "id": "uuid-100",
        "name": "Klinik Musterstadt",
        "customerNumber": "CUST-100",
        "isCurrentCustomer": false,
        "children": [
            {
                "id": "uuid-101",
                "name": "Radiology",
                "customerNumber": "CUST-101",
                "isCurrentCustomer": true,
                "children": []
            },
            {
                "id": "uuid-102",
                "name": "Orthopedics",
                "customerNumber": "CUST-102",
                "isCurrentCustomer": false,
                "children": []
            }
        ]
    }
}
```

## Feature Flag

This endpoint requires the `customer.hierarchy` feature to be enabled. If the feature is not active, a `501 Not Implemented` response is returned.


# Get customers
Source: https://docs.fynn.eu/api-reference/customer/get-customers

get /customers
Get customers

<sup>Required permissions: `customer:read`</sup>



# Remove parent customer
Source: https://docs.fynn.eu/api-reference/customer/remove-parent-customer

put /customers/{customerId}/remove-parent
Removes the parent customer assignment, making this customer a root-level customer in the organization hierarchy.

This endpoint requires the `customer.hierarchy` feature to be enabled.

<sup>Required permissions: `customer:write`</sup>

Removes the parent customer assignment from a child customer. After removal, the customer becomes a standalone root-level customer without hierarchy membership.

## Feature Flag

This endpoint requires the `customer.hierarchy` feature to be enabled. If the feature is not active, a `501 Not Implemented` response is returned.

## Webhooks

A successful removal dispatches the `customer.parent.removed` webhook event, which includes the customer payload.


# Send login email to customer
Source: https://docs.fynn.eu/api-reference/customer/send-login-email

post /customers/{id}/send-login-email
Sends an email to the customer containing a login link to the customer portal. The customer can click the link to access their portal without entering credentials. Use this for support scenarios or to help customers access their account.

Sends an email to the customer containing a one-click login link to the customer portal.

## Use Cases

* **Support**: Help customers who have trouble logging in
* **Onboarding**: Send a welcome email with direct portal access
* **Proactive Outreach**: Remind customers to update payment methods or review invoices

<Tip>
  The login link is valid for a limited time. If the customer doesn't use it, they can request a new one from the login page.
</Tip>


# Set parent customer
Source: https://docs.fynn.eu/api-reference/customer/set-parent-customer

put /customers/{customerId}/set-parent
Assigns a parent customer to establish an organizational hierarchy. The hierarchy supports a maximum of 3 levels. Circular references and self-assignment are not permitted. Both the parent and child customer must belong to the same tenant, and the parent customer must be active (not archived).

This endpoint requires the `customer.hierarchy` feature to be enabled.

<sup>Required permissions: `customer:write`</sup>

Establishes a parent-child relationship between two customers. This is used to model organizational structures such as a company with departments, a clinic with specialized units, or a retail chain with individual stores.

## Validation

The following rules are enforced when assigning a parent customer:

* The parent and child customer must belong to the **same tenant**
* A customer **cannot be its own parent**
* **Circular references** are not permitted (e.g., A → B → A)
* The hierarchy supports a **maximum of 3 levels** (root → child → grandchild)
* The parent customer must be **active** (not archived)

If any validation rule is violated, the API returns a `400 Bad Request` with a descriptive error message.

## Feature Flag

This endpoint requires the `customer.hierarchy` feature to be enabled. If the feature is not active, a `501 Not Implemented` response is returned.

## Webhooks

A successful assignment dispatches the `customer.parent.assigned` webhook event, which includes the full customer and parent customer payloads.


# Update customer
Source: https://docs.fynn.eu/api-reference/customer/update-customer

put /customers/{id}
Update customer

<sup>Required permissions: `customer:write`</sup>



# Add a customer address
Source: https://docs.fynn.eu/api-reference/customeraddress/add-a-customer-address

post /customers/{customerId}/addresses
Add a customer address. A new address is set as default for the given address type.

<sup>Required permissions: `customer:write`</sup>



# Delete a customer address
Source: https://docs.fynn.eu/api-reference/customeraddress/delete-a-customer-address

delete /customer-addresses/{id}
Delete a customer address

<sup>Required permissions: `customer:write`</sup>



# Get a customer address
Source: https://docs.fynn.eu/api-reference/customeraddress/get-a-customer-address

get /customer-addresses/{id}
Get a customer address

<sup>Required permissions: `customer:read`</sup>



# Get all customer addresses
Source: https://docs.fynn.eu/api-reference/customeraddress/get-all-customer-addresses

get /customers/{customerId}/addresses
Get all customer addresses

<sup>Required permissions: `customer:read`</sup>



# Set a customer address as default
Source: https://docs.fynn.eu/api-reference/customeraddress/set-a-customer-address-as-default

post /customer-addresses/{id}/default
Set a customer address as default. The default will be set only for the address type of the given address.

<sup>Required permissions: `customer:write`</sup>



# Unset a customer address as default
Source: https://docs.fynn.eu/api-reference/customeraddress/unset-a-customer-address-as-default

put /customer-addresses/{id}/unset-default
Unset a customer address as default. This is only possible for the default address of the type "TYPE_INVOICE". Then the default address will be used as default invoice address.

<sup>Required permissions: `customer:write`</sup>



# Update a customer address
Source: https://docs.fynn.eu/api-reference/customeraddress/update-a-customer-address

put /customer-addresses/{id}
Update a customer address

<sup>Required permissions: `customer:write`</sup>



# Create customer email address
Source: https://docs.fynn.eu/api-reference/customeremail/create-customer-email-address

post /customers/{customerId}/email-addresses
Create customer email address

<sup>Required permissions: `customer:write`</sup>



# Delete customer email address
Source: https://docs.fynn.eu/api-reference/customeremail/delete-customer-email-address

delete /customer-email-addresses/{id}
Delete customer email address

<sup>Required permissions: `customer:write`</sup>



# Get customer email address
Source: https://docs.fynn.eu/api-reference/customeremail/get-customer-email-address

get /customer-email-addresses/{id}
Get customer email address

<sup>Required permissions: `customer:read`</sup>



# Get customer email addresses
Source: https://docs.fynn.eu/api-reference/customeremail/get-customer-email-addresses

get /customers/{customerId}/email-addresses
Get customer email addresses

<sup>Required permissions: `customer:read`</sup>



# Set default customer email address
Source: https://docs.fynn.eu/api-reference/customeremail/set-default-customer-email-address

post /customer-email-addresses/{id}/default
Set a customer email as default. The default will be set only for the email type of the given email.

<sup>Required permissions: `customer:write`</sup>



# Update customer email address
Source: https://docs.fynn.eu/api-reference/customeremail/update-customer-email-address

patch /customer-email-addresses/{id}
Update customer email address

<sup>Required permissions: `customer:write`</sup>



# Request a one time token for a customer
Source: https://docs.fynn.eu/api-reference/customerotp/request-a-one-time-token-for-a-customer

post /public/customer/request-otp
Creates a CustomerOtp resource.



# Request a login link for the customer portal
Source: https://docs.fynn.eu/api-reference/customerotp/request-login-link

post /public/customer/request-login-link
Sends an email with a login link to the customer portal. The customer can click the link to access their portal without entering a password. Always returns success to prevent email enumeration.

Public endpoint for customers to request a login link to the customer portal.

## How It Works

1. Customer enters their email address on the login page
2. An email with a login link is sent to the customer
3. Customer clicks the link and is logged in automatically

<Note>
  This endpoint always returns `success: true` to prevent email enumeration attacks. The email is only sent if the address matches an existing customer.
</Note>

## Difference to OTP

This endpoint replaces the OTP (one-time password) flow for customer portal login. Instead of entering a 6-digit code, customers simply click a link in their email - a much smoother experience, especially on mobile devices.

The OTP flow (`/public/customer/request-otp` and `/public/customer/otp-login`) is still available and used in the checkout flow where inline verification is required.


# Get settings
Source: https://docs.fynn.eu/api-reference/customersettings/get-settings

get /customers/{id}/settings/{context}
Get all customer settings of the context

<sup>Required permissions: `customer-settings:read`</sup>



# Update settings
Source: https://docs.fynn.eu/api-reference/customersettings/update-settings

patch /customers/{id}/settings/{context}
Update given customer setting keys of the context.

<sup>Required permissions: `customer-settings:write`</sup>



# Manage payment methods on your own payment page
Source: https://docs.fynn.eu/api-reference/guides/add-payment-method

Learn how to manage payment methods on your own payment page.

## Fynn elements

We are currently working on a new feature that allows you to manage payment methods on your own payment page without any business-code. This feature is called Fynn elements and will be available in Q2.24.

## Add new payment method

The following steps show you how to add a new payment method using the Fynn API on your own payment page.

<Tabs>
  <Tab title="Stripe Credit card">
    <Steps>
      <Step title="Create stripe setup intent">
        To add a new payment method, you need to create a Stripe SetupIntent first in order to securely collect card details in Fynn.

        ```bash theme={null}
        curl -X POST \
        /payment-methods \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer <token>" \
        --data '{
            "gateway": "stripe",
            "type": "card",
            "customerId": "<customerId>",
            "isDefault": true,
            "futureUsageAllowed": true,
            "stripe": {
                "paymentMethodId": null,
                "customerId": null
            }
        }'
        ```

        **Example response**

        ```json theme={null}
        {
            "status": "action_required",
            "action_required": {
                "action": "client_site_action",
                "details": {
                    "clientSecret": "test_1234567890",
                    "publishableKey": "pk_test_1234567890"
                    "accountId": "acct_1234567890",
                }
            }
        }
        ```
      </Step>

      <Step title="Collect card details">
        After creating the SetupIntent, you can show the Stripe.js card element in your form to collect the card details.
        Then confirm the SetupIntent with the card details.

        ```html theme={null}
        <html>
        <head>
            <script src="https://js.stripe.com/v3/"></script>
            <script>
                var stripe = Stripe('pk_test_1234567890:<publishableKey>', { // previously received from the response
                    stripeAccount: 'acct_1234567890:<accountId>' // previously received from the response
                });

                // see: https://docs.stripe.com/js/element/other_element?type=card
                var elements = stripe.elements();
                var card = elements.create('card');
                card.mount('#card-element');

                var paymentIntentClientSecret = '<clientSecret>'; // previously received from the response

                var form = document.getElementById('payment-form');
                form.addEventListener('submit', function(event) {
                    event.preventDefault();
                    stripe.confirmCardSetup(paymentIntentClientSecret, {
                        payment_method: {
                            card: card,
                            billing_details: {
                                name: 'Jenny Rosen'
                            }
                        }
                    }).then(function(result) {
                        if (result.error) {
                            console.log(result.error.message);
                        } else {
                            console.log(result.setupIntent.payment_method);

                            // send payment method id to fynn
                            // see: https://docs.fynn.app/api-reference/paymentmethod/create-payment-method
                        }
                    });
                });
            </script>
        </head>
        <body>
            <form id="payment-form">
                <div id="card-element"></div>
                <button id="submit">Submit</button>
            </form>
        </body>
        </html>
        ```
      </Step>

      <Step title="Assign payment method">
        Assign the payment method created in stripe with Fynn. Use the payment method id received from the confirmation `result.setupIntent.payment_method`.

        ```bash theme={null}
        curl -X POST \
        /payment-methods \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer <token>" \
        --data '{
            "gateway": "stripe",
            "type": "card",
            "customerId": "<customerId>",
            "isDefault": true,
            "futureUsageAllowed": true,
            "stripe": {
                "paymentMethodId": "pm_1J4X2n2eZvKYlo2C2Q2Q2Q2Q2", // result.setupIntent.payment_method
            }
        }'
        ```
      </Step>

      <Step title="Done 🎉">
        That's it! You have successfully added a new card payment method to the customer.
      </Step>
    </Steps>
  </Tab>

  <Tab title="SEPA debit (via Fynn)">
    Collect the customer's SEPA details in your own form and create a new payment method:

    ```bash theme={null}
    curl -X POST \
    /payment-methods \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer <token>" \
    --data '{
        "gateway": "sepa_debit",
        "type": "sepa_debit",
        "customerId": "<customerId>",
        "isDefault": true,
        "futureUsageAllowed": true,
        "sepaMandate": {
            "iban": "DE89370400440532013000",
            "bic": "COBADEFFXXX",
            "accountHolder": "Max Mustermann",
            "signingDate": "2021-01-01",
            "type": "CORE",
            "sequence": "FRST"
        }
    }'
    ```

    For more details see: [Create payment method](/api-reference/paymentmethod/create-payment-method).
  </Tab>

  <Tab title="Bank transfer">
    <Check>
      Bank transfer is created by default when a customer is created.
    </Check>
  </Tab>
</Tabs>


# Collect Usage Data
Source: https://docs.fynn.eu/api-reference/guides/collect-usage-data

Send usage events to Fynn for usage-based billing.

Usage events are the foundation of usage-based billing. Send them from your application to track customer consumption.

## Quick Start

Send a usage event:

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "events": [{
      "transactionId": "req-abc-123",
      "eventName": "ai_request",
      "timestamp": "2026-01-15T14:30:00Z",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "properties": {
        "tokens_used": 350,
        "model": "gpt-4"
      }
    }]
  }'
```

***

## Event Structure

Each event requires these fields:

| Field           | Type     | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `transactionId` | string   | Unique ID for idempotency                                  |
| `eventName`     | string   | Matches your Nutzungsmetrik's event name                   |
| `timestamp`     | ISO 8601 | When the event occurred                                    |
| `customerId`    | string   | The customer's Fynn UUID **or** external ID (`externalId`) |
| `properties`    | object   | Event data (tokens, bytes, etc.)                           |

<Tip>
  The `customerId` field accepts both the Fynn UUID and the customer's `externalId`. Fynn automatically detects which format is being used.
</Tip>

### Example: AI Token Usage

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

### Example: API Call Tracking

```json theme={null}
{
  "transactionId": "call-xyz-456",
  "eventName": "api_call",
  "timestamp": "2026-01-15T14:31:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "properties": {
    "endpoint": "/api/users",
    "method": "GET",
    "response_time_ms": 145,
    "status_code": 200
  }
}
```

***

## Batch Import

Send up to 1000 events in one request:

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "events": [
      {
        "transactionId": "req-001",
        "eventName": "ai_request",
        "timestamp": "2026-01-15T10:00:00Z",
        "customerId": "cust-123",
        "properties": { "tokens_used": 150, "model": "gpt-4" }
      },
      {
        "transactionId": "req-002",
        "eventName": "ai_request",
        "timestamp": "2026-01-15T10:01:00Z",
        "customerId": "cust-123",
        "properties": { "tokens_used": 300, "model": "gpt-4-turbo" }
      }
    ]
  }'
```

***

## Response

**Success (202 Accepted):**

```json theme={null}
{
  "ingested": 2,
  "failed": 0,
  "errors": []
}
```

**Partial Success:**

```json theme={null}
{
  "ingested": 1,
  "failed": 1,
  "errors": [
    {
      "index": 1,
      "transactionId": "req-002",
      "error": "Invalid customer ID"
    }
  ]
}
```

***

## Idempotency

Events with the same `transactionId` are only processed once. If you send the same event twice, Fynn returns the existing event instead of creating a duplicate.

<Tip>
  Use deterministic transaction IDs, e.g.: `${customerId}-${timestamp}-${eventName}` or UUIDs.
</Tip>

***

## Properties for Nutzungsmetriks

The `properties` object should contain all fields your Nutzungsmetriks need:

| Nutzungsmetrik | Aggregation  | Required Property |
| -------------- | ------------ | ----------------- |
| Token Usage    | Sum          | `tokens_used`     |
| API Calls      | Count        | - (counts events) |
| Storage        | Latest       | `storage_gb`      |
| Active Users   | Unique Count | `user_id`         |

### Grouping Properties

If your Nutzungsmetrik uses `groupBy`, include those fields:

```json theme={null}
{
  "properties": {
    "tokens_used": 350,
    "model": "gpt-4",       // groupBy field
    "region": "eu-west-1"   // another groupBy field
  }
}
```

### Filter Properties

If your Nutzungsmetrik has filters, include the filtered fields:

```json theme={null}
{
  "properties": {
    "tokens_used": 350,
    "status_code": 200  // filter: status_code in [200, 201, 204]
  }
}
```

***

## Legacy: Subscription Measurements

For existing integrations using subscription-based measurements:

```bash theme={null}
curl -X POST https://coreapi.io/subscription-measurements/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "values": [
      {
        "subscription": "SUBSCRIPTION_ID",
        "subscriptionItem": "SUBSCRIPTION_ITEM_ID",
        "measurementCode": "used_traffic",
        "quantity": "1",
        "measuredAt": "2026-01-15T00:00:00Z"
      }
    ]
  }'
```

See: [API Reference](/api-reference/subscription-measurement/add-a-batch-of-subscription-measurement)

***

## Best Practices

### Timestamps

Always use UTC in ISO 8601 format:

```
✅ 2026-01-15T14:30:00Z
✅ 2026-01-15T14:30:00+00:00
❌ 2026-01-15 14:30:00
❌ 1705329000 (Unix timestamp)
```

### Batch Sizes

| Scenario           | Recommended Batch Size            |
| ------------------ | --------------------------------- |
| Real-time tracking | 10-100 events                     |
| Bulk import        | 500-1000 events                   |
| High volume        | Buffer and send every 1-5 seconds |

### Error Handling

```javascript theme={null}
async function sendEvents(events) {
  const response = await fetch('https://coreapi.io/api/usage-events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ events })
  });

  const result = await response.json();

  if (result.failed > 0) {
    // Retry failed events or log for manual review
    console.error('Failed events:', result.errors);
  }

  return result;
}
```

***

## Related Documentation

* [Nutzungsmetriken](/guide/catalogue/measurements/billable-metrics) - Konfiguriere was und wie gemessen wird
* [Nutzungsereignisse](/guide/catalogue/usage-events-import) - CSV Import und UI Optionen
* [Aggregationstypen](/guide/catalogue/measurements/aggregation-types/overview) - Summe, Anzahl, Maximum, etc.


# Enable manual invoice checks
Source: https://docs.fynn.eu/api-reference/guides/enable-manual-invoice-check

Learn how to enable manual invoice checks for all customers.

# Enable for all customers

Enable it for all existing customers and disable it for upcoming customers without changing settings.

<Tip>
  This is useful if you are migrating your subscriptions from another system and are not sure if those send invoices are correct.
</Tip>

## Set global tenant settings

To set global tenant settings, execute the following api request:

```bash theme={null}
curl --request PATCH \
    --url https://coreapi.io/settings \
    --header 'Authorization : Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/merge-patch+json' \
    --data '{
        "settings": [
            {
                "key": "requiresManualInvoiceApproval",
                "value": false
            }
        ]
    }'
```

## Enable for all existing customers

To enable manual invoice checks for all existing customers, execute the following api request:

1. Get all customers

```bash theme={null}
curl --request GET \
    --url https://coreapi.io/customers?limit=100 \
    --header 'Authorization : Bearer YOUR_API_KEY'
```

2. Update each customer

```bash theme={null}
curl --request PATCH \
    --url https://coreapi.io/customers/{customerId}/settings/billing \
    --header 'Authorization : Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/merge-patch+json' \
    --data '{
        "requiresManualInvoiceApproval": true
    }'
```

### Example script

A javascript example to enable manual invoice checks for all customers:

```js theme={null}
const apiKey = 'YOUR_API_KEY';

const getCustomers = async (page: number = 1) => {
    const customers = await fetch('https://coreapi.io/customers?limit=100&page=' + page, {
        headers: {
            Authorization: `Bearer ${apiKey}`
        }
    }).then(res => res.json());

    return customers;
};

const updateCustomer = async (customerId: string): void => {
    await fetch(`https://coreapi.io/customers/${customerId}/settings/billing`, {
        method: 'PATCH',
        headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/merge-patch+json'
        },
        body: JSON.stringify({
            requiresManualInvoiceApproval: true
        })
    });
};

const enableManualInvoiceChecks = async () => {
    let page = 1;
    let customers = await getCustomers(page);

    while (customers.length > 0) {
        for (const customer of customers) {
            await updateCustomer(customer.id);
        }

        page++;
        customers = await getCustomers(page);
    }
};

enableManualInvoiceChecks();
```


# Implement Self-Service Upgrades
Source: https://docs.fynn.eu/api-reference/guides/implement-upgrades

Integrate product group-based upgrades and downgrades into your application

This guide shows you how to implement self-service upgrades and downgrades using product groups in your application.

## Overview

The upgrade/downgrade flow consists of three main steps:

1. **Check eligibility** - Get available change options for a subscription item
2. **Display options** - Show the customer available upgrades/downgrades
3. **Apply change** - Execute the selected package change

***

## Prerequisites

Before implementing upgrades:

1. Create a **Product Group** with a tier for each package level
2. Assign the product group to the subscription item via `PUT /subscription-items/{id}/product-group`

***

## Step 1: Get Change Options

Fetch available upgrade/downgrade options for a subscription item:

```bash theme={null}
curl -X GET "https://coreapi.io/subscription-items/{itemId}/change-options" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "current": {
    "id": "tier-starter-uuid",
    "name": "Starter Plan",
    "pricePlan": {
      "id": "price-starter-uuid",
      "name": "Starter Monthly",
      "price": 2900,
      "billingInterval": "monthly"
    },
    "product": {
      "id": "product-starter-uuid",
      "name": "Starter"
    }
  },
  "options": [
    {
      "id": "tier-pro-uuid",
      "label": "Pro",
      "product": {
        "id": "product-pro-uuid",
        "name": "Pro Plan"
      },
      "pricePlans": [
        {
          "id": "price-pro-monthly-uuid",
          "name": "Pro Monthly",
          "price": 4900,
          "billingInterval": "monthly"
        }
      ],
      "changeTiming": "immediately",
      "creditType": "pro_rata",
      "isUpgrade": true,
      "isDowngrade": false,
      "quantitySetting": null
    }
  ],
  "hasPendingChange": false
}
```

### Response Fields

| Field                    | Description                             |
| ------------------------ | --------------------------------------- |
| `current`                | Currently active tier and price plan    |
| `options`                | Available upgrade/downgrade options     |
| `options[].isUpgrade`    | `true` if this is an upgrade            |
| `options[].isDowngrade`  | `true` if this is a downgrade           |
| `options[].changeTiming` | When the change takes effect            |
| `options[].creditType`   | How unused time is credited             |
| `hasPendingChange`       | `true` if a change is already scheduled |

<Warning>
  If `hasPendingChange` is `true`, no further changes can be made until the pending change is applied.
</Warning>

***

## Step 2: Display Options to Customer

Use the response to build a selection UI:

```javascript theme={null}
async function getUpgradeOptions(subscriptionItemId) {
  const response = await fetch(
    `/subscription-items/${subscriptionItemId}/change-options`,
    { headers: { Authorization: `Bearer ${token}` } }
  );

  const data = await response.json();

  // Check if changes are possible
  if (data.hasPendingChange) {
    return { error: 'A change is already pending' };
  }

  if (data.options.length === 0) {
    return { error: 'No upgrade options available' };
  }

  // Separate upgrades and downgrades
  const upgrades = data.options.filter(o => o.isUpgrade);
  const downgrades = data.options.filter(o => o.isDowngrade);

  return { current: data.current, upgrades, downgrades };
}
```

***

## Step 3: Apply the Change

When the customer selects an option, apply the change:

```bash theme={null}
curl -X POST "https://coreapi.io/product-group-memberships/{tierId}/apply" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subscriptionItem": "subscription-item-uuid",
    "quantity": 1
  }'
```

### Request Parameters

| Parameter           | Type    | Required | Description                                                                                                     |
| ------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `subscriptionItem`  | string  | Yes      | UUID of the subscription item to change                                                                         |
| `selectedPricePlan` | string  | No       | UUID of the price plan. Only required if the tier has multiple price plans. In most cases, this can be omitted. |
| `quantity`          | integer | No       | New quantity. Only applied if the tier allows quantity changes.                                                 |
| `sendInvoiceEmail`  | boolean | No       | Send credit note via email (default: `true`)                                                                    |

### Response

```json theme={null}
{
  "subscriptionItem": {
    "id": "item-uuid",
    "product": { "id": "...", "name": "Pro Plan" },
    "pricePlan": { "id": "...", "name": "Pro Monthly" },
    "status": "active"
  },
  "creditNote": {
    "id": "credit-note-uuid",
    "number": "CN-2026-0001",
    "amount": 1450
  }
}
```

***

## Change Timing Behavior

### Immediately

The change takes effect right away:

1. Current subscription item is ended
2. Credit note is created (based on `creditType`)
3. New subscription item is created and starts immediately
4. New invoice is generated

### End of Period

The change is scheduled for the next billing cycle:

1. Current subscription item continues until period end
2. At period end, item switches to new product/plan
3. No credit note is created
4. Next invoice uses new pricing

***

## Credit Types

When `changeTiming` is `immediately`, a credit is issued based on `creditType`:

| Type            | Formula                                   | Example                |
| --------------- | ----------------------------------------- | ---------------------- |
| `pro_rata`      | Price × (Days remaining / Days in period) | €29 × (15/30) = €14.50 |
| `full`          | Full period price                         | €29.00                 |
| `last_invoiced` | Amount from last invoice                  | Varies                 |
| `none`          | No credit                                 | €0.00                  |

***

## Complete Example

```javascript theme={null}
async function upgradeSubscription(subscriptionItemId, targetTierId) {
  // 1. Get current options to validate
  const options = await fetch(
    `/subscription-items/${subscriptionItemId}/change-options`,
    { headers: { Authorization: `Bearer ${token}` } }
  ).then(r => r.json());

  if (options.hasPendingChange) {
    throw new Error('Cannot change: pending change exists');
  }

  // 2. Find the selected option
  const selectedOption = options.options.find(o => o.id === targetTierId);
  if (!selectedOption) {
    throw new Error('Invalid tier selected');
  }

  // 3. Apply the change
  const result = await fetch(
    `/product-group-memberships/${targetTierId}/apply`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`
      },
      body: JSON.stringify({
        subscriptionItem: subscriptionItemId,
        quantity: 1
      })
    }
  ).then(r => r.json());

  return {
    newItem: result.subscriptionItem,
    creditNote: result.creditNote
  };
}
```

***

## Error Handling

| HTTP Status | Cause                       | Solution                            |
| ----------- | --------------------------- | ----------------------------------- |
| 400         | Invalid request             | Check required fields               |
| 404         | Subscription item not found | Verify item UUID                    |
| 422         | Pending change exists       | Wait for pending change to complete |
| 422         | Not eligible for change     | Check tier eligibility settings     |

***

## Webhooks

Listen for these events to track changes:

| Event                  | Description                           |
| ---------------------- | ------------------------------------- |
| `subscription.updated` | Subscription items changed            |
| `invoice.created`      | New invoice for upgraded subscription |
| `credit_note.created`  | Credit note for prorated amount       |

***

## Related Documentation

<CardGroup>
  <Card title="Product Groups" icon="layer-group" href="/guide/catalogue/product-groups">
    Set up product groups
  </Card>

  <Card title="Subscription Transitions" icon="arrow-right-arrow-left" href="/guide/subscriptions/transitions">
    Manual transitions
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guide/webhooks/introduction">
    Listen for events
  </Card>
</CardGroup>


# Wallet Payout
Source: https://docs.fynn.eu/api-reference/guides/wallet-payout

Pay out a customer wallet balance to their bank account via SEPA credit transfer over the API.

The Wallet Payout API pays out a customer's wallet balance to a bank account. Fynn debits the balance immediately and generates a SEPA credit transfer. How the transfer reaches your bank depends on the configured submission mode: in **manual mode** (default) you download the generated SEPA file and submit it to your bank yourself, then confirm the upload so the payout moves to `submitted`; in **automatic mode** Fynn submits it over EBICS. The payout is only finalized once the bank confirms the transfer via the account statement.

<Info>
  Bank payouts are subject to origin-based routing rules. A wallet balance can only be paid out to a bank account if it originated from a bank transfer or an in-house SEPA direct debit. Balance funded by card, PayPal, or GoCardless must be refunded through the original channel. See [Origin routing](#origin-routing) below.
</Info>

## Create a Payout

```bash theme={null}
curl -X POST https://coreapi.io/api/customers/CUSTOMER_ID/wallet/payouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": 5000,
    "currencyCode": "EUR",
    "reference": "Wallet payout March 2026"
  }'
```

**Response (201 Created):**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "amount": 5000,
  "currencyCode": "EUR",
  "endingBalance": 0,
  "recipientIban": "DE89 **** **** **** **89",
  "endToEndId": "WP2026030812345678",
  "createdAt": "2026-03-08T10:00:00Z"
}
```

### Request Fields

| Field           | Type    | Required | Description                                                                      |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `amount`        | integer | Yes      | Payout amount in the smallest currency unit (cents). Must be greater than `0`    |
| `currencyCode`  | string  | Yes      | ISO 4217 currency code (e.g. `EUR`)                                              |
| `iban`          | string  | No       | Recipient IBAN. Defaults to the customer's stored bank connection (SEPA mandate) |
| `bic`           | string  | No       | Recipient BIC, when an explicit `iban` is provided                               |
| `accountHolder` | string  | No       | Recipient account holder name. Defaults to the customer's display name           |
| `reference`     | string  | No       | Remittance reference shown on the bank statement (max 140 characters)            |
| `description`   | string  | No       | Internal description of the payout (max 140 characters)                          |

<Note>
  Amounts are integers in cents, not decimals. `5000` means `50,00 EUR`.
</Note>

### Response Fields

| Field           | Type    | Description                                                        |
| --------------- | ------- | ------------------------------------------------------------------ |
| `id`            | string  | Payout UUID                                                        |
| `status`        | string  | Payout status (`created` on success)                               |
| `amount`        | integer | Payout amount in cents                                             |
| `currencyCode`  | string  | ISO 4217 currency code                                             |
| `endingBalance` | integer | Remaining wallet balance in cents after the payout was booked      |
| `recipientIban` | string  | Masked recipient IBAN                                              |
| `endToEndId`    | string  | Unique end-to-end reference used to match the bank statement entry |
| `createdAt`     | string  | ISO 8601 timestamp                                                 |

<Tip>
  Without an `iban`, the payout uses the customer's stored bank connection (the active SEPA mandate's bank account). Pass an explicit `iban` to pay out to a different account; it is recorded on the payout for audit.
</Tip>

## Payout Status

A payout moves through a fixed lifecycle:

| Status      | Description                                                                                                                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created`   | Payout booked, wallet balance debited. The credit transfer is waiting to be submitted: in manual mode until you download the SEPA file and confirm the upload, in automatic mode until Fynn submits it over EBICS |
| `submitted` | The credit transfer was submitted to the bank, either after you confirmed the upload (manual mode) or over EBICS (automatic mode)                                                                                 |
| `executed`  | The bank executed the transfer, confirmed via the account statement. Terminal state                                                                                                                               |
| `failed`    | Submission failed. The wallet booking was automatically reversed and the balance restored. Terminal state                                                                                                         |

<Warning>
  `created` does not mean the money has left the bank account yet. The payout is only complete once it reaches `executed`. Subscribe to the [webhooks](#webhooks) to react to the terminal states.
</Warning>

## Origin Routing

Fynn records the origin of every wallet inflow and enforces where the balance may flow back. A bank payout is only allowed when every funding portion of the payout comes from an allowed origin.

| Origin of the balance        | Bank payout | Correct alternative                  |
| ---------------------------- | ----------- | ------------------------------------ |
| Bank transfer                | Allowed     | Payout via SEPA credit transfer      |
| SEPA direct debit (in-house) | Allowed     | Payout via SEPA credit transfer      |
| Card (Stripe, Unzer)         | Blocked     | Refund via the original card         |
| PayPal                       | Blocked     | Refund via PayPal                    |
| GoCardless                   | Blocked     | Refund via GoCardless                |
| Missing / unknown origin     | Blocked     | Manual review, then original channel |

A blocked payout is **not** booked. The request returns `422` with an error code identifying the reason. Mixed funding follows an all-or-nothing rule: a single blocked portion blocks the entire payout.

## Error Handling

| Status Code | Error Code                               | Scenario                                                                                                                                                                              |
| ----------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `422`       | `CUSTOMER_BALANCE__NEGATIVE_NOT_ALLOWED` | Insufficient wallet balance for the requested amount                                                                                                                                  |
| `422`       | `WALLET_PAYOUT__ROUTE_NOT_ALLOWED`       | Balance origin does not permit a bank payout (e.g. card-funded)                                                                                                                       |
| `422`       | `WALLET_PAYOUT__ROUTE_UNKNOWN_ORIGIN`    | Origin of the balance is unknown and requires manual review                                                                                                                           |
| `422`       | `WALLET_PAYOUT__MISSING_BANK_DATA`       | No recipient bank connection available and no `iban` provided                                                                                                                         |
| `422`       | `WALLET_PAYOUT__NOT_CONFIGURED`          | Required configuration is missing. In manual mode this means the SEPA credit transfer settings (sender bank account); in automatic mode it additionally requires the EBICS connection |
| `404`       | (none)                                   | Unknown customer                                                                                                                                                                      |

<Note>
  When a payout is blocked or rejected, nothing is booked. The wallet balance stays exactly as it was before the request.
</Note>

## Webhooks

Subscribe to these events to react to the terminal states of a payout. Both carry the same payload shape.

| Event                    | When                                                                          |
| ------------------------ | ----------------------------------------------------------------------------- |
| `wallet.payout.executed` | The bank executed the transfer and it was confirmed via the account statement |
| `wallet.payout.failed`   | Submission failed; the wallet balance was automatically restored              |

**Payload:**

```json theme={null}
{
  "payoutId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "amount": 5000,
  "currencyCode": "EUR",
  "status": "executed",
  "endToEndId": "WP2026030812345678",
  "reference": "Wallet payout March 2026",
  "failReason": null,
  "executedAt": "2026-03-10T08:15:00Z",
  "failedAt": null
}
```

| Field          | Type           | Description                                                 |
| -------------- | -------------- | ----------------------------------------------------------- |
| `payoutId`     | string         | Payout UUID                                                 |
| `customerId`   | string         | Customer UUID                                               |
| `amount`       | integer        | Payout amount in cents                                      |
| `currencyCode` | string         | ISO 4217 currency code                                      |
| `status`       | string         | `executed` or `failed`                                      |
| `endToEndId`   | string         | End-to-end reference matching the bank statement entry      |
| `reference`    | string         | Remittance reference of the payout                          |
| `failReason`   | string \| null | Reason for failure; `null` for executed payouts             |
| `executedAt`   | string \| null | ISO 8601 timestamp when executed; `null` for failed payouts |
| `failedAt`     | string \| null | ISO 8601 timestamp when failed; `null` for executed payouts |

See [Webhooks](/guide/webhooks/introduction) for signature verification and setup.

## Related Documentation

* [Guthaben auszahlen (Benutzerhandbuch)](/guide/invoices/wallet-payout) - Step-by-step guide and origin rules
* [Kundenguthaben](/guide/invoices/wallet-balance) - How the wallet balance works
* [Wallet Top-Up](/api-reference/guides/wallet-top-up) - Adding funds to a wallet balance


# Wallet Top-Up
Source: https://docs.fynn.eu/api-reference/guides/wallet-top-up

Initiate manual wallet top-ups and manage auto top-up rules via the API.

The Wallet Top-Up API lets you programmatically add funds to a customer's wallet balance by initiating payment collection, and configure automatic top-up rules that trigger when the balance drops below a threshold.

## Manual Top-Up

### Initiate a Top-Up

```bash theme={null}
curl -X POST https://coreapi.io/api/wallet/top-up \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100.00,
    "currencyCode": "EUR"
  }'
```

**Response (201 Created):**

```json theme={null}
{
  "id": "top_abc123",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "requestedAmount": { "amount": 10000, "currencyCode": "EUR" },
  "creditedAmount": null,
  "status": "pending",
  "paymentMethodId": null,
  "createdAt": "2026-03-08T10:00:00Z",
  "completedAt": null
}
```

| Field             | Type   | Required | Description                                                                 |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `customerId`      | string | Yes      | Customer UUID                                                               |
| `amount`          | number | Yes      | Top-up amount (e.g. `100.00`)                                               |
| `currencyCode`    | string | Yes      | ISO 4217 currency code (e.g. `EUR`)                                         |
| `paymentMethodId` | string | No       | Specific payment method UUID. Defaults to customer's default payment method |

<Tip>
  The top-up creates a PaymentIntent that collects the funds. Once the payment succeeds, the amount is credited to the customer's wallet.
</Tip>

### List Top-Ups

```bash theme={null}
curl https://coreapi.io/api/wallet/top-ups?customerId=CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response (200 OK):**

```json theme={null}
{
  "items": [
    {
      "id": "top_abc123",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "requestedAmount": { "amount": 10000, "currencyCode": "EUR" },
      "creditedAmount": { "amount": 10000, "currencyCode": "EUR" },
      "status": "completed",
      "paymentMethodId": null,
      "failureReason": null,
      "createdAt": "2026-03-08T10:00:00Z",
      "completedAt": "2026-03-08T10:01:00Z"
    }
  ],
  "count": 1
}
```

### Top-Up Status

| Status      | Description                            |
| ----------- | -------------------------------------- |
| `pending`   | Payment initiated, awaiting completion |
| `completed` | Payment succeeded, balance credited    |
| `failed`    | Payment failed, no balance change      |

### Get a Single Top-Up

```bash theme={null}
curl https://coreapi.io/api/wallet/top-ups/TOP_UP_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Auto Top-Up Rules

Auto top-up rules automatically initiate a top-up when a customer's wallet balance drops below a configured threshold.

### Create a Rule

```bash theme={null}
curl -X POST https://coreapi.io/api/wallet/auto-top-up \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "currencyCode": "EUR",
    "thresholdAmount": 10.00,
    "topUpAmount": 100.00
  }'
```

**Response (201 Created):**

```json theme={null}
{
  "id": "atr_xyz789",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "currencyCode": "EUR",
  "thresholdAmount": 10.00,
  "topUpAmount": 100.00,
  "paymentMethodId": null,
  "enabled": true,
  "consecutiveFailures": 0,
  "createdAt": "2026-03-08T10:00:00Z",
  "updatedAt": "2026-03-08T10:00:00Z"
}
```

| Field             | Type   | Required | Description                                               |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| `customerId`      | string | Yes      | Customer UUID                                             |
| `currencyCode`    | string | Yes      | ISO 4217 currency code                                    |
| `thresholdAmount` | number | Yes      | Balance threshold that triggers auto top-up (must be > 0) |
| `topUpAmount`     | number | Yes      | Amount to top up (must be > 0)                            |
| `paymentMethodId` | string | No       | Specific payment method. Defaults to customer's default   |

<Note>
  Only one rule per customer per currency is allowed. Attempting to create a duplicate returns `400 Bad Request`.
</Note>

### List Rules

```bash theme={null}
curl https://coreapi.io/api/wallet/auto-top-up?customerId=CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Update a Rule

```bash theme={null}
curl -X PUT https://coreapi.io/api/wallet/auto-top-up/RULE_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "thresholdAmount": 20.00,
    "topUpAmount": 200.00,
    "enabled": false
  }'
```

All fields are optional — only include the fields you want to change.

| Field             | Type    | Description                     |
| ----------------- | ------- | ------------------------------- |
| `thresholdAmount` | number  | New threshold (must be > 0)     |
| `topUpAmount`     | number  | New top-up amount (must be > 0) |
| `paymentMethodId` | string  | New payment method UUID         |
| `enabled`         | boolean | Enable or disable the rule      |

### Delete a Rule

```bash theme={null}
curl -X DELETE https://coreapi.io/api/wallet/auto-top-up/RULE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns `204 No Content` on success.

***

## How Auto Top-Up Works

1. A balance-reducing transaction occurs (e.g., wallet balance applied to an invoice)
2. Fynn checks if an enabled auto top-up rule exists for the customer and currency
3. If the ending balance is below the threshold, a top-up is initiated automatically
4. The top-up follows the same flow as a manual top-up (PaymentIntent → payment → credit)

**Safety mechanisms:**

* Top-up transactions themselves do **not** trigger auto top-up (prevents loops)
* The `consecutiveFailures` counter tracks sequential failures — monitor this to detect broken payment methods
* The feature must be enabled via the `WalletTopUp` feature flag

***

## Customer-Authenticated Requests

Customers authenticated via the customer portal can manage their own wallet:

* **Top-up**: `customerId` is inferred from the authenticated session (do not include it)
* **Auto top-up rules**: Customers can only view/manage their own rules
* Attempting to access another customer's data returns `403 Forbidden`

```bash theme={null}
# Customer-authenticated top-up (no customerId needed)
curl -X POST https://coreapi.io/api/wallet/top-up \
  -H "Authorization: Bearer CUSTOMER_TOKEN" \
  -d '{
    "amount": 50.00,
    "currencyCode": "EUR"
  }'
```

***

## Error Handling

| Status Code                | Scenario                                                           |
| -------------------------- | ------------------------------------------------------------------ |
| `400 Bad Request`          | Missing required field, duplicate rule for same currency           |
| `403 Forbidden`            | Feature not enabled, or customer accessing another customer's data |
| `404 Not Found`            | Rule or top-up not found                                           |
| `422 Unprocessable Entity` | Invalid amounts (zero, negative), invalid currency code            |

***

## Integration Example

```javascript theme={null}
const FYNN_API = 'https://coreapi.io';
const API_KEY = process.env.FYNN_API_KEY;

async function ensureWalletFunded(customerId, minBalance = 10, topUpAmount = 100) {
  // Check if auto top-up rule exists
  const rules = await fetch(
    `${FYNN_API}/api/wallet/auto-top-up?customerId=${customerId}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  ).then(r => r.json());

  if (rules.items.length === 0) {
    // Create auto top-up rule
    await fetch(`${FYNN_API}/api/wallet/auto-top-up`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`,
      },
      body: JSON.stringify({
        customerId,
        currencyCode: 'EUR',
        thresholdAmount: minBalance,
        topUpAmount: topUpAmount,
      }),
    });
  }
}
```

***

## Related Documentation

* [Kundenguthaben](/guide/invoices/wallet-balance) - Wie das Wallet-Guthaben funktioniert
* [Wallet aufladen (Benutzerhandbuch)](/guide/invoices/wallet-top-up) - Schritt-für-Schritt-Anleitung
* [Zahlungsmethoden hinzufügen](/api-reference/guides/add-payment-method) - Payment method setup


# Getting started
Source: https://docs.fynn.eu/api-reference/introduction

Welcome to the API reference documentation for the Fynn API.

Welcome to Fynn API documentation! This guide is designed to streamline the integration process
and provide you with all the necessary resources to seamlessly incorporate Fynn into your systems.
Whether you're managing subscriptions for a SaaS platform, digital content, or any other recurring billing needs,
our API aims to simplify complex billing operations, empowering you to focus on your core business.

<Tip>
  <b>Sandbox environment</b>

  <br />

  Before you start integrating with the Fynn API, you can test your application in a sandbox environment,
  where you can create and manage subscriptions without any financial implications.

  Contact our support team to get access to the sandbox environment.
</Tip>

The Fynn API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

## Endpoints

We provide the following endpoints:

* **Production**:
  * API: `https://coreapi.io`
  * Frontend: `https://app.fynn.eu`
  * Customerfront: `https://customerfront.app`
* **Playground**:
  * API: `https://preview.coreapi.io`
  * Frontend: `https://preview.fynn.eu`
  * Customerfront: `https://preview.customerfront.app`

<Note>
  <b>Customerfront</b>

  <br />

  The customerfront.app serves any customer-facing pages, such as the customer portal, checkout, and offer pages.
</Note>


# Create a measurement.
Source: https://docs.fynn.eu/api-reference/measurement/create-a-measurement

post /catalogue/measurements
Create a measurement.

<sup>Required permissions: `measurement:write`</sup>



# Delete a measurement.
Source: https://docs.fynn.eu/api-reference/measurement/delete-a-measurement

delete /catalogue/measurements/{id}
Delete a measurement. This is only allowed, if the measurement is not used in any plan or subscription.

<sup>Required permissions: `measurement:write`</sup>



# Get a measurement.
Source: https://docs.fynn.eu/api-reference/measurement/get-a-measurement

get /catalogue/measurements/{id}
Get a measurement.

<sup>Required permissions: `measurement:read`</sup>



# Get all measurements.
Source: https://docs.fynn.eu/api-reference/measurement/get-all-measurements

get /catalogue/measurements
Get all measurements.

<sup>Required permissions: `measurement:read`</sup>



# Update a measurement.
Source: https://docs.fynn.eu/api-reference/measurement/update-a-measurement

put /catalogue/measurements/{id}
Update a measurement.

<sup>Required permissions: `measurement:write`</sup>



# Migration: Measurements → Nutzungsmetriken
Source: https://docs.fynn.eu/api-reference/migrations/measurements-deprecation

Deprecation der Measurement-Endpunkte und Properties zugunsten der neuen Nutzungsmetriken

<Note>
  **Geplante Änderung** - Die Measurement-API und das `measurement` Property werden schrittweise durch das neue Nutzungsmetriken-System ersetzt.
</Note>

## Übersicht

Mit der Einführung der neuen **Nutzungsmetriken** wird das bisherige Measurement-System schrittweise abgelöst. Diese Seite beschreibt die Änderungen und wie du deine Integration anpassen kannst.

### Migrationspfad

| Phase       | Zeitraum | Änderung                                                                    |
| ----------- | -------- | --------------------------------------------------------------------------- |
| **Phase 1** | Aktuell  | Neues Nutzungsmetriken-System verfügbar, Measurements weiterhin unterstützt |
| **Phase 2** | Q1 2026  | `unit` Property wird neben `measurement` hinzugefügt                        |
| **Phase 3** | Q2 2026  | `measurement` Property wird deprecated (Warnung in Response)                |
| **Phase 4** | Q3 2026  | `measurement` Property wird entfernt, nur noch `unit`                       |

***

## Betroffene API Responses

Das `measurement` Property wird aktuell in folgenden API Responses zurückgegeben:

### Product Responses

**Endpunkte:**

* `GET /catalogue/products`
* `GET /catalogue/products/{id}`
* `POST /catalogue/products`
* `PUT /catalogue/products/{id}`

**Aktuelle Struktur:**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "measurement": {
    "id": "meas_xyz789",
    "code": "api_calls",
    "description": "Anzahl der API-Aufrufe",
    "aggregationType": "count",
    "type": "metered",
    "fairBilling": true,
    "unit": {
      "id": "unit_123",
      "name": "Stück"
    }
  }
}
```

**Zukünftige Struktur (Phase 2):**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "measurement": { ... },  // Bleibt zunächst erhalten
  "unit": {                // NEU: Zusätzlich auf Top-Level
    "id": "unit_123",
    "name": "Stück"
  }
}
```

**Finale Struktur (Phase 4):**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "unit": {
    "id": "unit_123",
    "name": "Stück"
  }
}
```

### Plan Responses (PlanResource)

**Endpunkte:**

* `GET /catalogue/plans`
* `GET /catalogue/plans/{id}`
* `POST /catalogue/plans`
* `PUT /catalogue/plans/{id}`

**Betroffen:** `measurement` Property im Plan-Objekt

### SubscriptionItem Responses

**Endpunkte:**

* `GET /subscription-items/{id}`
* `PATCH /subscription-items/{id}`

**Betroffen:** Nested `measurement` in Detail-Responses

### MeasurementValue Responses (Subscription Measurements)

**Endpunkte:**

* `GET /subscription-measurements/{id}`
* `POST /subscription-measurements`
* `POST /subscription-measurements/batch`

**Aktuelle Struktur:**

```json theme={null}
{
  "id": "mv_abc123",
  "measurement": {
    "id": "meas_xyz789",
    "code": "api_calls",
    "unit": {
      "id": "unit_123",
      "name": "Stück"
    }
  },
  "quantity": "150",
  "measuredAt": "2026-01-15T10:00:00Z"
}
```

***

## Deprecated Endpoints

<Warning>
  Die folgenden Endpunkte werden **Q3 2026** entfernt.
</Warning>

### Measurement CRUD Endpoints

| Endpoint                       | Method | Status         |
| ------------------------------ | ------ | -------------- |
| `/catalogue/measurements`      | GET    | **Deprecated** |
| `/catalogue/measurements`      | POST   | **Deprecated** |
| `/catalogue/measurements/{id}` | GET    | **Deprecated** |
| `/catalogue/measurements/{id}` | PUT    | **Deprecated** |
| `/catalogue/measurements/{id}` | DELETE | **Deprecated** |

**Ersatz:** Nutzungsmetrik direkt am Produkt konfigurieren.

### Subscription Measurement Endpoints

| Endpoint                           | Method | Status         | Ersatz                          |
| ---------------------------------- | ------ | -------------- | ------------------------------- |
| `/subscription-measurements`       | POST   | **Deprecated** | `POST /api/usage-events`        |
| `/subscription-measurements/batch` | POST   | **Deprecated** | `POST /api/usage-events`        |
| `/subscription-measurements/{id}`  | GET    | **Deprecated** | Usage über Subscription abrufen |

***

## SubscriptionItem Response Änderungen

### `currentMeasurementValue` wird ersetzt

<Warning>
  Das Property `currentMeasurementValue` wird deprecated und **Q3 2026** durch neue Properties ersetzt.
</Warning>

**Aktuelle Response:**

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "currentMeasurementValue": {
    "id": "mv_xyz",
    "quantity": "150",
    "measuredAt": "2026-01-15T10:00:00Z"
  }
}
```

**Zukünftige Response:**

Für **Produkte mit fester Menge** (nicht nutzungsbasiert):

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "quantity": "5",
  "unit": {
    "id": "unit_123",
    "name": "Benutzer"
  }
}
```

Für **nutzungsbasierte Produkte**:

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "quantity": null,
  "unit": {
    "id": "unit_123",
    "name": "API Calls"
  },
  "currentUsage": {
    "aggregatedValue": "1.523",
    "eventsCount": 47,
    "periodStart": "2026-01-01T00:00:00Z",
    "periodEnd": "2026-02-01T00:00:00Z"
  }
}
```

### Neue Properties

| Property       | Typ            | Beschreibung                                       |
| -------------- | -------------- | -------------------------------------------------- |
| `quantity`     | string \| null | Feste Menge (null für usage-based Produkte)        |
| `unit`         | object         | Einheit mit `id` und `name`                        |
| `currentUsage` | object \| null | Aggregierte Nutzung (nur für usage-based Produkte) |

### `currentUsage` Struktur

| Property          | Typ      | Beschreibung                                       |
| ----------------- | -------- | -------------------------------------------------- |
| `aggregatedValue` | string   | Der aggregierte Wert (z.B. Summe, Anzahl, Maximum) |
| `eventsCount`     | integer  | Anzahl der Ereignisse im Zeitraum                  |
| `periodStart`     | datetime | Beginn des aktuellen Abrechnungszeitraums          |
| `periodEnd`       | datetime | Ende des aktuellen Abrechnungszeitraums            |

<Tip>
  Für detaillierte Nutzungsdaten mit einzelnen Events verwende `GET /subscriptions/{id}/usage`.
</Tip>

### Manuelle Mengenänderungen werden ignoriert

<Warning>
  **Wichtig für Entwickler:** Produkte mit konfigurierter Nutzungsmetrik ignorieren manuelle Mengenänderungen.
</Warning>

### Aktuelles Verhalten

Bei Produkten mit Nutzungsmetrik wird die manuelle Mengenänderung am Subscription Item **ignoriert** (Legacy-Kompatibilität):

```bash theme={null}
# Wird für usage-based Produkte ignoriert
PATCH /subscription-items/{id}
{
  "quantity": 100
}
```

### Zukünftiges Verhalten (ab Q3 2026)

Ab Q3 2026 wird ein Fehler zurückgegeben:

```json theme={null}
{
  "error": {
    "code": "PRODUCT__QUANTITY_CHANGE_NOT_AVAILABLE_FOR_USAGE_BASED_PRODUCTS",
    "message": "Quantity changes are not available for usage-based products. Use usage events instead."
  }
}
```

### Korrekte Vorgehensweise

Für nutzungsbasierte Produkte muss die Menge über **Nutzungsereignisse** gesteuert werden:

```bash theme={null}
POST /api/usage-events
{
  "events": [{
    "transactionId": "unique-id",
    "eventName": "api_call",
    "timestamp": "2026-02-01T10:00:00Z",
    "customerId": "cust_123",
    "properties": {
      "endpoint": "/api/users"
    }
  }]
}
```

***

## Empfohlene Migration

<Note>
  Aktuell haben **alle Produkte** ein `measurement` (Pflichtfeld). Mit dem neuen System wird `measurement` komplett entfernt und durch `unit` ersetzt. Die Konfiguration der Nutzungsmetrik (Event-Name, Aggregation, Filter) erfolgt dann direkt am Produkt über "Nutzungsbasierte Abrechnung aktivieren".
</Note>

### Für API-Konsumenten

**Schritt 1:** Bereite deinen Code vor, das `unit` Property zu verwenden

```javascript theme={null}
// ❌ Bisher
const unitName = product.measurement?.unit?.name;

// ✅ Zukünftig (abwärtskompatibel)
const unitName = product.unit?.name ?? product.measurement?.unit?.name;
```

**Schritt 2:** Stelle Event-Ingestion um

```javascript theme={null}
// ❌ Bisher (deprecated)
await api.post('/subscription-measurements/batch', {
  values: [{
    subscription: 'sub_123',
    subscriptionItem: 'item_456',
    measurementCode: 'api_calls',
    quantity: '1',
    measuredAt: '2026-02-01T10:00:00Z'
  }]
});

// ✅ Neu
await api.post('/api/usage-events', {
  events: [{
    transactionId: 'tx_unique_123',
    eventName: 'api_call',
    timestamp: '2026-02-01T10:00:00Z',
    customerId: 'cust_789',
    properties: {
      endpoint: '/api/users',
      status_code: 200
    }
  }]
});
```

**Schritt 3:** Entferne Quantity-Updates für usage-based Produkte

```javascript theme={null}
// ❌ Nicht mehr verwenden
await api.patch(`/subscription-items/${itemId}`, { quantity: 100 });

// ✅ Mengen werden automatisch aus Events berechnet
```

***

## Zusammenfassung der Änderungen

| Bereich              | Aktuell                         | Zukünftig                |
| -------------------- | ------------------------------- | ------------------------ |
| **Product Response** | `measurement` mit nested `unit` | Nur `unit` (id, name)    |
| **Plan Response**    | `measurement` Property          | `unit` Property          |
| **SubscriptionItem** | `measurement` in Details        | `unit` Property          |
| **Verbrauchsdaten**  | `/subscription-measurements`    | `/api/usage-events`      |
| **Quantity Updates** | Ignoriert (Legacy)              | Fehler für usage-based   |
| **Measurement CRUD** | Eigene Endpoints                | Konfiguration am Produkt |

***

## Fragen?

Bei Fragen zur Migration kontaktiere uns:

* **E-Mail:** [developer@fynn.eu](mailto:developer@fynn.eu)
* **Support:** [support@fynn.eu](mailto:support@fynn.eu)

Oder buche einen [Termin mit unserem Team](https://cal.com/team/fynn/fynn-documentation).


# Create a new price plan.
Source: https://docs.fynn.eu/api-reference/priceplan/create-a-new-price-plan

post /price-plans
Create a new price plan.

<sup>Required permissions: `price-plan:write`</sup>



# Get a price.
Source: https://docs.fynn.eu/api-reference/priceplan/get-a-price

get /price-plans/{id}
Get a price for a product.

<sup>Required permissions: `price-plan:read`</sup>



# Get all prices.
Source: https://docs.fynn.eu/api-reference/priceplan/get-all-prices

get /price-plans
Get all prices for a product.

<sup>Required permissions: `price-plan:read`</sup>



# Update a price plan.
Source: https://docs.fynn.eu/api-reference/priceplan/update-a-price-plan

put /price-plans/{id}
Update a price plan. A price plan can only be updated, if it is not used by any subscription item. Otherwise you can archive the price plan.

<sup>Required permissions: `price-plan:write`</sup>



# Archive a product
Source: https://docs.fynn.eu/api-reference/product/archive-a-product

put /catalogue/products/{id}/archive
Archive a product

<sup>Required permissions: `product:write`</sup>



# Create a product
Source: https://docs.fynn.eu/api-reference/product/create-a-product

post /catalogue/products
Create a product

<sup>Required permissions: `product:write`</sup>



# Delete a product
Source: https://docs.fynn.eu/api-reference/product/delete-a-product

delete /catalogue/products/{id}
Delete a product

<sup>Required permissions: `product:write`</sup>



# Get a product
Source: https://docs.fynn.eu/api-reference/product/get-a-product

get /catalogue/products/{id}
Get a product

<sup>Required permissions: `product:read`</sup>



# Get products
Source: https://docs.fynn.eu/api-reference/product/get-products

get /catalogue/products
Get products

<sup>Required permissions: `product:read`</sup>



# Update a product
Source: https://docs.fynn.eu/api-reference/product/update-a-product

put /catalogue/products/{id}
Update a product

<sup>Required permissions: `product:write`</sup>



# Add products to a product family
Source: https://docs.fynn.eu/api-reference/productfamily/add-products-to-a-product-family

put /product-families/{id}/products
Add products to a product family

<sup>Required permissions: `product-family:write`</sup>



# Create a product family
Source: https://docs.fynn.eu/api-reference/productfamily/create-a-product-family

post /product-families
Create a product family

<sup>Required permissions: `product-family:write`</sup>



# Delete a product family
Source: https://docs.fynn.eu/api-reference/productfamily/delete-a-product-family

delete /product-families/{id}
Delete a product family

<sup>Required permissions: `product-family:write`</sup>



# Get a collection of product families
Source: https://docs.fynn.eu/api-reference/productfamily/get-a-collection-of-product-families

get /product-families
Get a collection of product families

<sup>Required permissions: `product-family:read`</sup>



# Get a product family
Source: https://docs.fynn.eu/api-reference/productfamily/get-a-product-family

get /product-families/{id}
Get a product family

<sup>Required permissions: `product-family:read`</sup>



# Get a product family tree
Source: https://docs.fynn.eu/api-reference/productfamily/get-a-product-family-tree

get /product-family-tree
Get a product family tree

<sup>Required permissions: `product-family:read`</sup>



# Update a product family
Source: https://docs.fynn.eu/api-reference/productfamily/update-a-product-family

put /product-families/{id}
Update a product family

<sup>Required permissions: `product-family:write`</sup>



# Change Tier
Source: https://docs.fynn.eu/api-reference/productgroup/apply-membership

post /product-group-memberships/{id}/apply
Apply a product group membership to a subscription item to perform an upgrade or downgrade.

Change the tier (membership) of a subscription item to perform an upgrade or downgrade.

## Flow

1. Get available options via `GET /subscription-items/{id}/change-options`
2. Select a tier from the options
3. Execute the tier change using this endpoint

## Request Parameters

| Parameter           | Required | Description                                                                                                                                                            |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscriptionItem`  | Yes      | UUID of the subscription item to change                                                                                                                                |
| `selectedPricePlan` | No       | UUID of the price plan. Only required if the tier has multiple price plans configured. In most cases, each tier has a single price plan and this field can be omitted. |
| `quantity`          | No       | New quantity. Only applied if the tier allows quantity changes.                                                                                                        |
| `sendInvoiceEmail`  | No       | Send credit note via email (default: `true`)                                                                                                                           |

## Response

Returns the updated subscription item and any created credit note.

<Card title="Implementation Guide" icon="code" href="/api-reference/guides/implement-upgrades">
  Complete guide for implementing self-service upgrades
</Card>


# Enable Up- & Downgrades
Source: https://docs.fynn.eu/api-reference/productgroup/assign-product-group

put /subscription-items/{id}/product-group
Assigns a product group membership to a subscription item, enabling up- and downgrades by the customer.

<sup>Required permissions: `subscription:write`</sup>

Assign a product group tier to a subscription item to enable up- and downgrades.

Once assigned, customers can change their tier in the customer portal, or you can trigger tier changes via the [Change Tier](/api-reference/productgroup/apply-membership) endpoint.

## Example

```bash theme={null}
curl -X PUT "https://coreapi.io/subscription-items/{itemId}/product-group" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "productGroupMembership": "membership-uuid"
  }'
```


# Create a product group
Source: https://docs.fynn.eu/api-reference/productgroup/create-product-group

post /catalogue/product-groups
Create a new product group for up- and downgrades.

<sup>Required permissions: `product-group:write`</sup>

Create a new product group for up- and downgrades.

## Memberships

Each membership represents a tier in the product group. The `position` field determines the upgrade/downgrade direction:

* Higher position = upgrade target
* Lower position = downgrade target

## Change Timing

* `immediately`: Change takes effect right away, credit is issued based on `creditType`
* `end_of_period`: Change takes effect at end of current billing period, no credit issued

## Credit Types

Only applicable when `changeTiming` is `immediately`:

| Type            | Description                    |
| --------------- | ------------------------------ |
| `pro_rata`      | Credit based on remaining days |
| `full`          | Full period credit             |
| `last_invoiced` | Credit of last invoice amount  |
| `none`          | No credit                      |


# Delete a product group
Source: https://docs.fynn.eu/api-reference/productgroup/delete-product-group

delete /catalogue/product-groups/{id}
Delete a product group. This will remove the product group from assigned subscription items.

<sup>Required permissions: `product-group:write`</sup>

Delete a product group.

<Warning>
  Deleting a product group will remove it from all assigned subscription items, making up- and downgrades impossible for those items.
</Warning>


# Get change options
Source: https://docs.fynn.eu/api-reference/productgroup/get-change-options

get /subscription-items/{id}/change-options
Get available upgrade and downgrade options for a subscription item. Only available if the item has a product group assigned.

<sup>Required permissions: `subscription:read`</sup>

Get available upgrade and downgrade options for a subscription item.

## Prerequisites

The subscription item must have a product group assigned via `PUT /subscription-items/{id}/product-group`.

## Response

The response includes:

* `current`: Information about the current membership and price plan
* `options`: Available upgrade/downgrade options
* `hasPendingChange`: Whether a change is already scheduled

<Note>
  If `hasPendingChange` is `true`, no further changes can be made until the pending change is applied.
</Note>


# Get a product group
Source: https://docs.fynn.eu/api-reference/productgroup/get-product-group

get /catalogue/product-groups/{id}
Get a product group by ID.

<sup>Required permissions: `product-group:read`</sup>

Get a single product group by ID.


# Get product groups
Source: https://docs.fynn.eu/api-reference/productgroup/get-product-groups

get /catalogue/product-groups
Get all product groups for up- and downgrades.

<sup>Required permissions: `product-group:read`</sup>

Get all product groups for up- and downgrades.

## Use Cases

* List all available product groups
* Display upgrade/downgrade configurations in admin UI
* Verify product group setup before enabling self-service changes

<Card title="Product Groups Guide" icon="book" href="/guide/catalogue/product-groups">
  Learn how to set up product groups for self-service upgrades
</Card>


# Update a product group
Source: https://docs.fynn.eu/api-reference/productgroup/update-product-group

put /catalogue/product-groups/{id}
Update a product group.

<sup>Required permissions: `product-group:write`</sup>

Update a product group.


# Create a new tenant
Source: https://docs.fynn.eu/api-reference/tenant/create-a-new-tenant

post /tenants
Creates a Tenant resource.



# Get a tenant
Source: https://docs.fynn.eu/api-reference/tenant/get-a-tenant

get /tenants/{id}
Retrieves a Tenant resource.

<sup>Required permissions: `tenant:manager`</sup>



# Get the tenants of the current user
Source: https://docs.fynn.eu/api-reference/tenant/get-the-tenants-of-the-current-user

get /user/tenants
Retrieves the collection of Tenant resources.

<sup>Required permissions: `ROLE_USER`</sup>



# Update a tenant
Source: https://docs.fynn.eu/api-reference/tenant/update-a-tenant

patch /tenants/{id}
Updates the Tenant resource.

<sup>Required permissions: `tenant:manager`</sup>



# Create a unit
Source: https://docs.fynn.eu/api-reference/unit/create-a-unit

post /units
Create a unit. Units will be used to define the unit of measure for products or invoice positions.

<sup>Required permissions: `unit:write`</sup>



# Get a unit
Source: https://docs.fynn.eu/api-reference/unit/get-a-unit

get /units/{id}
Get a unit

<sup>Required permissions: `unit:read`</sup>



# Get all units
Source: https://docs.fynn.eu/api-reference/unit/get-all-units

get /units
Get all units

<sup>Required permissions: `unit:read`</sup>



# Update a unit
Source: https://docs.fynn.eu/api-reference/unit/update-a-unit

put /units/{id}
Update a unit

<sup>Required permissions: `unit:write`</sup>



# Usage Events API
Source: https://docs.fynn.eu/api-reference/usage-events/overview

API endpoints for usage-based billing event ingestion and retrieval.

Die Usage Events API ermöglicht das Senden und Abrufen von Nutzungsereignissen für nutzungsbasierte Abrechnung.

## Base URL

```
https://coreapi.io
```

## Authentifizierung

Alle Endpoints erfordern einen API-Token im Header:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Endpoints

| Method | Endpoint                     | Beschreibung                         |
| ------ | ---------------------------- | ------------------------------------ |
| POST   | `/api/usage-events`          | Nutzungsereignisse senden (Batch)    |
| GET    | `/api/usage-events`          | Nutzungsereignisse abrufen           |
| GET    | `/api/usage-events/[id]`     | Einzelnes Ereignis abrufen           |
| GET    | `/api/usage-events/discover` | Event-Namen und Properties entdecken |

***

## POST /api/usage-events

Sende bis zu 1000 Nutzungsereignisse in einem Request.

### Request

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "events": [
      {
        "transactionId": "tx-001",
        "eventName": "ai_request",
        "timestamp": "2026-02-01T10:00:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "tokens_used": 350,
          "model": "gpt-4"
        }
      }
    ]
  }'
```

### Request Body

<ParamField type="array">
  Array von Nutzungsereignissen (1-1000 Events)

  <Expandable title="Event-Objekt">
    <ParamField type="string">
      Eindeutige ID für Idempotenz. Doppelte transactionIds werden ignoriert.
    </ParamField>

    <ParamField type="string">
      Name des Events. Muss mit dem konfigurierten Event-Namen der Nutzungsmetrik übereinstimmen.
    </ParamField>

    <ParamField type="string">
      Zeitstempel im ISO 8601 Format (z.B. `2026-02-01T10:00:00Z`)
    </ParamField>

    <ParamField type="string">
      Kunden-Identifier. Akzeptiert die Fynn-UUID **oder** die externe Kundennummer (`externalId`). Fynn erkennt automatisch, welches Format übergeben wird.
    </ParamField>

    <ParamField type="object">
      Beliebige Event-Eigenschaften für Aggregation, Filter und Gruppierung
    </ParamField>
  </Expandable>
</ParamField>

<Tip>
  Du kannst im Feld `customerId` auch die externe Kundennummer (`externalId`) übergeben. Fynn erkennt automatisch, ob es sich um eine UUID oder eine externe ID handelt. Die `externalId` wird am Kunden unter [Kundeneinstellungen](/guide/customers/settings) hinterlegt.
</Tip>

### Response (202 Accepted)

```json theme={null}
{
  "ingested": 1,
  "failed": 0,
  "errors": []
}
```

<ResponseField name="ingested" type="integer">
  Anzahl erfolgreich verarbeiteter Events
</ResponseField>

<ResponseField name="failed" type="integer">
  Anzahl fehlgeschlagener Events
</ResponseField>

<ResponseField name="errors" type="array">
  Details zu fehlgeschlagenen Events

  <Expandable title="Error-Objekt">
    <ResponseField name="index" type="integer">
      Index des fehlgeschlagenen Events im Request-Array
    </ResponseField>

    <ResponseField name="transactionId" type="string">
      TransactionId des fehlgeschlagenen Events
    </ResponseField>

    <ResponseField name="error" type="string">
      Fehlermeldung
    </ResponseField>
  </Expandable>
</ResponseField>

***

## GET /api/usage-events

Rufe Nutzungsereignisse mit Paginierung und Filtern ab.

### Request

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events?customerId=550e8400-e29b-41d4-a716-446655440000&eventName=ai_request&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Query Parameter

<ParamField type="string">
  Filtere nach Kunden-UUID
</ParamField>

<ParamField type="string">
  Filtere nach Event-Name
</ParamField>

<ParamField type="string">
  Filtere nach Zeitraum (ISO 8601)
</ParamField>

<ParamField type="string">
  Sortierfeld: `timestamp` oder `createdAt`
</ParamField>

<ParamField type="string">
  Sortierreihenfolge: `ASC` oder `DESC`
</ParamField>

<ParamField type="string">
  Paginierungs-Cursor für nächste Seite
</ParamField>

<ParamField type="integer">
  Anzahl Ergebnisse pro Seite (max. 100)
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "data": [
    {
      "id": "01HQXYZ123456789ABCDEFGH",
      "transactionId": "tx-001",
      "eventName": "ai_request",
      "timestamp": "2026-02-01T10:00:00Z",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "properties": {
        "tokens_used": 350,
        "model": "gpt-4"
      },
      "createdAt": "2026-02-01T10:00:05Z"
    }
  ],
  "meta": {},
  "pagination": {
    "cursor": "eyJpZCI6IjAxSFFYWVoxMjM0NTY3ODlBQkNERUZHSCJ9"
  }
}
```

***

## GET /api/usage-events/\[id]

Rufe ein einzelnes Nutzungsereignis ab.

### Request

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events/01HQXYZ123456789ABCDEFGH" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameter

<ParamField type="string">
  UUID oder ULID des Nutzungsereignisses
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "id": "01HQXYZ123456789ABCDEFGH",
  "transactionId": "tx-001",
  "eventName": "ai_request",
  "timestamp": "2026-02-01T10:00:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "properties": {
    "tokens_used": 350,
    "model": "gpt-4"
  },
  "createdAt": "2026-02-01T10:00:05Z"
}
```

***

## GET /api/usage-events/discover

Entdecke automatisch Event-Namen und Properties aus bereits gesendeten Events. Nützlich für die Konfiguration von Nutzungsmetriken.

### Request

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events/discover?limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Query Parameter

<ParamField type="string">
  Filtere nach spezifischem Event-Namen
</ParamField>

<ParamField type="integer">
  Anzahl Events zur Analyse (max. 10000)
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "eventNames": [
    {
      "name": "ai_request",
      "sampleProperties": {
        "tokens_used": 350,
        "model": "gpt-4"
      }
    },
    {
      "name": "api_call",
      "sampleProperties": {
        "endpoint": "/api/users",
        "status_code": 200
      }
    }
  ],
  "allProperties": [
    {
      "path": "tokens_used",
      "type": "number",
      "eventName": "ai_request",
      "sampleValues": [150, 350, 500]
    },
    {
      "path": "model",
      "type": "string",
      "eventName": "ai_request",
      "sampleValues": ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"]
    }
  ],
  "exampleEvents": [
    {
      "eventName": "ai_request",
      "properties": {
        "tokens_used": 350,
        "model": "gpt-4"
      },
      "timestamp": "2026-02-01T10:00:00Z"
    }
  ]
}
```

<ResponseField name="eventNames" type="array">
  Liste aller gefundenen Event-Namen mit Beispiel-Properties
</ResponseField>

<ResponseField name="allProperties" type="array">
  Liste aller gefundenen Property-Pfade mit Typ-Information
</ResponseField>

<ResponseField name="exampleEvents" type="array">
  Beispiel-Events für jeden Event-Namen
</ResponseField>

***

## Fehler-Codes

| HTTP Status | Beschreibung                                        |
| ----------- | --------------------------------------------------- |
| 202         | Events akzeptiert (kann teilweise Fehler enthalten) |
| 400         | Ungültige Anfrage - Validierungsfehler              |
| 401         | Nicht autorisiert - Ungültiger API-Token            |
| 404         | Event nicht gefunden                                |
| 429         | Rate Limit überschritten                            |

***

## Verwandte Dokumentation

* [Nutzungsmetriken konfigurieren](/guide/catalogue/measurements/billable-metrics)
* [Nutzungsereignisse senden (Guide)](/guide/catalogue/usage-events-import)
* [Collect Usage Data](/api-reference/guides/collect-usage-data)


# Complete the user registration
Source: https://docs.fynn.eu/api-reference/user/complete-the-user-registration

post /user/complete
Complete the user registration

<sup>Required permissions: `user:write`</sup>



# Get all login activities
Source: https://docs.fynn.eu/api-reference/user/get-all-login-activities

get /user/login-activities
Get all login activities.

<sup>Required permissions: `user:read`</sup>



# Get the current user
Source: https://docs.fynn.eu/api-reference/user/get-the-current-user

get /user/me
Get the current user

<sup>Required permissions: `user:read`</sup>



# Get the current user's accounts
Source: https://docs.fynn.eu/api-reference/user/get-the-current-users-accounts

get /user/accounts
Retrieves the collection of Account resources.



# Register a new user
Source: https://docs.fynn.eu/api-reference/user/register-a-new-user

post /auth/register
Register a new user



# Set the default tenant of the current user
Source: https://docs.fynn.eu/api-reference/user/set-the-default-tenant-of-the-current-user

post /user/default-tenant
Set the default tenant of the current user

<sup>Required permissions: `user:write`</sup>



# Create api token
Source: https://docs.fynn.eu/api-reference/userapitoken/create-api-token

post /user/api-tokens
Create a new api token for this user. This token can be used to authenticate against the API. The token has the same privileges as the current user account, assigned to tenant.

<sup>Required permissions: `user:api-token:write`</sup>



# Delete api token
Source: https://docs.fynn.eu/api-reference/userapitoken/delete-api-token

delete /user/api-tokens/{id}
Delete an api token

<sup>Required permissions: `user:api-token:write`</sup>



# Get all api tokens
Source: https://docs.fynn.eu/api-reference/userapitoken/get-all-api-tokens

get /user/api-tokens
Get all api tokens

<sup>Required permissions: `user:api-token:read`</sup>



# DATEV
Source: https://docs.fynn.eu/integrations/accounting/datev

Lerne, wie du Fynn mit DATEV verbindest, um Rechnungen, Stornos, Buchungssätze und Debitoren zu exportieren.

Die DATEV Integration erleichtert die Synchronisation von Rechnungen, Stornos, Gutschriften, Buchungssätzen und Debitoren zwischen Fynn und DATEV Kanzlei-Rechnungswesen.

## Funktionsumfang

* Export von Rechnungen und Stornos als DATEV Belegtransfer-Datei
* Export von Buchungssätzen inkl. PRAP als DATEV Buchungsstapel-Datei
* Export von Debitoren als Debitoren Stamm-Datei

## DATEV Integration einrichten

Um die DATEV Integration in Fynn einzurichten, benötigst du folgende Informationen:

* DATEV Beraternummer
* DATEV Mandantennummer
* SKR-Kontenrahmen

Die DATEV Beraternummer und Mandantennummer erhältst du von deinem Steuerberater. Der SKR-Kontenrahmen ist der Standardkontenrahmen, den du in DATEV verwendest.

## DATEV Integration konfigurieren

<Steps>
  <Step title="Beraternummer und Mandantennummer eingeben">
    Navigiere in Fynn zu "Einstellungen" > "Buchhaltung" > ["DATEV Grundeinstellungen"](https://app.fynn.eu/settings/accounting/cost-centres) und trage die Beraternummer, Mandantennummer und Sachkontenlänge aus DATEV ein.

    <Tip>
      Die Beraternummer und Mandantennummer findest du in DATEV. Alternativ kannst du auch fiktive Werte eingeben.
    </Tip>

    <Frame>
      <img alt="DATEV Grundeinstellungen" />
    </Frame>
  </Step>

  <Step title="SKR-Kontenrahmen auswählen">
    Wähle im Bereich "Buchungen" den SKR-Kontenrahmen aus, den du in DATEV verwendest und konfiguriere grundlegende Einstellungen zu den Buchungssätzen.
    Weitere Details zu den Einstellungen findest du unter [Buchhaltung](/guide/accounting/introduction).

    <Frame>
      <img alt="SKR-Kontenrahmen auswählen" />
    </Frame>
  </Step>

  <Step title="Feldzuweisungen konfigurieren (optional)">
    Konfiguriere optional die individuellen Felder eines DATEV-Stammdaten & Buchungsstapels. Hier kannst du die Felder aus Fynn den Feldern in DATEV zuweisen.

    <Tip>
      Sollten dir Felder fehlen, oder diese im falschem Format vorliegen, kontaktiere uns, um eine Lösung zu finden.
    </Tip>

    <Frame>
      <img alt="Feldzuweisungen konfigurieren" />
    </Frame>
  </Step>
</Steps>

### Buchungsschlüssel

Bei Verwendung von DATEV ist es je nach DATEV-Einstellung notwendig, Buchungsschlüssel zu hinterlegen.

Diese Buchungsschlüssel werden bei der Erstellung von Buchungen automatisch verwendet.

Um ein Buchungsschlüssel für ein Konto zu hinterlegen, siehe [Buchungsschlüssel](/guide/accounting/introduction#buchungsschluessel).

## DATEV Export durchführen

Weitere Details um Rechnungen, Stornos, Buchungssätze und Debitoren zu exportieren, findest du unter: [Buchungen exportieren](/guide/accounting/introduction).


# DATEVconnect online
Source: https://docs.fynn.eu/integrations/accounting/datev-online

DATEVconnect online erlaubt eine vereinfachte Synchronisation von Rechnungen, Stornos, Gutschriften, Buchungssätzen und Debitoren zwischen Fynn und DATEV Kanzlei-Rechnungswesen.

<Frame>
  <img />
</Frame>

<Card title="Premium Addon" icon="sparkles">
  Diese Integration ist ab dem Pro Plan verfügbar. Um die Integration zu nutzen, kontaktiere bitte <a href="mailto:hi@fynn.eu">[hi@fynn.eu](mailto:hi@fynn.eu)</a>
</Card>

<Warning>
  Wichtig: Unter Einstellungen > Buchhaltung / Accounting sind die Werte zu setzen, bevor der DATEVconnect online Export gestartet wird:

  * Debitor Buchungskonten
  * Buchung je Rechnungsposition
  * Wirtschaftsjahresbeginn
  * SKR Kontenrahmen

  Diese Einstellungen sind für den DATEV Buchungsdatenservice relevant. Sind hier falsche Werte eingetragen, wird der Export fehlschlagen. Für genaue Informationen, wende dich bitte an deinen Steuerberater.
</Warning>

## DATEVconnect online einrichten und verbinden

Um die DATEVconnect online Integration in Fynn einzurichten, benötigst du folgende Informationen:

* DATEV Beraternummer
* DATEV Mandantennummer
* SKR-Kontenrahmen
* DATEVconnect online Zugangsdaten (Benutzername und Passwort)
* [DATEV Buchungsdatenservice](https://www.datev.de/web/de/datev-shop/91000-buchungsdatenservice/) muss vorab über DATEV gebucht werden

Die DATEV Beraternummer und Mandantennummer erhältst du von deinem Steuerberater. Der SKR-Kontenrahmen ist der Standardkontenrahmen, den du in DATEV verwendest.

<Frame>
  <img alt="DATEVconnect online einrichten" />
</Frame>

<Steps>
  <Step title="DATEV Beraternummer und DATEV Mandantennummer eingeben">
    Navigiere in Fynn auf der linken Seite im Menü unter Buchhaltung > DATEV.
  </Step>

  <Step title="Klicke auf DATEV Verbindung herstellen">
    <Note>
      Im nächsten Schritt wirst du aufgefordert, deine DATEV Unternehmen online Zugangsdaten einzugeben. Nach Abschluss der Verbindung wirst du wieder auf Fynn weitergeleitet.
    </Note>
  </Step>

  <Step title="Verbindung erfolgreich hergestellt">
    Du kannst jetzt sehen, ob die Verbindung zu DATEV erfolgreich hergestellt wurde.

    <Frame>
      <img alt="DATEVconnect online Verbindung hergestellt" />
    </Frame>
  </Step>
</Steps>

## DATEVconnect online Daten übertragen

<Warning>
  Wichtig: Über Buchungsdatenservice exportierte Belege dessen Buchungen werden beim Export festgeschrieben.

  Wichtig: Bereits festgeschriebene Belege werden nicht erneut exportiert. D.h. wird ein manueller Datev Export als Zip gestartet, und dort festgeschrieben, sind die für Buchungsdatenservice nicht mehr verfügbar.

  Wichtig: Es werden auch nicht bezahlte Rechnungen übertragen.
</Warning>

<Steps>
  <Step title="Navigiere in Fynn auf der linken Seite im Menü unter Buchhaltung > DATEV." />

  <Step title="Klicke auf Export starten">
    In diesem Schritt kann das Jahr und der aktuelle Monat ausgewählt werden, für den die Daten exportiert werden sollen.

    <Frame>
      <img alt="DATEVconnect online Export starten" />
    </Frame>

    Mit dem Klick auf "Jetzt übertragen" wird der Export gestartet. Dieser kann einige Minuten dauern, je nach Anzahl der zu übertragenden Belege.
  </Step>

  <Step title="Export abgeschlossen">
    Nach Abschluss des Exports wird eine Zusammenfassung der übertragenen Daten angezeigt. Hier kannst du die Anzahl der übertragenen Rechnungen, Stornos, Gutschriften, Buchungssätze und Debitoren sehen.

    <Frame>
      <img alt="DAETV Export abgeschlossen" />
    </Frame>
  </Step>
</Steps>

## Troubleshooting

### Header Version

Die Header Version ist in Fynn festgelegt und kann nicht geändert werden. Die aktuell verwendete Header Version ist 712.


# n8n
Source: https://docs.fynn.eu/integrations/automation/n8n

Lerne, wie du Fynn mit n8n verbindest, um deine Workflows zu automatisieren und verschiedene Services zu integrieren.

<Frame>
  <img />
</Frame>

n8n ist eine Open-Source-Workflow-Automatisierungsplattform, die es dir ermöglicht, verschiedene Services und APIs miteinander zu verbinden.

## Vorteile

* **Workflow-Automatisierung**: Erstelle komplexe Workflows, die verschiedene Services miteinander verbinden und automatisieren, um manuelle Aufgaben zu reduzieren und Effizienz zu steigern.

* **Flexible Integrationen**: Nutze die Fynn API über n8n, um Fynn mit Hunderten von anderen Tools und Services zu verbinden, darunter CRM-Systeme, E-Mail-Marketing-Tools, Projektmanagement-Software und mehr.

* **Echtzeit-Synchronisation**: Automatisiere die Synchronisation von Daten zwischen Fynn und anderen Systemen in Echtzeit, um sicherzustellen, dass alle Systeme immer auf dem neuesten Stand sind.

* **Open Source**: n8n ist Open Source und kann selbst gehostet werden, was dir volle Kontrolle über deine Daten und Workflows gibt.

* **Benutzerfreundliche Oberfläche**: n8n bietet eine visuelle, benutzerfreundliche Oberfläche, die es auch Nicht-Entwicklern ermöglicht, komplexe Automatisierungen zu erstellen.

* **Dedizierter Fynn Node**: Nutze den offiziellen Fynn Community-Node für eine einfache und nahtlose Integration.

## n8n mit Fynn verbinden

Wir bieten einen speziellen Community-Node für n8n, der die Integration mit Fynn erheblich vereinfacht: `@fynnplatform/n8n-nodes-fynn`

<Steps>
  <Step title="n8n Account erstellen oder anmelden">
    Erstelle ein n8n-Konto auf [n8n.io](https://n8n.io) oder melde dich mit deinem bestehenden Account an. Du kannst n8n auch selbst hosten, wenn du die Open-Source-Version verwendest.
  </Step>

  <Step title="Fynn Community-Node installieren">
    Installiere den Fynn Community-Node in n8n:

    * Öffne die n8n-Einstellungen
    * Navigiere zu "Community Nodes"
    * Klicke auf "Install a community node"
    * Gib folgenden Namen ein: `@fynnplatform/n8n-nodes-fynn`
    * Klicke auf "Install"

    <Info>
      Alternativ kannst du den Node auch über die Kommandozeile installieren, wenn du n8n selbst hostest:
      `npm install @fynnplatform/n8n-nodes-fynn`
    </Info>
  </Step>

  <Step title="Neuen Workflow erstellen">
    Erstelle einen neuen Workflow in n8n, indem du auf "New Workflow" klickst.
  </Step>

  <Step title="Fynn Node hinzufügen">
    Füge den "Fynn" Node zu deinem Workflow hinzu. Du findest ihn unter "Community Nodes" > "Fynn" in der Node-Liste.
  </Step>

  <Step title="Fynn Credentials konfigurieren">
    Konfiguriere die Fynn-Verbindung:

    * Klicke auf "Credential to connect with" und wähle "Create New Credential"
    * Gib einen Namen für die Credentials ein (z.B. "Fynn Production")
    * Füge deinen API Schlüssel ein

    <Info>
      Deinen API Schlüssel findest du in Fynn unter "Einstellungen" > "API Schlüssel". Erstelle einen neuen API Schlüssel, falls du noch keinen hast. Weitere Informationen findest du unter [API Schlüssel erstellen](#api-schlüssel-erstellen).
    </Info>
  </Step>

  <Step title="Node konfigurieren">
    Wähle die gewünschte Operation aus (z.B. "Get Customer", "Create Invoice", etc.) und konfiguriere die entsprechenden Parameter.
  </Step>

  <Step title="Workflow testen und aktivieren">
    Teste deinen Workflow, indem du ihn manuell ausführst. Sobald alles funktioniert, kannst du den Workflow aktivieren, damit er automatisch ausgeführt wird.
  </Step>
</Steps>

## Alternative: HTTP Request Node verwenden

Falls du den Community-Node nicht verwenden möchtest oder erweiterte Anpassungen benötigst, kannst du auch den Standard "HTTP Request" Node verwenden:

<Steps>
  <Step title="HTTP Request Node hinzufügen">
    Füge einen "HTTP Request" Node zu deinem Workflow hinzu. Dieser Node ermöglicht es dir, API-Anfragen an Fynn zu senden.

    <Tip>
      Du kannst auch den "Webhook" Node verwenden, um Webhooks von Fynn zu empfangen und darauf zu reagieren.
    </Tip>
  </Step>

  <Step title="Fynn API konfigurieren">
    Konfiguriere den HTTP Request Node mit folgenden Informationen:

    * **Method**: Wähle die entsprechende HTTP-Methode (GET, POST, PUT, DELETE) basierend auf der gewünschten Aktion
    * **URL**: Verwende die Fynn API-URL: `https://coreapi.io/v1/[endpoint]`
    * **Authentication**: Wähle "Generic Credential Type" und füge deinen API Schlüssel als Header hinzu:
      * **Name**: `Authorization`
      * **Value**: `Bearer [DEIN_API_SCHLÜSSEL]`

    <Info>
      Deinen API Schlüssel findest du in Fynn unter "Einstellungen" > "API Schlüssel". Erstelle einen neuen API Schlüssel, falls du noch keinen hast. Weitere Informationen findest du unter [API Schlüssel erstellen](#api-schlüssel-erstellen).
    </Info>
  </Step>
</Steps>

## Beispiel-Workflows mit n8n

* **Neue Rechnung erstellen**: Automatisiere die Erstellung von Rechnungen basierend auf bestimmten Ereignissen oder Daten aus anderen Systemen.
* **Kundensynchronisation**: Synchronisiere Kundendaten zwischen Fynn und anderen Systemen wie CRM oder E-Mail-Marketing-Tools.
* **Webhook-Verarbeitung**: Empfange Webhooks von Fynn und verarbeite sie, um Aktionen in anderen Systemen auszulösen.
* **Berichte und Analysen**: Erstelle automatische Berichte, indem du Daten aus Fynn abrufst und sie in anderen Tools wie Google Sheets oder Notion speicherst.

## API Schlüssel erstellen

Um n8n mit Fynn zu verbinden, benötigst du einen API Schlüssel. So erstellst du einen:

<Steps>
  <Step title="Einstellungen öffnen">
    Navigiere in Fynn zu ["Einstellungen" > "API Schlüssel"](https://app.fynn.eu/settings/api-tokens).
  </Step>

  <Step title="Neuen API Schlüssel erstellen">
    Klicke auf "+ API Schlüssel anlegen" und gib einen Namen für den API Schlüssel ein (z.B. "n8n Integration").
  </Step>

  <Step title="API Schlüssel kopieren">
    Nach der Erstellung wird der API Schlüssel einmalig angezeigt. Kopiere ihn sofort und speichere ihn sicher, da er später nicht mehr angezeigt werden kann.

    <Warning>
      Bewahre deinen API Schlüssel sicher auf und teile ihn nicht mit anderen. Der API Schlüssel gewährt Zugriff auf deine Fynn-Daten.
    </Warning>
  </Step>
</Steps>

## Webhooks verwenden

Fynn unterstützt Webhooks, die es dir ermöglichen, in Echtzeit über Ereignisse in Fynn informiert zu werden. Du kannst Webhooks in n8n verwenden, um auf diese Ereignisse zu reagieren.

Weitere Informationen zu Webhooks findest du in der [Webhook-Dokumentation](/guide/webhooks/introduction).

## API-Referenz

Für detaillierte Informationen über die Fynn API, einschließlich verfügbarer Endpoints, Request- und Response-Formate, siehe die [API-Referenz](/api-reference).


# Attio
Source: https://docs.fynn.eu/integrations/crm/attio

Verbinde Fynn mit Attio: Abrechnungs-Widget direkt an der Company, Aktionen aus dem CRM und Kunden-Sync in beide Richtungen.

Die Attio-Integration zeigt deine Fynn-Abrechnung direkt an der Company in Attio, lässt dich typische Aktionen ohne Wechsel ins Billing anstoßen und hält Fynn-Kunden und Attio-Companies automatisch synchron.

<Info>
  Die Oberfläche der Fynn-App in Attio ist englisch. Aktionen und Widget heißen deshalb zum Beispiel **Link Fynn customer** oder **Fynn Billing**. Die Fynn-App selbst bedienst du weiterhin auf Deutsch.
</Info>

## Was die Integration kann

<CardGroup>
  <Card title="Abrechnungs-Widget an der Company" icon="table-columns">
    Das Widget **Fynn Billing** zeigt an jeder Company das Abonnement, die letzten Rechnungen (inklusive Ratenplan), Zahlungen und Angebote deines Fynn-Kunden.
  </Card>

  <Card title="Aktionen aus Attio" icon="bolt">
    Aus dem Company-Datensatz heraus verknüpfst du den Fynn-Kunden, erstellst ein Angebot, sendest eine Rechnung erneut, verschickst einen Zahlungslink oder kündigst ein Abo, jeweils mit Bestätigung vor der Kündigung.
  </Card>

  <Card title="Kunden-Sync" icon="arrows-rotate">
    Neue Companies in Attio können automatisch als Fynn-Kunden angelegt werden. Änderungen am Firmennamen werden bei aktiviertem bidirektionalen Sync in beide Richtungen übertragen.
  </Card>

  <Card title="Automatische Verknüpfung" icon="id-badge">
    Fynn schreibt die Kunden-ID (`fynn_customer_id`) und einen Billing-Link (`fynn_billing_url`) auf die Attio-Company. So bleibt die Verbindung zwischen CRM und Billing eindeutig und dauerhaft.
  </Card>
</CardGroup>

## Attio verbinden

<Steps>
  <Step title="Integrationsseite öffnen">
    Öffne in der Fynn-App die Einstellungen und navigiere zu **Integrationen**. Wähle dort Attio aus.
  </Step>

  <Step title="OAuth-Verbindung herstellen">
    Klicke auf **Mit Attio verbinden**. Du wirst zu Attio weitergeleitet, um Fynn Zugriff auf deinen Workspace zu erteilen. Nach der Bestätigung kehrst du automatisch zu Fynn zurück.
  </Step>

  <Step title="Integration einrichten">
    Nach dem Verbinden richtet Fynn die benötigten Attribute (`fynn_customer_id` und `fynn_billing_url`) auf dem Companies-Objekt ein und registriert den Webhook für Echtzeit-Sync. Das läuft automatisch im Hintergrund.
  </Step>

  <Step title="Fertig">
    Ab sofort werden Änderungen an Attio-Companies direkt nach Fynn übertragen, und verknüpfte Companies tragen den Billing-Link.
  </Step>
</Steps>

<Warning>
  Der Attio-Nutzer, der die Verbindung herstellt, braucht im Workspace die Rechte, Attribute anzulegen und Webhooks zu registrieren. Der Zugriff der Integration umfasst Records, Object configuration, Webhooks und Notes (für die Aktivitätsnotizen).
</Warning>

## Widget und Aktionen einrichten

Das Abrechnungs-Widget und die Aktionen laufen als Fynn-App direkt in Attio. Damit sich die App gegenüber Fynn authentifizieren kann, hinterlegst du das Integration-Secret einmalig als Workspace-Verbindung.

<Steps>
  <Step title="Integration-Secret in Fynn kopieren">
    Öffne in Fynn die Attio-Integrationsseite. Sobald die Integration eingerichtet ist, findest du dort das Integration-Secret. Klicke auf **Kopieren**.
  </Step>

  <Step title="Als Workspace-Verbindung hinterlegen">
    Öffne in Attio **Apps**, wähle **Fynn Billing** und klicke auf **Connect**. Füge das Integration-Secret ein und bestätige.
  </Step>

  <Step title="Widget an der Company hinzufügen">
    Öffne eine Company in Attio, wähle in der Seitenkonfiguration **Add widget** und füge das Widget **Fynn Billing** hinzu. Die Aktionen stehen anschließend im Aktionsmenü der Company bereit.
  </Step>
</Steps>

<Note>
  Behandle das Integration-Secret wie ein Passwort. Es bleibt bei einer erneuten Einrichtung unverändert, sodass du es nicht erneut in Attio eintragen musst.
</Note>

<Info>
  Auf der Einstellungsseite der Fynn-App in Attio gibt es nur noch das optionale Feld **API base URL** unter **Advanced**. Lass es leer, dann nutzt die App die Fynn-Produktionsumgebung. Ändere es nur für Staging oder Tests.
</Info>

## Kunden verknüpfen oder anlegen

Bevor Widget und Aktionen Daten anzeigen können, muss die Company mit einem Fynn-Kunden verknüpft sein. Dafür gibt es an jeder Company die Aktion **Link Fynn customer**.

<Steps>
  <Step title="Aktion öffnen">
    Öffne eine Company und wähle **Link Fynn customer**.
  </Step>

  <Step title="Bestehenden Kunden verknüpfen">
    Suche nach dem Fynn-Kunden über Name oder E-Mail-Adresse, wähle ihn aus und bestätige mit **Link**. Bei einer bereits verknüpften Company kannst du die Verknüpfung mit **Relink** auf einen anderen Kunden umstellen.
  </Step>

  <Step title="Oder neuen Kunden anlegen">
    Gibt es den Kunden in Fynn noch nicht, wähle **Create new customer**. Das Formular ist mit den Daten der Company vorbefüllt (Company name, Email, Street, Postcode, City, Country). Mit **Create customer** legt Fynn den Kunden an und verknüpft ihn direkt.
  </Step>
</Steps>

<Note>
  Ohne verknüpften Fynn-Kunden zeigen das Widget und die übrigen Aktionen einen Hinweis, die Verknüpfung zuerst herzustellen.
</Note>

## Angebote direkt in Attio erstellen

An jeder Company findest du die Aktion **Create quote (CPQ)**. Damit baust du ein vollständiges Angebot für den verknüpften Fynn-Kunden, ohne Attio zu verlassen. Der Builder unterstützt alle wesentlichen Angebots-Bausteine direkt im Attio-Dialog.

<Steps>
  <Step title="Aktion öffnen">
    Öffne eine Company und wähle **Create quote (CPQ)**. Hat der Kunde bereits offene Angebotsentwürfe, wählst du zuerst, ob du ein neues Angebot startest (**Create new quote**) oder einen bestehenden Entwurf bearbeitest (**Edit**).
  </Step>

  <Step title="Ablaufdatum setzen">
    Lege optional ein Ablaufdatum für das Angebot fest. Ohne Datum bleibt das Angebot zeitlich offen.
  </Step>

  <Step title="Käufer-Adresse eintragen">
    Trage die Rechnungsadresse des Käufers ein. Die Felder werden auf korrekte Eingaben geprüft, zum Beispiel E-Mail-Format und Ländercode, damit das Angebot keine ungültigen Adressdaten enthält.
  </Step>

  <Step title="Positionen hinzufügen">
    Wähle Produkte aus deinem Katalog, setze die Mengen und füge Positionen hinzu oder entferne sie wieder. Die laufende Summe aktualisiert sich dabei live.
  </Step>

  <Step title="Textblöcke einfügen">
    Ergänze das Angebot um Überschriften und Absätze. Du kannst Blöcke hinzufügen, bearbeiten, entfernen und in der Reihenfolge verschieben.
  </Step>

  <Step title="Im Fynn-Editor verfeinern">
    Für erweiterte Preisgestaltung wie Phasen, Rabatte und Konditionen, oder um Bilder und Dateien hinzuzufügen, öffnest du das Angebot über **Open in the Fynn editor**. Bilder und Dateianhänge lassen sich nur dort ergänzen, da Attio keinen Datei-Upload unterstützt.
  </Step>
</Steps>

Daneben gibt es die Aktion **Create quote in Fynn**: Sie öffnet direkt den Fynn-Angebotseditor mit vorausgewähltem Kunden, wenn du das Angebot lieber komplett in Fynn erstellst.

<Info>
  Für die Angebotserstellung ist keine zusätzliche Einrichtung nötig. Sie nutzt dieselbe Workspace-Verbindung, die du bereits hinterlegt hast.
</Info>

<Note>
  Angenommene oder archivierte Angebote sind gesperrt und können im Builder nicht bearbeitet werden. Öffne stattdessen den Fynn-Editor direkt.
</Note>

## Weitere Aktionen an der Company

<AccordionGroup>
  <Accordion title="Resend invoice">
    Zeigt die Rechnungen des Kunden als Liste mit Nummer, Datum, Betrag und Status. Jede Zeile trägt den Link **Open in Fynn** und einen **Send**-Button, der die Rechnung erneut an den Kunden sendet.
  </Accordion>

  <Accordion title="Send payment link">
    Sendet dem Kunden einen Link, über den er seine Zahlungsmethode hinterlegen oder aktualisieren kann.
  </Accordion>

  <Accordion title="Cancel subscription">
    Listet die Abonnements des Kunden mit Status. Nur aktive Abos lassen sich kündigen, jeweils nach einem Bestätigungsdialog. Die Kündigung erfolgt zum nächstmöglichen Termin.
  </Accordion>
</AccordionGroup>

<Info>
  Nach jeder erfolgreichen Aktion legt Fynn eine Aktivitätsnotiz auf der Timeline der Company an, zum Beispiel "Payment link sent" oder "Invoice resent". So bleibt im CRM nachvollziehbar, was aus Attio heraus ausgelöst wurde.
</Info>

## Abrechnungsfortschritt in Attio

Das Abrechnungs-Widget an der Company zeigt neben Abonnements, Rechnungen und Zahlungen auch den Abrechnungsfortschritt deines Kunden: wie viel bereits fakturiert wurde und, bei Verträgen mit einem festen Gesamtvolumen, wie viel davon noch offen ist.

Bei unbefristeten Abonnements ohne festes Vertragsvolumen wird nur der bereits fakturierte Betrag angezeigt. Es gibt kein sinnvolles Soll, das sich ausweisen ließe.

<Info>
  Der Abrechnungsfortschritt ist automatisch verfügbar, sobald für den Kunden Rechnungen in Fynn vorhanden sind. Keine zusätzliche Einrichtung erforderlich.
</Info>

## Konfiguration

Auf der Einstellungsseite der Attio-Integration stehen dir folgende Optionen zur Verfügung:

<AccordionGroup>
  <Accordion title="Kunden aus Attio anlegen">
    Wenn diese Option aktiv ist, legt Fynn automatisch einen neuen Kunden an, sobald eine Company in Attio angelegt oder aktualisiert wird und noch kein Fynn-Kunde verknüpft ist.
  </Accordion>

  <Accordion title="Bidirektionaler Sync">
    Ist diese Option aktiv, überträgt Fynn Änderungen am Kundennamen auch zurück nach Attio. Ohne diese Option fließen Änderungen nur von Attio nach Fynn.
  </Accordion>

  <Accordion title="Belege spiegeln">
    Ist diese Option aktiv, legt Fynn deine Abos, Rechnungen und Angebote als eigene Attio-Objekte an und verknüpft sie mit der Company. Die Option ist standardmäßig aus, weil sie zusätzliche Objekte und eine laufende Synchronisierung in Attio erzeugt. Die Objekte werden erst beim Aktivieren angelegt.
  </Accordion>
</AccordionGroup>

## Belege als Attio-Objekte spiegeln

Zusätzlich zum Live-Widget kann Fynn deine Abos, Rechnungen und Angebote als native Attio-Objekte anlegen und mit der Company verknüpfen. So kannst du in Attio direkt filtern, sortieren und in Listen arbeiten.

Die Spiegelung ist ein bewusster Schalter und standardmäßig aus, damit ohne dein Zutun keine zusätzlichen Objekte und keine laufende Synchronisierung in deinem Workspace entstehen. Erst wenn du **Belege spiegeln** in den Attio-Einstellungen aktivierst, legt Fynn die Objekte **Fynn Subscription**, **Fynn Invoice** und **Fynn Offer** an und hält sie aktuell.

<Note>
  Automatisch übertragen werden Belege ab dem Zeitpunkt der Aktivierung: neue Belege und Belege, die sich ändern. Bestehende Belege überträgst du bei Bedarf über **Bestandsbelege übertragen** auf der Einstellungsseite der Integration.
</Note>

### Spalten einmalig einblenden

Attios Listenansicht zeigt neu angelegte Objekte zunächst nur mit dem Namen. Öffne deshalb einmal pro Workspace in der jeweiligen Liste die Spaltenauswahl und blende die gewünschten Fynn-Attribute ein, zum Beispiel Status, Beträge oder Vertragsbeginn. Attio merkt sich die Ansicht für alle Mitglieder des Workspace.

<Note>
  Diesen Schritt kann Fynn nicht übernehmen, da sich Listenansichten in Attio nicht automatisch konfigurieren lassen.
</Note>

### Icons und Seitenleiste anpassen

Auch das Objekt-Icon, die Farbe und die Aufnahme in die linke Seitenleiste richtest du einmal pro Workspace von Hand ein, die Attio-API bietet dafür keine Schnittstelle. Öffne dazu das Objekt unter **Workspace Settings → Data → Objects** und wähle im Tab **Appearance** ein Icon und eine Farbe, zum Beispiel Grün mit Dollar-Symbol für Rechnungen, Orange für Angebote und Lila für Abos.

<Note>
  Schaltest du die Spiegelung wieder aus, stoppt die Übertragung. Die bereits in Attio angelegten Objekte bleiben erhalten und werden nicht automatisch entfernt.
</Note>

## Felder an Attio-Companies

Fynn ergänzt das Companies-Objekt in Attio um zwei Text-Attribute:

| Feld                                   | Bedeutung                                                   |
| -------------------------------------- | ----------------------------------------------------------- |
| `fynn_customer_id` (Fynn customer ID)  | Eindeutige Fynn-Kunden-ID, die die Verknüpfung sicherstellt |
| `fynn_billing_url` (Fynn billing link) | Direktlink zur Kundendetailseite in Fynn                    |

Die Felder werden beim ersten Einrichten der Integration automatisch angelegt, falls sie noch nicht existieren.

## Hinweise

<Note>
  Der Kunden-Sync überträgt aktuell den Firmennamen. Weitere Felder (Adresse, E-Mail, Ansprechpartner) werden nicht automatisch übertragen.
</Note>

<Info>
  Das Abrechnungs-Widget und die Aktionen lesen die Daten live aus Fynn. In Attio werden keine Rechnungen oder Zahlungen gespeichert, du siehst also immer den aktuellen Stand.
</Info>


# HubSpot
Source: https://docs.fynn.eu/integrations/crm/hubspot

Lerne, wie du Fynn mit HubSpot verbindest, um Angebote als Deals zu erstellen, Kontakte zu synchronisieren und Unternehmen & Deals für das Provisionsmodul zuzuordnen.

<Frame>
  <img />
</Frame>

Die HubSpot Integration ermöglicht eine nahtlose Verbindung zwischen Fynn und HubSpot, um Angebote aus Fynn als Deals in HubSpot zu erstellen und mit der Pipeline zu synchronisieren. Darüber hinaus werden die Kontakte synchronisiert, und Status-Informationen zu unterschriebenen Dokumenten und Ansichten werden in der Deal-Pipeline angezeigt. Außerdem kannst du in HubSpot direkt ein Angebot am Kontakt/Unternehmen anlegen. Erfahre mehr über die Funktionalitäten der HubSpot Integration und wie du sie in Fynn nutzen kannst:

## Vorteile

* **Erstellung von Deals aus Angeboten**: Mit der HubSpot Integration kannst du Angebote aus Fynn direkt als Deals in HubSpot erstellen und mit der Pipeline synchronisieren, um den Vertriebsprozess zu optimieren.

* **Synchronisation von Kontakten**: Die Integration synchronisiert Kontakte zwischen Fynn und HubSpot, um sicherzustellen, dass deine Kundendaten immer auf dem neuesten Stand sind.

* **Synchronisation von Status-Informationen**: Status-Informationen zu unterschriebenen Dokumenten und Ansichten werden als Timeline-Events synchronisiert, damit dein Team den Fortschritt der Kundeninteraktionen verfolgen kann.

* **Direkte Angebotserstellung in HubSpot**: Du kannst auch direkt in HubSpot ein Angebot am Kontakt/Unternehmen erstellen, um den Vertriebsprozess noch effizienter zu gestalten.

<Note>
  Diese Integration ist nur in Kombination mit dem Angebots-Addon verfügbar.
</Note>

## HubSpot verbinden

<Steps>
  <Step title="Einstellungen öffnen">
    Öffne die Einstellungen in Fynn unter "Einstellungen" und klicke auf ["CRM"](https://app.fynn.eu/settings/crm).
  </Step>

  <Step title="HubSpot verbinden">
    Klicke auf "HubSpot verbinden" und melde dich mit deinem HubSpot Account an. Du wirst nun
    zu HubSpot weitergeleitet, um Fynn die benötigten Berechtigungen zu erteilen.

    <Frame>
      <img alt="HubSpot verbinden" />
    </Frame>
  </Step>

  <Step title="Berechtigungen erteilen">
    Klicke auf "Genehmigen", um Fynn die benötigten Berechtigungen zu erteilen.

    Nachdem du die Berechtigungen erteilt hast, wirst du zurück zu Fynn geleitet und die Integration ist abgeschlossen.
  </Step>

  <Step title="Pipeline und Stages konfigurieren">
    Nachdem du die Berechtigungen erteilt hast, kannst du die Pipeline und Stages konfigurieren, die du mit HubSpot synchronisieren möchtest.

    <AccordionGroup>
      <Accordion title="Deal-Pipeline">
        Wähle die Pipeline aus, in der die Deals aus Fynn erstellt werden sollen.
      </Accordion>

      <Accordion title="Deal-Sent-Stage">
        Wird ein Angebot in Fynn an Empfänger versendet, wird der Deal in HubSpot in diese Stage versendet.
      </Accordion>

      <Accordion title="Deal-Closed-Won-Stage">
        Wird ein Angebot in Fynn von einem Empfänger unterschrieben, wird der Deal in HubSpot in diese Stage verschoben.
      </Accordion>

      <Accordion title="Deal-Closed-Lost-Stage">
        Wird ein Angebot in Fynn von einem Empfänger abgelehnt, oder storniert, wird der Deal in HubSpot in diese Stage verschoben.
      </Accordion>
    </AccordionGroup>

    <Frame>
      <img alt="Pipeline und Stages konfigurieren" />
    </Frame>
  </Step>

  <Step title="Einrichtung abgeschlossen 🎉">
    Die HubSpot Integration ist nun erfolgreich eingerichtet und du kannst Angebote aus Fynn direkt als Deals in HubSpot erstellen und mit der Pipeline synchronisieren.
  </Step>
</Steps>

## Angebote / Deals erstellen

Um Angebote aus Fynn als Deals in HubSpot zu erstellen, sehe dir dazu den [Angebote](/guide/offers/introduction) Bereich an.

## Abrechnungsfortschritt in HubSpot

In HubSpot siehst du an jedem Kontakt und Unternehmen eine Karte mit dem Abrechnungsfortschritt: wie viel für den Kunden bereits fakturiert wurde und, bei Verträgen mit einem festen Gesamtvolumen, wie viel noch offen ist.

Bei einzelnen Abonnements gibt es zusätzlich eine Fortschrittsanzeige direkt auf der Abonnement-Ebene.

Bei unbefristeten Abonnements ohne festes Vertragsvolumen wird nur der bereits fakturierte Betrag angezeigt. Es gibt kein sinnvolles Soll, das sich ausweisen ließe.

<Info>
  Die Karte erscheint automatisch in der Seitenleiste, sobald für den Kunden Rechnungen in Fynn vorhanden sind.
</Info>

***

## Unternehmen & Deal Synchronisation

Fynn synchronisiert HubSpot-Unternehmen und Deals in eine lokale Datenbank. Dies ermöglicht die Zuordnung von HubSpot-Unternehmen zu Fynn-Kunden und HubSpot-Deals zu Fynn-Abonnements — die Grundlage für das Provisionsmodul.

### Was wird synchronisiert?

<CardGroup>
  <Card title="Unternehmen" icon="building">
    * Name
    * Domain
    * Besitzer (Name + E-Mail)
  </Card>

  <Card title="Deals" icon="handshake">
    * Name
    * Deal-Stage
    * Pipeline
    * Betrag & Währung
    * Besitzer (Name + E-Mail)
    * Abschlussdatum
    * Positionen (Line Items)
  </Card>
</CardGroup>

### Wann wird synchronisiert?

<Steps>
  <Step title="Erstmalige Synchronisation">
    Die erste Synchronisation startest du manuell — entweder über den **Mapping-Wizard** oder über die **Einstellungen** mit dem Button "Jetzt synchronisieren". Dabei werden alle bestehenden Unternehmen und Deals aus HubSpot geladen.
  </Step>

  <Step title="Echtzeit-Updates">
    Nach der Ersteinrichtung werden Änderungen in HubSpot **automatisch in Echtzeit** übernommen. Das betrifft unter anderem:

    * Neue Unternehmen oder Deals
    * Namensänderungen
    * Stage-Wechsel bei Deals
    * Besitzer-Wechsel
  </Step>

  <Step title="Periodischer Abgleich">
    Als zusätzliches Sicherheitsnetz gleicht Fynn regelmäßig alle Daten mit HubSpot ab, um sicherzustellen, dass keine Änderungen verpasst werden.
  </Step>
</Steps>

### Mapping-Wizard

Mit dem Mapping-Wizard ordnest du deine HubSpot-Daten den entsprechenden Fynn-Objekten zu. Der Wizard führt dich in drei Schritten durch den Prozess:

<Steps>
  <Step title="Unternehmen zuordnen">
    HubSpot-Unternehmen werden Fynn-Kunden zugeordnet. Fynn schlägt dabei automatisch Zuordnungen vor — basierend auf E-Mail-Domain und Firmenname. Ein HubSpot-Unternehmen kann auch mehreren Fynn-Kunden zugeordnet werden.
  </Step>

  <Step title="Deals zuordnen">
    HubSpot-Deals werden Fynn-Abonnements zugeordnet. Du kannst Deals nach Stage filtern (z.B. nur "Closed Won"), um die Übersicht zu behalten. Mehrere Deals können demselben Abonnement zugeordnet werden.
  </Step>

  <Step title="Überprüfen & Anwenden">
    Alle Zuordnungen werden übersichtlich zusammengefasst. Nach deiner Bestätigung werden sie angewendet.
  </Step>
</Steps>

<Tip>
  Du kannst den Mapping-Wizard jederzeit erneut öffnen, um bestehende Zuordnungen anzupassen oder neue hinzuzufügen.
</Tip>

### Voraussetzungen

<Warning>
  Damit die Unternehmen & Deal Synchronisation genutzt werden kann, müssen folgende Voraussetzungen erfüllt sein:

  * **HubSpot muss verbunden sein** — Die Verbindung erfolgt per OAuth wie oben beschrieben.
  * **HubSpot-Berechtigungen** — Fynn benötigt Lesezugriff auf Unternehmen, Deals und Besitzer (Companies Read, Deals Read, Owners Read). Diese Berechtigungen werden bei der Verbindung automatisch angefordert.
</Warning>

### Häufige Fragen

<AccordionGroup>
  <Accordion title="Was passiert, wenn ich ein Unternehmen in HubSpot lösche?">
    Es wird automatisch aus der lokalen Datenbank entfernt. Bestehende Zuordnungen zu Fynn-Kunden bleiben erhalten und können im Mapping-Wizard angepasst werden.
  </Accordion>

  <Accordion title="Kann ich die Zuordnung nachträglich ändern?">
    Ja, du kannst den Mapping-Wizard jederzeit erneut öffnen und Zuordnungen anpassen, entfernen oder neue hinzufügen.
  </Accordion>

  <Accordion title="Werden meine HubSpot-Daten verändert?">
    Nein, die Synchronisation ist ausschließlich lesend. Fynn schreibt keine Daten zurück nach HubSpot.
  </Accordion>

  <Accordion title="Wie oft werden die Daten aktualisiert?">
    Änderungen in HubSpot werden in Echtzeit übernommen. Zusätzlich findet ein periodischer Abgleich statt, der als Sicherheitsnetz dient, um keine Änderungen zu verpassen.
  </Accordion>
</AccordionGroup>

***

## Fynn → HubSpot Feld-Synchronisation

Neben der Zuordnung von HubSpot-Feldern nach Fynn kannst du auch die umgekehrte Richtung einrichten: Fynn-Daten werden nach HubSpot geschrieben. Werte wie das nächste Abrechnungsdatum, der Vertragsstatus oder die Kundennummer bleiben in HubSpot damit aktuell.

Die Konfiguration findest du in den HubSpot-Einstellungen in der Karte "Fynn → HubSpot", direkt neben der bestehenden Feld-Zuordnung.

### Was kann synchronisiert werden?

Die Synchronisation ist in drei Bereiche unterteilt:

<CardGroup>
  <Card title="Kunden" icon="user">
    Firmenname, Kundennummer, USt-ID, Land, Status, E-Mail sowie deine eigenen Felder.
  </Card>

  <Card title="Abos" icon="repeat">
    Vertragsbeginn, Vertragsende, Kündigungsdatum, nächstes Abrechnungsdatum, Status, Abonummer, Laufzeit, Vertragswert sowie deine eigenen Felder.
  </Card>

  <Card title="Assets" icon="box">
    Hauptkennung, Status, Typ, Lieferdatum sowie weitere Attribute.
  </Card>
</CardGroup>

Für jedes Fynn-Feld legst du das Ziel in HubSpot fest: zuerst das HubSpot-Objekt, dann die HubSpot-Property. Die Properties werden aus deinem verbundenen HubSpot-Account geladen, auch deine eigenen. Welche Objekte pro Bereich möglich sind:

| Bereich | Mögliche HubSpot-Objekte   |
| ------- | -------------------------- |
| Kunden  | Unternehmen, Kontakt       |
| Abos    | Unternehmen, Kontakt, Deal |
| Assets  | Unternehmen, Kontakt       |

<Note>
  Damit ein Feld geschrieben werden kann, muss HubSpot verbunden und der Fynn-Datensatz mit einem HubSpot-Objekt verknüpft sein: Kunden mit einem HubSpot-Unternehmen über die bestehende Zuordnung, Abos mit einem verknüpften Deal.
</Note>

### Einrichten

<Steps>
  <Step title="Bereich wählen">
    Wechsle in der Karte "Fynn → HubSpot" zum Tab "Kunden", "Abos" oder "Assets".
  </Step>

  <Step title="HubSpot-Objekt wählen">
    Lege für ein Fynn-Feld fest, in welches HubSpot-Objekt es geschrieben wird.
  </Step>

  <Step title="HubSpot-Property wählen">
    Wähle die Ziel-Property in HubSpot. Verfügbar sind alle Properties des gewählten Objekts, auch deine eigenen.
  </Step>
</Steps>

<Note>
  Eine HubSpot-Property kann nur von einem einzigen Fynn-Feld befüllt werden. Ist ein Ziel bereits belegt, musst du die Zuordnung erst auflösen, bevor du speichern kannst.
</Note>

### Wann wird synchronisiert?

Die Synchronisation läuft automatisch. Sobald sich ein Wert in Fynn ändert, wird die Änderung in das verknüpfte HubSpot-Objekt geschrieben, in der Regel innerhalb einer Minute. Das gilt etwa, wenn ein Abo gekündigt wird, ein Abrechnungslauf das nächste Abrechnungsdatum weitersetzt oder du Kundendaten bearbeitest.

Änderungen werden gesammelt und gebündelt übertragen. So bleibt die Synchronisation auch bei mehreren tausend Datensätzen zuverlässig.


# Pipedrive
Source: https://docs.fynn.eu/integrations/crm/pipedrive

Verbinde Fynn mit Pipedrive: Billing-Übersicht direkt an Organisationen, Kunden-Sync in beide Richtungen und Angebote per Deep-Link.

Die Pipedrive-Integration zeigt dir Abrechnungsdaten direkt an jeder Organisation in Pipedrive, hält Kundendaten beidseitig aktuell und öffnet den Fynn-Angebotseditor mit vorausgewähltem Kunden per Klick.

## Was die Integration kann

<CardGroup>
  <Card title="Billing-Panel an Organisationen" icon="chart-bar">
    In der Organisations-Ansicht in Pipedrive siehst du den aktuellen Abonnementstatus, offene und bezahlte Rechnungen (inkl. Hinweis auf aktive Ratenpläne), letzte Zahlungen und aktuelle Angebote.
  </Card>

  <Card title="Schnellaktionen" icon="bolt">
    Direkt aus dem Panel heraus: Rechnung erneut senden, Link zur Zahlungsmethoden-Verwaltung verschicken oder ein Abonnement zum nächstmöglichen Termin kündigen.
  </Card>

  <Card title="Angebote erstellen und bearbeiten" icon="file-contract">
    Ein Klick im Panel öffnet den Fynn-Angebotseditor mit dem passenden Kunden bereits vorausgewählt. Bestehende Angebote öffnest du genauso direkt.
  </Card>

  <Card title="Kunden-Sync" icon="arrows-rotate">
    Fynn-Kunden und Pipedrive-Organisationen bleiben automatisch synchronisiert: Neue Organisationen in Pipedrive können direkt als Fynn-Kunden angelegt werden; Änderungen am Firmennamen werden in beide Richtungen übertragen.
  </Card>
</CardGroup>

## Pipedrive verbinden

<Steps>
  <Step title="Integrationsseite öffnen">
    Öffne in der Fynn-App die Einstellungen und navigiere zu **Integrationen**. Wähle dort Pipedrive aus.
  </Step>

  <Step title="OAuth-Verbindung herstellen">
    Klicke auf **Pipedrive verbinden**. Du wirst zu Pipedrive weitergeleitet, um Fynn die benötigten Berechtigungen zu erteilen. Nach der Bestätigung kehrt Pipedrive automatisch zu Fynn zurück.
  </Step>

  <Step title="Integration einrichten">
    Nach dem ersten Verbinden richtet Fynn automatisch die nötigen Felder und Webhooks in deinem Pipedrive-Konto ein. Das passiert im Hintergrund und dauert wenige Sekunden.
  </Step>

  <Step title="Fertig">
    Das Billing-Panel erscheint ab sofort in jeder Pipedrive-Organisation, der ein Fynn-Kunde zugeordnet ist.
  </Step>
</Steps>

## Konfiguration

Auf der Einstellungsseite der Pipedrive-Integration findest du zwei Sync-Optionen:

<AccordionGroup>
  <Accordion title="Kunden aus Pipedrive anlegen">
    Wenn diese Option aktiv ist, legt Fynn automatisch einen neuen Kunden an, sobald eine Organisation in Pipedrive erstellt oder geändert wird und noch kein Fynn-Kunden verknüpft ist. Ohne diese Option startet die Verknüpfung erst, wenn du einen Kunden manuell in Fynn anlegst und der Abgleich die passende Organisation findet.
  </Accordion>

  <Accordion title="Bidirektionaler Sync">
    Ist der bidirektionale Sync eingeschaltet, überträgt Fynn Änderungen am Kundennamen auch zurück nach Pipedrive. Ohne diese Option fließen Änderungen nur von Pipedrive nach Fynn.
  </Accordion>
</AccordionGroup>

## Angebote direkt in Pipedrive erstellen und bearbeiten

Angebote entstehen und wachsen direkt in Pipedrive, ohne die App zu wechseln. Ein Klick im Aktionsmenü einer Organisation öffnet den vollständigen Fynn-Angebotseditor in einem fokussierten Fenster, ganz ohne die linke Navigation. Du arbeitest also mit dem echten Editor, nur eingebettet.

<Steps>
  <Step title="Angebot anlegen">
    Öffne bei einer Organisation das Aktionsmenü und wähle die Fynn-Aktion zum Erstellen eines Angebots. Fynn legt sofort einen Entwurf für den verknüpften Kunden an und öffnet ihn direkt im Editor, ohne Zwischenschritt.
  </Step>

  <Step title="Angebot ausarbeiten">
    Im eingebetteten Editor ergänzt du Positionen, Preise, Laufzeiten und Texte wie gewohnt. Alle Änderungen werden automatisch gespeichert.
  </Step>

  <Step title="Bestehendes Angebot bearbeiten">
    Ein bestehendes Angebot öffnest du über die Angebots-Aktion erneut im Editor-Fenster. Du landest genau in dem Angebot und kannst weiterarbeiten.
  </Step>
</Steps>

<Note>
  Ist die Organisation noch mit keinem Fynn-Kunden verknüpft, führt dich ein Hinweis zuerst zur Konfiguration. Sobald die Verknüpfung steht, öffnet die Aktion den Editor direkt.
</Note>

## Billing-Panel

Das Panel in Pipedrive zeigt für jede verknüpfte Organisation:

| Bereich     | Inhalt                                                                       |
| ----------- | ---------------------------------------------------------------------------- |
| Abonnements | Aktive Pläne, Status, nächste Abrechnung                                     |
| Rechnungen  | Letzte Rechnungen mit Betrag, Status und Hinweis auf einen aktiven Ratenplan |
| Zahlungen   | Letzte eingegangene Zahlungen                                                |
| Angebote    | Aktuelle Angebote mit direktem Link zum Editor                               |

Über die Aktionsschaltflächen im Panel kannst du ohne Wechsel in die Fynn-App eine Rechnung erneut zustellen, einen Zahlungsmethoden-Link an den Kunden schicken oder ein Abonnement kündigen.

## Abrechnungsfortschritt in Pipedrive

Das Billing-Panel in Pipedrive zeigt dir auch den Abrechnungsfortschritt der verknüpften Organisation: wie viel bereits fakturiert wurde und, bei Verträgen mit einem festen Gesamtvolumen, wie viel noch offen ist.

Bei unbefristeten Abonnements ohne festes Vertragsvolumen wird nur der bereits fakturierte Betrag angezeigt. Es gibt kein sinnvolles Soll, das sich ausweisen ließe.

<Info>
  Der Abrechnungsfortschritt erscheint automatisch im Panel, sobald für den Kunden Rechnungen in Fynn vorhanden sind.
</Info>

## Hinweise

<Info>
  Für neue Organisationen ohne hinterlegte E-Mail-Adresse in Pipedrive wird in Fynn zunächst eine Platzhalter-E-Mail eingetragen. Die tatsächliche Rechnungs-E-Mail trägst du direkt im Kundenprofil in Fynn nach.
</Info>

<Note>
  Der Fynn-Kundenname und Pipedrive-Organisationsname werden beim bidirektionalen Sync abgeglichen. Weitere Felder (Ansprechpartner, E-Mail, Telefon) werden aktuell nicht übertragen.
</Note>

<Warning>
  Die Integration setzt ein aktives Pipedrive-Konto sowie die Berechtigung voraus, Organisations-Felder und Webhooks in Pipedrive zu erstellen. Stelle sicher, dass dein Pipedrive-Nutzer diese Rechte hat, bevor du die Verbindung herstellst.
</Warning>


# Salesforce
Source: https://docs.fynn.eu/integrations/crm/salesforce

Lerne, wie du Fynn mit Salesforce verbindest, um Daten zu übertragen.

<Frame>
  <img />
</Frame>

Die Salesforce Integration ermöglicht es, Fynn mit Salesforce zu verbinden, um Daten von Fynn in Salesforce zu übertragen. Dies ist besonders nützlich für Unternehmen, die ihre CRM-Daten in Salesforce verwalten und gleichzeitig Fynn für andere Geschäftsprozesse nutzen möchten.

<Card title="Premium Addon" icon="sparkles">
  Die Salesforce Integration ist nur für Fynn Enterprise verfügbar. Bei Interesse an der Integration kontaktiere bitte <a href="mailto:hi@fynn.eu">[hi@fynn.eu](mailto:hi@fynn.eu)</a>
</Card>


# Custom PDF Rendering
Source: https://docs.fynn.eu/integrations/custom-pdf-rendering

Nutze deine eigene PDF-Rendering-Engine für Rechnungen, Gutschriften und Stornos.

<Note>
  Diese Funktion ist nur im **Enterprise**-Plan verfügbar. Kontaktiere unser Sales-Team unter [sales@fynn.eu](mailto:sales@fynn.eu) für weitere Informationen.
</Note>

## Übersicht

Mit Custom PDF Rendering kannst du deine eigene PDF-Rendering-Engine verwenden, um Rechnungen, Gutschriften und Stornos nach deinen individuellen Anforderungen zu generieren. Dies ermöglicht:

* **Vollständige Design-Kontrolle**: Gestalte Belege exakt nach deinen Corporate-Design-Vorgaben
* **Eigene Template-Engines**: Nutze deine bevorzugte Template-Engine (LaTeX, Typst, etc.)
* **Komplexe Layouts**: Erstelle mehrseitige Dokumente mit komplexen Tabellen und Grafiken
* **Integration mit bestehenden Systemen**: Binde deine vorhandene Dokumentengenerierung nahtlos ein

## Funktionsweise

```mermaid theme={null}
sequenceDiagram
    participant F as Fynn
    participant W as Dein Webhook-Server
    participant P as Deine PDF-Engine

    F->>F: Beleg finalisieren
    F->>W: Webhook: invoice.pdf.generation_requested
    W->>P: PDF generieren
    P->>W: PDF-Datei
    W->>F: POST /api/invoices/{id}/pdf
    F->>F: Finalisierung abschließen
```

1. **Beleg wird finalisiert**: Wenn ein Beleg finalisiert wird, wechselt er in den Status `STATUS_FINALIZING`
2. **Webhook wird ausgelöst**: Fynn sendet den `invoice.pdf.generation_requested` Webhook mit allen Belegdaten
3. **PDF generieren**: Dein System generiert das PDF mit deiner eigenen Rendering-Engine
4. **PDF hochladen**: Das fertige PDF wird über die API an Fynn zurückgesendet
5. **Finalisierung abschließen**: Fynn schließt den Finalisierungsprozess ab (ZUGFeRD-Einbettung, Versand, etc.)

## Konfiguration

### 1. Feature aktivieren

Kontaktiere den Fynn-Support, um das Feature für deine Organisation freizuschalten.

### 2. Webhook registrieren

Registriere einen Webhook für das Event `invoice.pdf.generation_requested`:

<Tabs>
  <Tab title="Web-App verwenden">
    <Steps>
      <Step title="Webhooks öffnen">
        Navigiere zu **Einstellungen** > **Webhooks**
      </Step>

      <Step title="Neuen Webhook erstellen">
        Klicke auf **Neuer Webhook** und konfiguriere:

        * **URL**: Die URL deines Webhook-Endpoints
        * **Events**: Wähle `invoice.pdf.generation_requested`
        * **Secret**: Ein sicheres Secret zur Signaturvalidierung
      </Step>
    </Steps>
  </Tab>

  <Tab title="API verwenden">
    ```bash theme={null}
    POST /webhooks
    {
        "url": "https://your-server.com/webhooks/fynn",
        "events": ["invoice.pdf.generation_requested"],
        "version": "v1",
        "enabled": true
    }
    ```

    Das Webhook-Secret wird automatisch generiert und kann nach Erstellung in den Webhook-Details abgerufen werden.
  </Tab>
</Tabs>

### 3. Einstellungen konfigurieren

Unter **Einstellungen** > **Abrechnung** > **Benutzerdefiniertes PDF-Rendering** kannst du folgende Optionen konfigurieren:

<Frame>
  <img alt="Benutzerdefiniertes PDF-Rendering Einstellungen" />
</Frame>

| Einstellung                                      | Beschreibung                                                                                                                              | Standard    |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Benutzerdefiniertes PDF-Rendering aktivieren** | Wenn aktiviert, wird die PDF-Generierung von Belegen über einen Webhook an ein externes System delegiert.                                 | Deaktiviert |
| **ZUGFeRD-XML einbetten**                        | ZUGFeRD-XML-Daten automatisch in das hochgeladene PDF einbetten. Deaktiviere dies, wenn dein externer Renderer bereits ZUGFeRD einbettet. | Aktiviert   |
| **Automatischer Fallback**                       | Automatisch auf den integrierten Renderer zurückfallen, wenn das externe System das PDF nicht innerhalb des Timeout-Zeitraums liefert.    | Deaktiviert |
| **Timeout**                                      | Timeout in Minuten (1-1440)                                                                                                               | 30          |

## Webhook-Payload

Der `invoice.pdf.generation_requested` Webhook enthält alle Belegdaten:

```json theme={null}
{
    "event": {
        "id": "01JKXYZ1234567890ABCDEFGH",
        "type": "invoice.pdf.generation_requested",
        "version": "v1",
        "createdAt": "2026-02-09T10:00:00+00:00"
    },
    "data": {
        "invoice": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "number": "RE-2026-0001",
            "type": "TYPE_INVOICE",
            "status": "STATUS_FINALIZING",
            ...
        }
    }
}
```

## PDF hochladen

Nach der PDF-Generierung muss das Dokument über die API hochgeladen werden:

```bash theme={null}
curl -X POST "https://coreapi.io/api/invoices/{invoiceId}/pdf" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@invoice.pdf"
```

### Endpoint-Details

| Methode | Pfad                     | Beschreibung            |
| ------- | ------------------------ | ----------------------- |
| `POST`  | `/api/invoices/{id}/pdf` | PDF für Beleg hochladen |

### Request

* **Content-Type**: `multipart/form-data`
* **Feld**: `file` - Die PDF-Datei (MIME-Type: `application/pdf`)

### Response

**200 OK**

```json theme={null}
{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "STATUS_UNPAID",
    "message": "PDF uploaded and invoice finalization continued."
}
```

### Fehlercodes

| Code  | Beschreibung                                  |
| ----- | --------------------------------------------- |
| `404` | Beleg nicht gefunden                          |
| `409` | Beleg ist nicht im Status `STATUS_FINALIZING` |
| `422` | Ungültige Datei (kein PDF)                    |

## Timeout und Fallback

Wenn das Custom PDF Rendering aktiviert ist, wartet Fynn auf das Hochladen des PDFs. Falls das PDF nicht rechtzeitig hochgeladen wird:

* **Mit aktiviertem Fallback**: Nach Ablauf des Timeouts generiert Fynn das PDF automatisch mit der internen Rendering-Engine
* **Ohne Fallback**: Der Beleg bleibt im Status `STATUS_FINALIZING` bis das PDF manuell hochgeladen wird

<Warning>
  Stelle sicher, dass dein System das PDF innerhalb des konfigurierten Timeouts hochlädt, um Verzögerungen bei der Belegstellung zu vermeiden.
</Warning>

## ZUGFeRD-Einbettung

Wenn `embedZugferd` aktiviert ist, bettet Fynn automatisch die ZUGFeRD/Factur-X XML-Daten in das hochgeladene PDF ein. Dies gewährleistet die Compliance mit dem deutschen e-Rechnungsstandard.

<Tip>
  Du musst dich nicht um die ZUGFeRD-Generierung kümmern – Fynn übernimmt die Einbettung nach dem Upload automatisch.
</Tip>

## Best Practices

### Webhook-Verarbeitung

1. **Asynchrone Verarbeitung**: Bestätige den Webhook sofort (HTTP 200) und verarbeite die PDF-Generierung asynchron
2. **Idempotenz**: Implementiere Idempotenz, um doppelte Webhook-Aufrufe zu handhaben
3. **Retry-Logik**: Implementiere Retries für den PDF-Upload bei temporären Fehlern

### PDF-Anforderungen

* **Format**: PDF/A-3 wird empfohlen für beste ZUGFeRD-Kompatibilität
* **Größe**: Maximal 10 MB
* **Qualität**: Mindestens 150 DPI für eingebettete Bilder

### Sicherheit

* Validiere die Webhook-Signatur
* Nutze HTTPS für alle API-Aufrufe
* Speichere API-Tokens sicher

## Beispiel-Implementierung (Node.js)

```javascript theme={null}
const express = require('express');
const crypto = require('crypto');
const FormData = require('form-data');
const axios = require('axios');

const app = express();
app.use(express.json());

app.post('/webhooks/fynn', async (req, res) => {
    // 1. Webhook sofort bestätigen
    res.status(200).send('OK');

    // 2. Signatur validieren
    const signature = req.headers['x-fynn-signature'];
    const expectedSignature = crypto
        .createHmac('sha256', process.env.WEBHOOK_SECRET)
        .update(JSON.stringify(req.body))
        .digest('hex');

    if (signature !== expectedSignature) {
        console.error('Invalid webhook signature');
        return;
    }

    // 3. PDF generieren (deine eigene Logik)
    const { invoice } = req.body.data;
    const pdfBuffer = await generateInvoicePdf(invoice);

    // 4. PDF an Fynn hochladen
    const form = new FormData();
    form.append('file', pdfBuffer, {
        filename: `invoice-${invoice.number}.pdf`,
        contentType: 'application/pdf'
    });

    await axios.post(
        `https://coreapi.io/api/invoices/${invoice.id}/pdf`,
        form,
        {
            headers: {
                ...form.getHeaders(),
                'Authorization': `Bearer ${process.env.FYNN_API_TOKEN}`
            }
        }
    );
});

async function generateInvoicePdf(invoice) {
    // Implementiere hier deine PDF-Generierung
    // z.B. mit Puppeteer, PDFKit, LaTeX, etc.
}
```

## Troubleshooting

### PDF wird nicht akzeptiert

* Stelle sicher, dass die Datei ein gültiges PDF ist
* Überprüfe, dass der Beleg im Status `STATUS_FINALIZING` ist
* Validiere, dass du die richtige Invoice-ID verwendest

### Webhook wird nicht empfangen

* Überprüfe, dass der Webhook für `invoice.pdf.generation_requested` registriert ist
* Stelle sicher, dass dein Endpoint erreichbar ist
* Überprüfe die Webhook-Logs in den Fynn-Einstellungen

### Timeout-Fehler

* Erhöhe den `timeoutMinutes`-Wert
* Optimiere deine PDF-Generierung
* Aktiviere den Fallback für kritische Situationen

## API-Referenz

Weitere Details zur API findest du in der [API-Dokumentation](/api-reference/invoice/upload-invoice-pdf).


# Überweisung
Source: https://docs.fynn.eu/integrations/payment-providers/bank-transfer

Wir bieten dir eine Vielzahl von Integrationen zu 3rd-Party-Tools und -Services, um die Funktionalität der Fynn-Plattform zu erweitern.

Die Zahlungsmethode Überweisung ermöglicht es den Kunden, ihre Rechnungen manuell per Banküberweisung zu begleichen. Hier erfährst Du, wie Du die Zahlungsmethode Überweisung in Fynn verwenden kannst:

## Einrichtung

Die Zahlungsmethode Überweisung ist standardmäßig in Fynn verfügbar. Um Überweisungen zu akzeptieren, musst Du lediglich Deine Bankdaten in Deinem Fynn-Konto pflegen.

<Steps>
  <Step title="Öffne die Zahlungsmethoden-Einstellungen">
    Gehe hierzu zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods) und scrolle nach unten zu "Bankkonto".
  </Step>

  <Step title="Bankkonto hinterlegen">
    Füge die IBAN des Bankkontos hinzu, auf das Deine Kunden die Überweisung tätigen sollen.
    Dieses Bankkonto wird auf den Rechnungen Deiner Kunden angezeigt.

    <Frame>
      <img alt="Bankkonto hinterlegen" />
    </Frame>

    Die IBAN wird automatisch validiert.
  </Step>

  <Step title="Bankkonto speichern">
    Klicke auf "Speichern", um die Änderungen zu übernehmen.
  </Step>
</Steps>

<Note>
  Möchtest du mehrere Bankkonten hinterlegen, und diese auf unterschiedlichen Rechnungen / Abonnements verwenden wollen,
  kontaktiere uns bitte und wir helfen dir gerne weiter: [Kontakt aufnehmen](mailto:hi@fynn.eu)
</Note>

## Zahlungsstatus aktualisieren

Nachdem Du Deine Bankdaten hinterlegt hast, kannst Du den Zahlungsstatus einer Rechnung manuell pflegen.
Alternativ bietet Fynn einen Bank-Konto Sync an, der zweimal täglich Kontobewegungen von Deinem Bankkonto abruft.
Basierend auf verschiedenen Parametern wird ermittelt, ob eine Kontobewegung einer Rechnung zugewiesen werden kann.
Sollte keine automatische Zuweisung erfolgen, müssen diese Kontobewegungen manuell verknüpft werden.

### Vorteile des Bank-Konto Syncs

* **Automatische Zuweisung**: Der Bank-Konto Sync ermöglicht eine automatische Zuweisung von BankKontobewegungen zu offenen Rechnungen, was den manuellen Aufwand reduziert und die Zahlungsabwicklung beschleunigt.

* **Reduzierung von Fehlern**: Die automatische Zuweisung von Kontobewegungen reduziert das Risiko von Fehlern bei der manuellen Zuordnung und erhöht die Genauigkeit der Zahlungsverfolgung.

* **Zeitersparnis**: Der Bank-Konto Sync spart Zeit, da er die manuelle Überprüfung von Kontobewegungen überflüssig macht und die manuelle Zuweisung von Kontobewegungen zu offenen Rechnungen reduziert.

### Bankkonto Sync aktivieren

Um Deine Bank mit Fynn zu verbinden und den Bank-Konto Sync zu aktivieren, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Zahlungsmethoden Einstellungen">
    Gehe zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods) und scrolle nach unten zu "Bankkonto".
  </Step>

  <Step title="Bankkonto hinzufügen">
    Klicke unter "Kontoabgleich" auf "Konten verwalten".

    <Frame>
      <img alt="Konten verwalten" />
    </Frame>
  </Step>

  <Step title="Bankkonto hinzufügen">
    Klicke nun in der Maske auf "Bankkonto verbinden". Es öffnet sich nun ein Fenster zur Auswahl der Bank.
    Hier kannst Du Deine Bank auswählen und wirst anschließend zu unserem Partner GoCardless weitergeleitet.

    <Check>
      Deine Zugangsdaten werden niemals mit uns geteilt und sind sicher bei GoCardless verschlüsselt.
      Wir erhalten nur Zugriff auf deine Kontobewegungen, um sie mit offenen Rechnungen abzugleichen.
    </Check>

    <Tip>
      Solltest du mehrere Bankkonten unter einem Zugang besitzen, kannst du diese nach Authorisierung bei GoCardless auswählen.
    </Tip>

    <Frame>
      <img alt="Bankkonto hinzufügen" />
    </Frame>
  </Step>

  <Step title="Bankkonto erfolgreich hinzugefügt 🎉">
    Dein Bankkonto wurde nun erfolggreich hinzugefügt. Es werden nun 2x täglich (8:00 Uhr, 16:00 Uhr)
    Kontobewegungen von Deinem Bankkonto abgerufen und mit offenen Rechnungen abgeglichen.
  </Step>
</Steps>

<Tip>
  Durch die Verwendung der Zahlungsmethode Überweisung und des Bank-Konto Syncs in Fynn kannst Du die Zahlungsabwicklung optimieren und Deine Buchhaltung effizienter gestalten.
</Tip>

<Tip>
  Bei der ersten Einrichtung werden die letzten 90 Tage an Kontobewegungen abgerufen und mit offenen Rechnungen abgeglichen.
</Tip>

## Kontobewegungen manuell zuweisen

In manchen Fällen kann es vorkommen, dass eine Kontobewegung nicht automatisch einer Rechnung zugeordnet werden kann,
da bspw. falsche Informationen in der Überweisung angegeben wurde, oder die Kontobewegung nicht zur Begleichung einer Rechnung gedacht war.

<Steps>
  <Step title="Kontobewegungen einsehen">
    Gehe zu [Zahlungen > Kontobewegungen](https://app.fynn.eu/finance/bank-transactions).

    Hier siehst Du alle Kontobewegungen, die von Deinem Bankkonto abgerufen wurden.

    <Frame>
      <img alt="Kontobewegungen einsehen" />
    </Frame>
  </Step>

  <Step title="Kontobewegung manuell zuweisen">
    Öffne die Kontobewegung, die Du manuell zuweisen möchtest, indem du auf das "Lupen"-Symbol klickst.
    Wähle nun die Rechnungen aus, die mit dieser Kontobewegung beglichen werden soll.

    <Frame>
      <img alt="Kontobewegung manuell zuweisen" />
    </Frame>
  </Step>

  <Step title="Kontobewegung manuell zuweisen">
    Klicke auf "Belege zuordnen", um die Kontobewegung manuell zuzuweisen.
  </Step>

  <Step title="(optional) Kontobewegung ignorieren">
    Sollte die Kontobewegung nicht zur Begleichung einer Rechnung gedacht sein, kannst Du sie auch ignorieren.
    Klicke hierzu auf das "Pfeil"-Symbol neben "Belege zuordnen" und wähle "Kontobewegung ignorieren".

    <Frame>
      <img alt="Kontobewegung ignorieren" />
    </Frame>
  </Step>

  <Step title="Die Kontobewegung wurde erfolgreich verarbeitet 🎉">
    Die Kontobewegung wurde nun erfolgreich zugewiesen oder ignoriert und die Rechnungen wurden beglichen.
  </Step>
</Steps>


# EBICS
Source: https://docs.fynn.eu/integrations/payment-providers/ebics

Mit der EBICS Integration können automatisch Überweisungen und Lastschriften direkt aus Fynn heraus durchgeführt werden.

<Frame>
  <img />
</Frame>

<Card title="Premium Addon" icon="sparkles">
  Die Salesforce Integration ist nur für Fynn Enterprise verfügbar. Bei Interesse an der Integration kontaktiere bitte <a href="mailto:hi@fynn.eu">[hi@fynn.eu](mailto:hi@fynn.eu)</a>
</Card>

Für die Einrichtung der EBICS Integration in Fynn benötigst du folgende Informationen von deiner Bank:

* **Bankverbindung**: Deine Bankverbindung, die du für die Überweisungen und Lastschriften verwenden möchtest.
* **EBICS-Kennung**: Deine persönliche EBICS-Kennung, die du von deiner Bank erhältst.
* **EBICS-Server**: Die EBICS-Serveradresse, die du von deiner Bank erhältst.
* **Zugangsdaten**: Deine EBICS-Zugangsdaten, die du ebenfalls von deiner Bank erhältst.

Gemeinsam mit diesen Informationen, komme bitte auf uns zu, damit wir die EBICS Integration in Fynn für dich einrichten können.


# GoCardless
Source: https://docs.fynn.eu/integrations/payment-providers/go-cardless

Wir bieten dir eine Vielzahl von Integrationen zu 3rd-Party-Tools und -Services, um die Funktionalität der Fynn-Plattform zu erweitern.

<Frame>
  <img />
</Frame>

70.000+ Unternehmen auf der gesamten Welt nutzen GoCardless um den Zahlungseinzug zu optimieren. Mit GoCardless wird der SEPA-Lastschrifteinzug zum Kinderspiel.

GoCardless beschützt dich vor hohen Kreditkartengebühren und Rücklastschriften. Kreditkarten sind nicht immer die bevorzugte Wahl bei der Bezahlung von Abonnements, was bedeutet, dass du dich nicht mit gestohlenen, verlorenen oder abgelaufenen Kreditkarten herumschlagen musst.

## Vorteile von GoCardless

* **Weniger fehlgeschlagene Zahlungen** - 97,1 % der Beiträge werden beim ersten Mal erfolgreich eingezogen.

* **Automatische Zahlungen**: GoCardless ermöglicht automatische Lastschriftzahlungen, was den Zahlungsprozess für Kunden und Unternehmen vereinfacht und sicherstellt, dass Rechnungen rechtzeitig beglichen werden.

* **Reduzierter Verwaltungsaufwand**: Durch die Automatisierung von Zahlungen mit GoCardless entfällt der manuelle Aufwand für die Bearbeitung von Zahlungen und die Verfolgung offener Rechnungen, was die Effizienz steigert und Fehler reduziert.

* **Verringertes Zahlungsausfallrisiko**: Die automatische Abbuchung per Lastschrift reduziert das Risiko von verspäteten oder ausbleibenden Zahlungen, da Zahlungen direkt vom Bankkonto des Kunden abgebucht werden.

* **Transparente Zahlungsabwicklung**: GoCardless bietet eine transparente und sichere Zahlungsabwicklung, was Vertrauen bei Kunden schafft und die Kundenzufriedenheit erhöht.

## GoCardless verbinden

<Check>
  Für die Verbindung von GoCardless benötigst du kein Konto. Dieses kannst du direkt während des Einrichtungsprozesses erstellen.
</Check>

Um GoCardless mit Fynn zu verbinden, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Zahlungsmethoden-Einstellungen">
    Gehe hierzu zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods).
  </Step>

  <Step title="Klicke auf Verbinden">
    Klicke neben dem GoCardless Logo auf den Button "Verbinden". Du wirst nun zur GoCardless-Website weitergeleitet, wo du dich mit deinem GoCardless-Konto anmelden oder ein neues Konto erstellen kannst.

    <Frame>
      <img alt="GoCardless verbinden" />
    </Frame>
  </Step>

  <Step title="GoCardless Konto anlegen oder anmelden">
    Wenn du bereits ein GoCardless-Konto hast, kannst du dich mit deinen Anmeldedaten einloggen. Andernfalls kannst du ein neues Konto erstellen, indem du auf "Erstellen Sie ein Konto" klickst und die erforderlichen Informationen eingibst.

    <Frame>
      <img alt="GoCardless Konto anlegen oder anmelden" />
    </Frame>
  </Step>

  <Step title="GoCardless ist erfolgreich verbunden 🎉">
    Nachdem du dich bei GoCardless angemeldet oder ein neues Konto erstellt hast, wirst du zur Fynn-Plattform zurückgeleitet und eine Bestätigung erhalten, dass GoCardless erfolgreich verbunden wurde.

    <Frame>
      <img alt="GoCardless erfolgreich verbunden" />
    </Frame>
  </Step>

  <Step title="(optional) SEPA-Lastschrift Zahlungsmethode aktivieren">
    Nachdem GoCardless erfolgreich verbunden wurde, kannst du die SEPA-Lastschrift-Zahlungsmethode aktivieren, indem du auf den Schalter neben "SEPA-Lastschrift" klickst.

    Näheres hierzu findest du unter [Zahlungsmethoden freigeben](/guide/tenant/payment-methods#zahlungsmethoden-freigeben).

    <Frame>
      <img alt="SEPA-Lastschrift Zahlungsmethode aktivieren" />
    </Frame>
  </Step>
</Steps>


# PayPal
Source: https://docs.fynn.eu/integrations/payment-providers/paypal

Wir bieten dir eine Vielzahl von Integrationen zu 3rd-Party-Tools und -Services, um die Funktionalität der Fynn-Plattform zu erweitern.

<Frame>
  <img />
</Frame>

Die Zahlungsmethode PayPal ermöglicht es den Kunden, ihre Rechnungen einfach und sicher über ihr PayPal-Konto zu begleichen. Hier erfährst Du mehr über die Vorteile von PayPal und wie Du es mit Fynn verbinden kannst:

## Vorteile von PayPal

* **Schnelle und sichere Zahlungen**: PayPal bietet eine schnelle und sichere Zahlungsmethode, bei der Kunden ihre Rechnungen einfach und bequem über ihr PayPal-Konto begleichen können.

* **Globale Akzeptanz**: PayPal wird weltweit akzeptiert und bietet Kunden eine vertrauenswürdige und bekannte Zahlungsmethode, unabhängig von ihrem Standort oder der Währung.

* **Käuferschutz**: PayPal bietet einen Käuferschutz, der Kunden zusätzliche Sicherheit gibt, falls es zu Problemen mit der Bestellung oder Zahlung kommt.

## PayPal verbinden

<Check>
  Für die Verbindung von PayPal benötigst du kein Konto. Dieses kannst du direkt während des Einrichtungsprozesses erstellen.
</Check>

Um PayPal mit Fynn zu verbinden, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Zahlungsmethoden-Einstellungen">
    Gehe hierzu zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods).
  </Step>

  <Step title="Klicke auf Verbinden">
    Klicke neben dem PayPal Logo auf den Button "Verbinden". Du wirst nun zur PayPal-Website weitergeleitet, wo du dich mit deinem PayPal-Konto anmelden oder ein neues Konto erstellen kannst.

    <Frame>
      <img alt="PayPal verbinden" />
    </Frame>
  </Step>

  <Step title="PayPal Konto anlegen oder anmelden">
    Wenn du bereits ein PayPal-Konto hast, kannst du dich mit deinen Anmeldedaten einloggen. Andernfalls kannst du ein neues Konto erstellen.
  </Step>

  <Step title="PayPal E-Mail Adresse bestätigen">
    Nachdem du dich bei PayPal angemeldet oder ein neues Konto erstellt hast, wirst du zur Fynn-Plattform zurückgeleitet.
    Anschließend muss deine PayPal E-Mail Adresse bestätigt werden, bevor du Zahlungen über PayPal akzeptieren kannst.
  </Step>

  <Step title="PayPal ist erfolgreich verbunden 🎉">
    Nachdem du deine PayPal E-Mail Adresse bestätigt hast, ist PayPal erfolgreich verbunden und du kannst Zahlungen über PayPal akzeptieren.
  </Step>

  <Step title="(optional) PayPal Zahlungsmethode aktivieren">
    Nachdem PayPal erfolgreich verbunden wurde, kannst du die PayPal-Zahlungsmethode aktivieren, indem du auf den Schalter neben "PayPal" klickst.

    Näheres hierzu findest du unter [Zahlungsmethoden freigeben](/guide/tenant/payment-methods#zahlungsmethoden-freigeben).

    <Frame>
      <img alt="PayPal Zahlungsmethode aktivieren" />
    </Frame>
  </Step>
</Steps>


# SEPA-Lastschrift
Source: https://docs.fynn.eu/integrations/payment-providers/sepa

Wir bieten dir eine Vielzahl von Integrationen zu 3rd-Party-Tools und -Services, um die Funktionalität der Fynn-Plattform zu erweitern.

Die Zahlungsmethode SEPA-Lastschrift über die Hausbank ermöglicht es den Kunden, ihre Rechnungen automatisch per Lastschriftverfahren von ihrem Bankkonto abzubuchen. Hier erfährst Du mehr über die Vorteile von SEPA-Lastschrift und wie Du es mit Fynn verbinden kannst:

## Vorteile von SEPA-Lastschrift über die Hausbank

* **Automatische Zahlungen**: SEPA-Lastschrift ermöglicht automatische Abbuchungen von Rechnungsbeträgen direkt vom Bankkonto des Kunden, was eine bequeme und zuverlässige Zahlungsmethode darstellt.

* **Reduzierter Verwaltungsaufwand**: Durch die Automatisierung von Zahlungen entfällt der manuelle Aufwand für die Bearbeitung von Rechnungen und die Verfolgung offener Posten, was die Effizienz steigert und Fehler minimiert.

* **Pünktliche Zahlungen**: SEPA-Lastschrift gewährleistet pünktliche Zahlungen, da Rechnungsbeträge zum Fälligkeitsdatum automatisch vom Bankkonto des Kunden abgebucht werden.

* **Sicherheit und Zuverlässigkeit**: SEPA-Lastschrift bietet eine sichere und zuverlässige Zahlungsmethode, da Zahlungen direkt zwischen Bankkonten abgewickelt werden und das SEPA-System strenge Sicherheitsstandards erfüllt.

## SEPA-Lastschrift einrichten

<Check>
  Für die Verbindung von SEPA-Lastschrift über die Hausbank mit Fynn, benötigst du kein Konto.
</Check>

Um PayPal mit Fynn zu verbinden, folge diesen Schritten:

<Steps>
  <Step title="Öffne die Zahlungsmethoden-Einstellungen">
    Gehe hierzu zu [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods).
  </Step>

  <Step title="Klicke auf Verbinden">
    Klicke neben dem SEPA Logo auf den Button "Verbinden". Es öffnet sich nun ein neues Fenster, in dem du SEPA-Lastschrift über die Hausbank mit Fynn konfigurieren kannst.

    <Frame>
      <img alt="SEPA-Lastschrift verbinden" />
    </Frame>
  </Step>

  <Step title="SEPA-Lastschrift konfigurieren">
    Fülle die erforderlichen Felder aus, um SEPA-Lastschrift über die Hausbank mit Fynn zu verbinden. Hierzu gehören:

    * **Gläuber-Identifikationsnummer**: Die Gläuber-Identifikationsnummer (Creditor Identifier) ist eine eindeutige Kennung, die von der Deutschen Bundesbank vergeben wird und die Identifizierung des Gläubigers bei SEPA-Lastschrifttransaktionen ermöglicht.
    * **Verwendungszweck**: Der Verwendungszweck ist ein individueller Text, der auf dem Kontoauszug des Kunden erscheint und zur Identifizierung der Zahlung dient.

    <Frame>
      <img alt="SEPA-Lastschrift konfigurieren" />
    </Frame>
  </Step>

  <Step title="SEPA-Lastschrift ist erfolgreich verbunden 🎉">
    Du kannst nun SEPA-Lastschrift über die Hausbank mit Fynn verwenden, um automatische Zahlungen von deinen Kunden zu akzeptieren.
  </Step>

  <Step title="(optional) SEPA-Lastschrift Zahlungsmethode aktivieren">
    Nachdem SEPA-Lastschrift erfolgreich verbunden wurde, kannst du die SEPA-Lastschrift-Zahlungsmethode aktivieren, indem du auf den Schalter neben "SEPA-Lastschrift" klickst.

    Näheres hierzu findest du unter [Zahlungsmethoden freigeben](/guide/tenant/payment-methods#zahlungsmethoden-freigeben).

    <Frame>
      <img alt="SEPA-Lastschrift aktivieren" />
    </Frame>
  </Step>
</Steps>

## SEPA-Lastschriften bei der Hausbank hochladen

Um SEPA-Lastschriften einzuziehen, musst du die SEPA-Lastschriften bei deiner Hausbank hochladen. Befolge dafür folgende Schritte:

<Note>
  Eine automatisierte Integration zur Übertragung von SEPA-Lastschriften an die Hausbank über die EBICS-Schnittstelle ist in Planung.
</Note>

<Steps>
  <Step title="Öffne SEPA-Auftragsübersicht">
    Klicke hierzu in der Web-App auf der linken Seite auf "SEPA-Aufträge" und klicke auf "Datei generieren".

    <Frame>
      <img alt="SEPA-Lastschrift-Datei generieren" />
    </Frame>
  </Step>

  <Step title="Konfiguriere die SEPA-Auftragsdatei">
    Nun öffnet sich ein neues Fenster, in dem du die SEPA-Auftragsdatei konfigurieren kannst.

    <Info>
      Bei einigen Banken kann es aus technischen Gründen notwendig sein, dass jede Zahlung eine eigene Datei ist. In diesem Fall
      kannst du "Zahlung aufteilen" aktivieren.
    </Info>

    <Info>
      Möchtest du nur eine einzelne Buchung auf deinem Bankkonto haben, kannst du "Sammelbuchung" aktivieren.
    </Info>

    <Frame>
      <img alt="SEPA-Lastschrift-Datei konfigurieren" />
    </Frame>
  </Step>

  <Step title="SEPA-Aufträge generieren">
    Klicke auf "SEPA-Aufträge generieren". Es wird nun eine Datei generiert, die du bei deiner Hausbank hochladen kannst.
  </Step>

  <Step title="SEPA-Auftrag bei der Hausbank hochladen">
    Lade nun die generierte SEPA-Datei bei deiner Hausbank hoch, um die SEPA-Lastschriften einzuziehen.
  </Step>

  <Step title="SEPA-Auftrag als Hochgeladen markieren">
    Nachdem du die SEPA-Lastschriften bei deiner Hausbank hochgeladen hast, solltest du die SEPA-Aufträge in Fynn als "Hochgeladen" markieren.
    Dies löst die SEPA-Lastschriftvorankündigung aus und informiert deine Kunden über die bevorstehende Abbuchung.
  </Step>

  <Step title="SEPA-Auftrag erfolgreich hochgeladen 🎉">
    Du hast nun erfolgreich SEPA-Lastschriften bei deiner Hausbank hochgeladen und die SEPA-Aufträge in Fynn als "Hochgeladen" markiert.
  </Step>
</Steps>


# Accept the suggestions
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/accept-the-suggestions

put /payment/bank-account-transactions/accept-suggestions
Accept the suggestions for the bank account transaction. 
This will create a new transaction with the remaining bank transaction amount upto the unpaid invoice amounts.
When the bank transaction has a remaining amount, you can assign that to other invoices.

<sup>Required permissions: `bank-account-transaction:write`</sup>



# Assign invoices to the bank account transaction.
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/assign-invoices-to-the-bank-account-transaction

put /payment/bank-account-transactions/{id}/assign-invoices
Assign invoices to the bank account transaction. 
This will create a new transaction with the remaining bank transaction amount upto the unpaid invoice amount.
When the bank transaction has a remaining amount, you can assign that to other invoices.

<sup>Required permissions: `bank-account-transaction:write`</sup>



# Assign Invoices and Book the Remainder
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/assign-with-disposition

Assign one or more invoices to a bank account transaction and immediately dispose of any remaining or overpaid amount in a single request.

`POST /api/payment/bank-account-transactions/{id}/assign-with-disposition`

Assigns invoices to a bank account transaction and, in the same request, handles the remaining or
overpaid amount according to a chosen `disposition`. This combines invoice assignment and remainder
booking into one atomic operation, eliminating the separate follow-up step.

**Required permission:** `BankAccountTransactionWrite`

***

## Request

### Path parameters

| Parameter | Type          | Description                         |
| --------- | ------------- | ----------------------------------- |
| `id`      | string (UUID) | ID of the bank account transaction. |

### Request body

```json theme={null}
{
  "invoiceIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "disposition": "credit_wallet",
  "assignmentAmounts": null
}
```

| Field               | Type                                 | Required | Description                                                                                                                                                                                          |
| ------------------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoiceIds`        | array of UUID strings                | Yes      | Invoices to assign, in assignment order. Must contain at least one entry. All IDs must exist; an unknown ID yields a 422 before anything is booked.                                                  |
| `disposition`       | string (enum)                        | Yes      | How to handle the remaining or overpaid amount. See [Disposition values](#disposition-values) below.                                                                                                 |
| `assignmentAmounts` | object (invoice ID → decimal string) | No       | Optional per-invoice amount caps. Keys must be invoice IDs from `invoiceIds`. Not supported with `credit_wallet` or `credit_wallet_and_payout`: omit or send `null` when using a wallet disposition. |

### Disposition values

| Value                      | Behaviour                                                                                                                                                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `open`                     | Leaves the remainder unbooked. The transaction keeps an outstanding amount and can be assigned to further invoices later. This reproduces the behaviour of the plain assign endpoint.                                                                        |
| `credit_wallet`            | Overpays the last assigned invoice by the full remaining amount so the transaction is fully booked, then moves that overpayment to the customer's credit balance (Guthaben). Requires all invoices to belong to a single customer.                           |
| `credit_wallet_and_payout` | **Currently not available** (returns 422 `payout_not_available`). Identical to `credit_wallet`, but would additionally schedule a SEPA payout of the credited amount back to the customer. Disabled pending the outbound ledger leg in the payout subsystem. |

<Warning>
  `credit_wallet_and_payout` returns a 422 with reason `payout_not_available` for every request.
  The disposition is accepted by the schema but blocked at the service layer until the payout
  subsystem books its outbound ledger leg. Use `credit_wallet` if you want to credit the remainder
  to the customer's balance without an immediate payout.
</Warning>

***

## Response

**HTTP 200: Invoices assigned and remainder disposed.**

```json theme={null}
{
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "STATUS_BOOKED",
  "disposition": "credit_wallet",
  "unassignedAmount": 0,
  "disposedAmount": 1000,
  "currencyCode": "EUR",
  "payoutId": null
}
```

| Field              | Type                  | Description                                                                                             |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
| `transactionId`    | string (UUID)         | ID of the bank account transaction.                                                                     |
| `status`           | string                | Updated status of the transaction (e.g. `STATUS_BOOKED`, `STATUS_OUTSTANDING_AMOUNT`).                  |
| `disposition`      | string                | The disposition that was applied (`open`, `credit_wallet`, or `credit_wallet_and_payout`).              |
| `unassignedAmount` | integer               | Remaining unassigned amount in cents after the operation. `0` when the transaction is fully booked.     |
| `disposedAmount`   | integer or null       | Amount moved to the customer's credit balance, in cents. `null` for the `open` disposition.             |
| `currencyCode`     | string                | ISO 4217 currency code (e.g. `EUR`).                                                                    |
| `payoutId`         | string (UUID) or null | ID of the initiated payout. `null` unless `credit_wallet_and_payout` was used and a payout was created. |

***

## Examples

### Assign one invoice and leave the remainder open

```json theme={null}
{
  "invoiceIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "disposition": "open"
}
```

**Response**

```json theme={null}
{
  "transactionId": "a1b2c3d4-0000-4000-8000-000000000001",
  "status": "STATUS_OUTSTANDING_AMOUNT",
  "disposition": "open",
  "unassignedAmount": 2500,
  "disposedAmount": null,
  "currencyCode": "EUR",
  "payoutId": null
}
```

***

### Assign two invoices and credit the remainder to the customer's balance

```json theme={null}
{
  "invoiceIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "ad8f1b9e-1b9e-4c4c-8f1b-9e1b9e4c4c8f"
  ],
  "disposition": "credit_wallet"
}
```

**Response**

```json theme={null}
{
  "transactionId": "a1b2c3d4-0000-4000-8000-000000000001",
  "status": "STATUS_BOOKED",
  "disposition": "credit_wallet",
  "unassignedAmount": 0,
  "disposedAmount": 1000,
  "currencyCode": "EUR",
  "payoutId": null
}
```

The transaction is fully booked. EUR 10.00 was credited to the customer's balance (Guthaben).

***

### Assign with per-invoice amount caps (`open` disposition)

Use `assignmentAmounts` when you want to assign a specific partial amount per invoice rather than
the invoice's full outstanding balance. This is only available with `disposition: "open"`.

```json theme={null}
{
  "invoiceIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "ad8f1b9e-1b9e-4c4c-8f1b-9e1b9e4c4c8f"
  ],
  "disposition": "open",
  "assignmentAmounts": {
    "3fa85f64-5717-4562-b3fc-2c963f66afa6": "150.00",
    "ad8f1b9e-1b9e-4c4c-8f1b-9e1b9e4c4c8f": "200.00"
  }
}
```

***

## Errors

All errors follow the standard `problem+json` format.

| HTTP status | `reason`                                     | Description                                                                                                                                                                                                                        |
| ----------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403         | (none)                                       | The API token does not have the `BankAccountTransactionWrite` permission.                                                                                                                                                          |
| 404         | (none)                                       | No bank account transaction found for the given `id` within the organisation.                                                                                                                                                      |
| 422         | `assignment_amounts_with_wallet_disposition` | `assignmentAmounts` was provided together with `credit_wallet` or `credit_wallet_and_payout`. Per-invoice amount caps are not supported with wallet dispositions because the remainder must be fully absorbed by the last invoice. |
| 422         | `return_transaction`                         | The transaction is a returned direct debit (Rücklastschrift) and cannot be assigned here.                                                                                                                                          |
| 422         | `non_positive_transaction`                   | Wallet dispositions require an incoming (positive) transaction.                                                                                                                                                                    |
| 422         | `no_single_payment_intent`                   | The last invoice has no single resolvable payment intent to book the remainder against.                                                                                                                                            |
| 422         | `payout_not_available`                       | `credit_wallet_and_payout` was requested but is not yet available. Use `credit_wallet` instead.                                                                                                                                    |
| 422         | (validation)                                 | An invoice ID in `invoiceIds` does not exist, `invoiceIds` is empty, or `disposition` is not a valid enum value.                                                                                                                   |
| 422         | (domain)                                     | The invoices span multiple customers. Wallet dispositions (`credit_wallet`, `credit_wallet_and_payout`) require all invoices to belong to a single customer.                                                                       |


# Get a bank account transaction assignment
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/get-a-bank-account-transaction-assignment

get /payment/bank-account-transaction-assignments/{id}
Get a bank account transaction assignment, which shows the match between a bank account transaction and an invoice.



# Get bank account transaction details
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/get-bank-account-transaction-details

get /payment/bank-account-transactions/{id}
Get the bank account transaction details with all the assigned invoices and transactions.

<sup>Required permissions: `bank-account-transaction:read`</sup>



# Get bank account transactions
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/get-bank-account-transactions

get /payment/bank-account-transactions
Get the bank account transactions. Bank account transactions are synchronized (e.g. by <a href="#tag/Open-Banking/operation/connectKlarna">Klarna Sync</a>) or uploaded statements from the bank account.
The bank account transactions are matched with invoices and transactions. 
If the bank account transaction is not matched, it is shown in the list of bank account transactions with the status "matching required".
If the bank account transaction is matched, it is shown in the list of bank account transactions with the status "booked" or "outstanding amount".
If the bank account transaction is ignored, the transaction won't be processed and is not shown in the list of bank account transactions anymore.

<sup>Required permissions: `bank-account-transaction:read`</sup>



# Get the status count of the bank account transactions
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/get-the-status-count-of-the-bank-account-transactions

get /payment/bank-account-transactions/status-count
Retrieves a BankAccountTransaction resource.

<sup>Required permissions: `bank-account-transaction:read`</sup>



# Ignore bank account transactions.
Source: https://docs.fynn.eu/api-reference/bankaccounttransaction/ignore-bank-account-transactions

put /payment/bank-account-transactions/ignore
Ignore bank account transactions. The transaction will not be processed and showed in the list of transactions.
This is useful for transactions that are not relevant for the business, e.g. incoming payments for rentals.
Otherwise you can hide a bank transaction which is already assigned and has an outstanding, not mappable amount.

<sup>Required permissions: `bank-account-transaction:write`</sup>



# Create a billing group
Source: https://docs.fynn.eu/api-reference/billinggroup/create-a-billing-group

post /billing-groups
Create a billing group, to group the billing date of subscriptions. If a subscription is not assigned to a billing group, it will be charged in the billing interval from creation date.

Subscriptions which are assigned to a billing group will be charged on the billing date of the billing group with proration.



# Get a billing group
Source: https://docs.fynn.eu/api-reference/billinggroup/get-a-billing-group

get /billing-groups/{id}
Get a billing group



# Get a collection of billing groups
Source: https://docs.fynn.eu/api-reference/billinggroup/get-a-collection-of-billing-groups

get /customers/{customerId}/billing-groups
Get a collection of billing groups



# Get billing run details for an invoice
Source: https://docs.fynn.eu/api-reference/billingrun/get-billing-run-details-for-an-invoice

get /invoices/{invoiceId}/billing-run
Get all billing run details which created the invoice. This includes all subscriptions, subscription items and the date range which was billed.

<sup>Required permissions: `invoice:read`</sup>



# Create a coupon
Source: https://docs.fynn.eu/api-reference/coupon/create-a-coupon

post /coupons
You can create a coupon, which can be used by customers to get a discount on their subscription.
You can create a coupon with a *fixed amount* or a *percentage*. You can also set a maximum number of uses and a maximum number of uses per customer.
You can also set an end date, after which the coupon is no longer valid.

The coupon code can be used in the checkout process, in the customer front, or via the API.


<sup>Required permissions: `coupon:write`</sup>



# Delete a coupon
Source: https://docs.fynn.eu/api-reference/coupon/delete-a-coupon

delete /coupons/{id}
Delete a coupon.

<sup>Required permissions: `coupon:write`</sup>



# Get a coupon
Source: https://docs.fynn.eu/api-reference/coupon/get-a-coupon

get /coupons/{id}
Get a coupon.

<sup>Required permissions: `coupon:read`</sup>



# Get all coupons
Source: https://docs.fynn.eu/api-reference/coupon/get-all-coupons

get /coupons
Get all coupons.

<sup>Required permissions: `coupon:read`</sup>



# Get all redeemptions for a coupon
Source: https://docs.fynn.eu/api-reference/coupon/get-all-redeemptions-for-a-coupon

get /coupons/{couponId}/redeemptions
Get all redeemptions for a coupon.

<sup>Required permissions: `coupon:read`</sup>



# Toggle a coupon
Source: https://docs.fynn.eu/api-reference/coupon/toggle-a-coupon

put /coupons/{id}/toggle
Toggle a coupon.

<sup>Required permissions: `coupon:write`</sup>



# Update a coupon
Source: https://docs.fynn.eu/api-reference/coupon/update-a-coupon

put /coupons/{id}
Update a coupon.

<sup>Required permissions: `coupon:write`</sup>



# Cancel dunning document
Source: https://docs.fynn.eu/api-reference/dunningdocument/cancel-dunning-document

put /dunning/documents/{id}/cancel
Cancel dunning document and stop dunning process for this invoice

<sup>Required permissions: `dunning-document:write`</sup>



# Get dunning document
Source: https://docs.fynn.eu/api-reference/dunningdocument/get-dunning-document

get /dunning/documents/{id}
Get dunning document

<sup>Required permissions: `dunning-document:read`</sup>



# Get dunning documents
Source: https://docs.fynn.eu/api-reference/dunningdocument/get-dunning-documents

get /dunning/documents
Get dunning documents

<sup>Required permissions: `dunning-document:read`</sup>



# Add comment
Source: https://docs.fynn.eu/api-reference/invoice/add-comment

post /invoices/{id}/comment
Add comment. This is available for invoices, credit notes and cancellations.

<sup>Required permissions: `invoice:write`</sup>



# Add invoice payment
Source: https://docs.fynn.eu/api-reference/invoice/add-invoice-payment

post /invoices/{id}/payments
Add a payment to the invoice. This is only possible if the invoice is in status unpaid. This is available for invoices and credit notes.

<sup>Required permissions: `transaction:write`</sup>



# Add invoice position items
Source: https://docs.fynn.eu/api-reference/invoice/add-invoice-position-items

post /invoices/{id}/position-items
Add invoice position items to the invoice. This is only possible if the invoice is in status draft or new. This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Cancel invoice
Source: https://docs.fynn.eu/api-reference/invoice/cancel-invoice

post /invoices/{id}/cancel
Cancel an invoice. This will cancel the invoice and send a cancellation email to the customer. This is only possible if the invoice is already finalized and not paid or partial paid. This is available for invoices only.

<sup>Required permissions: `invoice:cancel`</sup>



# Close invoice
Source: https://docs.fynn.eu/api-reference/invoice/close-invoice

put /invoices/{id}/close
Close an invoice. This is only possible if the invoice is in status "STATUS_DRAFT" or "STATUS_NEW" (waiting for approval). This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Create draft invoice
Source: https://docs.fynn.eu/api-reference/invoice/create-draft-invoice

post /invoices
Create a new invoice in status draft. This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Credit invoice
Source: https://docs.fynn.eu/api-reference/invoice/credit-invoice

post /invoices/{id}/credit
Credit an invoice. This will credit the given positions and send an email to the customer. This is only possible if the invoice is already finalized and paid or partial paid. This is available for invoices only.

<sup>Required permissions: `invoice:credit`</sup>



# Delete invoice
Source: https://docs.fynn.eu/api-reference/invoice/delete-invoice

delete /invoices/{id}
Delete an invoice. This is only possible if the invoice is in status "STATUS_DRAFT" or "STATUS_NEW" (waiting for approval). This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Duplicate invoice
Source: https://docs.fynn.eu/api-reference/invoice/duplicate-invoice

post /invoices/{id}/duplicate
Duplicate an invoice. This will create a new draft invoice with the same positions and customer address. This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Finalize invoice
Source: https://docs.fynn.eu/api-reference/invoice/finalize-invoice

post /invoices/{id}/finalize
Finalize an invoice.
                This will generate the pdf, create a payment intent and send the invoice to the customer.
                
                *Preconditions:*
                - The invoice must be in status draft or new.
                - The invoice must have a customer address.
                - The invoice must have a valid payment method, which is not expired and enabled.
                - The invoice must have at least one position item.
                - The customer must be in "active" state.
                
                This is available for invoices only.
                

<sup>Required permissions: `invoice:finalize`</sup>



# Get invoice
Source: https://docs.fynn.eu/api-reference/invoice/get-invoice

get /invoices/{id}
Get a single invoice by its id. This is available for invoices, credit notes and cancellations.

<sup>Required permissions: `invoice:read`</sup>



# Get invoice download link
Source: https://docs.fynn.eu/api-reference/invoice/get-invoice-download-link

put /invoices/{id}/download-link
Get the download link of the invoice. The link is valid for 24 hours. This is available for invoices, credit notes and cancellations.

<sup>Required permissions: `invoice:read`, `customer:invoice:read`</sup>



# Get invoice preview
Source: https://docs.fynn.eu/api-reference/invoice/get-invoice-preview

get /invoices/{id}/preview
Get a preview of the invoice. This will generate the pdf and return it. This is available for invoices, credit notes and cancellations.

<sup>Required permissions: `invoice:read`</sup>



# Get invoices
Source: https://docs.fynn.eu/api-reference/invoice/get-invoices

get /invoices
Get all invoices. If the user is authenticated as customer (e.g. by the customerfront) the invoices are filtered by their customer. This is available for invoices, credit notes and cancellations.

<sup>Required permissions: `invoice:read`</sup>



# Resend invoice
Source: https://docs.fynn.eu/api-reference/invoice/resend-invoice

put /invoices/{id}/resend
Resend an invoice. This will resend the generated pdf to the customer as a duplicate. This is only possible if the invoice is already finalized. This is available for invoices, credit notes and cancellations.

<sup>Required permissions: `invoice:write`</sup>



# Set invoice customer address
Source: https://docs.fynn.eu/api-reference/invoice/set-invoice-customer-address

post /invoices/{id}/customer-address
Set an invoice address based on an existing customer address. *The vat id will be updated accordingly.* This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Set invoice note
Source: https://docs.fynn.eu/api-reference/invoice/set-invoice-note

put /invoices/{id}/internal-note
Set the internal note of the invoice.

<sup>Required permissions: `invoice:write`</sup>



# Set invoice payment method
Source: https://docs.fynn.eu/api-reference/invoice/set-invoice-payment-method

post /invoices/{id}/payment-method
Set the payment method for the invoice. The payment method must be enabled and not expired. This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Toggle dunning
Source: https://docs.fynn.eu/api-reference/invoice/toggle-dunning

put /invoices/{id}/dunning
Disable or enable dunning for the invoice. This is only possible if the invoice is in status "STATUS_UNPAID". If dunning is enabled after it was disabled, the next dunning rule will be applied automatically. This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Update draft invoice
Source: https://docs.fynn.eu/api-reference/invoice/update-draft-invoice

put /invoices/{id}
Update a draft invoice. This is available for invoices only.

<sup>Required permissions: `invoice:write`</sup>



# Upload custom invoice PDF
Source: https://docs.fynn.eu/api-reference/invoice/upload-invoice-pdf

post /invoices/{id}/pdf
Upload a custom-rendered PDF for an invoice that is currently in the Finalizing state. This endpoint is used by external PDF rendering engines that receive the `invoice.pdf.generation_requested` webhook.

**Enterprise Feature**: This endpoint requires the Custom PDF Rendering feature to be enabled.

After upload, Fynn will:
- Optionally embed ZUGFeRD/Factur-X XML data (if configured)
- Continue the invoice finalization process
- Send notifications and trigger payment collection

<sup>Required permissions: `invoice:write`</sup>



# Delete an invoice position item
Source: https://docs.fynn.eu/api-reference/invoicepositionitem/delete-an-invoice-position-item

delete /invoice-position-items/{id}
Delete an invoice position item. This is only possible for invoices that are in status draft or new.

<sup>Required permissions: `invoice:write`</sup>



# Get an invoice position item
Source: https://docs.fynn.eu/api-reference/invoicepositionitem/get-an-invoice-position-item

get /invoice-position-items/{id}
Get an invoice position item.

<sup>Required permissions: `invoice:read`</sup>



# Update an invoice position item
Source: https://docs.fynn.eu/api-reference/invoicepositionitem/update-an-invoice-position-item

put /invoice-position-items/{id}
Update an invoice position item. This is only possible for invoices that are in status draft or new.

<sup>Required permissions: `invoice:write`</sup>



# [Deprecated, removed 2026-08-01] Create an offer
Source: https://docs.fynn.eu/api-reference/offer/create-an-offer

post /subscriptions/{id}/offers
Create a new offer

<sup>Required permissions: `offer:write`</sup>



# [Deprecated, removed 2026-08-01] Get a offer document
Source: https://docs.fynn.eu/api-reference/offer/get-a-offer-document

get /offers/{id}/document
Get a single offer document



# [Deprecated, removed 2026-08-01] Get a public offer
Source: https://docs.fynn.eu/api-reference/offer/get-a-public-offer

get /public/offers/{id}
Get a single public offer



# [Deprecated, removed 2026-08-01] Get an offer
Source: https://docs.fynn.eu/api-reference/offer/get-an-offer

get /offers/{id}
Get a single offer

<sup>Required permissions: `offer:read`</sup>



# Get offers
Source: https://docs.fynn.eu/api-reference/offer/get-offers

get /offers
Get a list of offers

<sup>Required permissions: `offer:read`</sup>



# Update an offer
Source: https://docs.fynn.eu/api-reference/offer/update-an-offer

put /offers/{id}
Update an existing offer

<sup>Required permissions: `offer:write`</sup>



# Connect Klarna
Source: https://docs.fynn.eu/api-reference/open-banking/connect-klarna

post /klarna/connect
Connect Klarna to allow fetching transactions from your bank account

<sup>Required permissions: `open-banking:fetch-transactions`</sup>



# Disconnect open banking account
Source: https://docs.fynn.eu/api-reference/open-banking/disconnect-open-banking-account

put /open-banking-accounts/{id}/disconnect
Disconnect an open banking account, to prevent further access to the account information

<sup>Required permissions: `open-banking-account:write`</sup>



# Trigger a transaction fetch for an open banking account
Source: https://docs.fynn.eu/api-reference/open-banking/fetch-open-banking-account-transactions

post /api/open-banking-accounts/{id}/fetch-transactions
Queues a transaction fetch for the account, starting at the last successful access. The fetch runs asynchronously. Fetches are rate limited per account (EBICS: 15 minutes, other providers: 6 hours) to protect the quotas of the banking providers.

<sup>Required permissions: `open-banking:fetch-transactions`</sup>



# Get connected open banking accounts
Source: https://docs.fynn.eu/api-reference/open-banking/get-connected-open-banking-accounts

get /open-banking-accounts
Get all connected open banking accounts, which allows to access transactions, balances and other information

<sup>Required permissions: `open-banking-account:read`</sup>



# Get open banking account
Source: https://docs.fynn.eu/api-reference/open-banking/get-open-banking-account

get /open-banking-accounts/{id}
Get open banking account details.

<sup>Required permissions: `open-banking-account:read`</sup>



# Get overdue rules
Source: https://docs.fynn.eu/api-reference/overduerule/get-overdue-rules

get /dunning/overdue-rules
Get overdue rules.

<sup>Required permissions: `dunning-rule:read`</sup>



# Update overdue rule
Source: https://docs.fynn.eu/api-reference/overduerule/update-overdue-rule

put /dunning/overdue-rules/{id}
Update overdue rule.

<sup>Required permissions: `dunning-rule:write`</sup>



# Get transaction
Source: https://docs.fynn.eu/api-reference/payment-transaction/get-transaction

get /payment/transactions/{id}
Get a payment transaction, which represents a payment, refund or payout.



# Get transactions
Source: https://docs.fynn.eu/api-reference/payment-transaction/get-transactions

get /payment/transactions
Get a list of payment transactions, which represents a payment, refund or payout.

<sup>Required permissions: `transaction:read`</sup>



# Create payment method
Source: https://docs.fynn.eu/api-reference/paymentmethod/create-payment-method

post /payment-methods
Create a customer's payment method

<sup>Required permissions: `payment-method:add`</sup>



# Create payment method link
Source: https://docs.fynn.eu/api-reference/paymentmethod/create-payment-method-link

post /payment-methods/link
Create a link to request the customer to add a new payment method. The link can be sent to the customer via email.

<sup>Required permissions: `payment-method:add`</sup>



# Get customer's payment methods
Source: https://docs.fynn.eu/api-reference/paymentmethod/get-customers-payment-methods

get /customers/{customerId}/payment-methods
Get customer's payment methods.

<sup>Required permissions: `payment-method:read`, `customer:payment-method:read`</sup>



# Migrate stripe payment methods
Source: https://docs.fynn.eu/api-reference/paymentmethod/migrate-stripe-payment-methods

post /payment-methods/migrate/stripe
Assigns stripe customer ids to fynn customers, which are matched by email. After that, all **not expired** and **attached** payment methods will be created in fynn.

<sup>Required permissions: `payment-method:migrate`</sup>



# Upload a document for a payment method
Source: https://docs.fynn.eu/api-reference/paymentmethod/upload-a-document-for-a-payment-method

post /payment-methods/{id}/document
Upload a document for a payment method, e.g. a signed sepa mandate

<sup>Required permissions: `payment-method:write`</sup>



# Archive a price plan.
Source: https://docs.fynn.eu/api-reference/priceplan/archive-a-price-plan

put /price-plans/{id}/archive
Archive a price plan. Archived price plans will not be shown in any lists, until it is explicit requested.

<sup>Required permissions: `price-plan:write`</sup>



# Get a Sepa XML payment
Source: https://docs.fynn.eu/api-reference/sepa-xml-payments/get-a-sepa-xml-payment

get /sepa-xml-payments/{id}
Get a Sepa XML payment



# Delete a SEPA XML file
Source: https://docs.fynn.eu/api-reference/sepaxmlstatement/delete-a-sepa-xml-file

delete /sepa-xml-files/{id}
Deletes a SEPA XML file and the associated media file. The deletion is only allowed, when the `uploaded` property is `false`. All related payment transactions will be marked as unprocessed and can be used for a new SEPA XML file.

<sup>Required permissions: `sepa-xml:write`</sup>



# Generate a SEPA XML file
Source: https://docs.fynn.eu/api-reference/sepaxmlstatement/generate-a-sepa-xml-file

post /sepa-xml-files/generate
Generates a SEPA XML file from unprocessed sepa xml payments.
The generated SEPA XML file needs to be uploaded to the bank **manually**.
**After uploading the SEPA XML file to the bank, you need to mark the SEPA XML file as uploaded.**
The SEPA XML file can contain *direct debits* and *credit* transfers.
Credit transfers is used for (partial) refunds.

The generated SEPA XML file is returned as zip file and can be redownloaded later.

<sup>Required permissions: `sepa-xml:write`</sup>



# Get a list of SEPA XML files
Source: https://docs.fynn.eu/api-reference/sepaxmlstatement/get-a-list-of-sepa-xml-files

get /sepa-xml-files
Returns a list of generated SEPA XML files.

<sup>Required permissions: `sepa-xml:read`</sup>



# Get a SEPA XML file
Source: https://docs.fynn.eu/api-reference/sepaxmlstatement/get-a-sepa-xml-file

get /sepa-xml-files/{id}
Returns a generated SEPA XML file.

<sup>Required permissions: `sepa-xml:read`</sup>



# Mark a SEPA XML file as uploaded
Source: https://docs.fynn.eu/api-reference/sepaxmlstatement/mark-a-sepa-xml-file-as-uploaded

put /sepa-xml-files/{id}/uploaded
Marks a SEPA XML file as uploaded to the bank. This means, that the SEPA XML file was uploaded to the bank already. All related payment transactions will be marked as waiting, until the grace period of the bank is over. You cannot regenerate the SEPA XML file, when it was marked as uploaded.

<sup>Required permissions: `sepa-xml:write`</sup>



# Add a batch of subscription measurement.
Source: https://docs.fynn.eu/api-reference/subscription-measurement/add-a-batch-of-subscription-measurement

post /subscription-measurements/batch
Add a batch of subscription measurement. This could be a quantity changes, or a metered usages.



# Add a subscription measurement.
Source: https://docs.fynn.eu/api-reference/subscription-measurement/add-a-subscription-measurement

post /subscription-measurements
Add a subscription measurement. This could be a quantity change, or a metered usage.



# Get a subscription measurement.
Source: https://docs.fynn.eu/api-reference/subscription-measurement/get-a-subscription-measurement

get /subscription-measurements/{id}
Get a subscription measurement.



# Activate subscription
Source: https://docs.fynn.eu/api-reference/subscription/activate-subscription

put /subscriptions/{id}/activate
Activates the subscription and starts billing.

<sup>Required permissions: `subscription:write`</sup>



# Add comment
Source: https://docs.fynn.eu/api-reference/subscription/add-comment

post /subscriptions/{id}/comment
Add comment

<sup>Required permissions: `subscription:write`</sup>



# Cancel subscription
Source: https://docs.fynn.eu/api-reference/subscription/cancel-subscription

put /subscriptions/{id}/cancel
Cancel the subscription. This will stop billing and the subscription will be inactive after the cancellation date.

<sup>Required permissions: `subscription:write`</sup>



# Create subscription
Source: https://docs.fynn.eu/api-reference/subscription/create-subscription

post /subscriptions
Create a new subscription.

<sup>Required permissions: `subscription:write`</sup>



# Create subscription from plan
Source: https://docs.fynn.eu/api-reference/subscription/create-subscription-from-plan

post /subscriptions/from-plan
Create a new subscription.

<sup>Required permissions: `subscription:write`</sup>



# Delete subscription
Source: https://docs.fynn.eu/api-reference/subscription/delete-subscription

delete /subscriptions/{id}
Delete a subscription. This is only possible if the subscription is in draft mode.

<sup>Required permissions: `subscription:write`</sup>



# Extend trial
Source: https://docs.fynn.eu/api-reference/subscription/extend-trial

put /subscriptions/{id}/extend-trial
Extends the trial period of the subscription.

<sup>Required permissions: `subscription:write`</sup>



# Get all subscriptions
Source: https://docs.fynn.eu/api-reference/subscription/get-all-subscriptions

get /subscriptions
Get all subscriptions as a list.

<sup>Required permissions: `subscription:read`</sup>



# Get estimated amount
Source: https://docs.fynn.eu/api-reference/subscription/get-estimated-amount

get /subscriptions/{id}/estimated-amount
Get the estimated amount of the subscription.

<sup>Required permissions: `subscription:read`</sup>



# Get estimated invoice
Source: https://docs.fynn.eu/api-reference/subscription/get-estimated-invoice

get /subscriptions/{id}/estimated-invoice
Get a preview of the estimated invoice of the subscription.

<sup>Required permissions: `subscription:read`</sup>



# Get subscription
Source: https://docs.fynn.eu/api-reference/subscription/get-subscription

get /subscriptions/{id}
Get detailed information about a subscription.

<sup>Required permissions: `subscription:read`</sup>



# Order products
Source: https://docs.fynn.eu/api-reference/subscription/order-products

post /subscriptions/{id}/products
Order products for the subscription.

<sup>Required permissions: `subscription:write`</sup>



# Pause subscription
Source: https://docs.fynn.eu/api-reference/subscription/pause-subscription

put /subscriptions/{id}/pause
Pause the subscription. This will stop billing and the subscription will be inactive.

<sup>Required permissions: `subscription:write`</sup>



# Resume subscription
Source: https://docs.fynn.eu/api-reference/subscription/resume-subscription

put /subscriptions/{id}/resume
Resume the subscription. This will start billing again.

<sup>Required permissions: `subscription:write`</sup>



# Revoke trial
Source: https://docs.fynn.eu/api-reference/subscription/revoke-trial

put /subscriptions/{id}/revoke-trial
Revoke the trial period of the subscription and start billing immediately, as it would without a trial.

<sup>Required permissions: `subscription:write`</sup>



# Subscription Transition
Source: https://docs.fynn.eu/api-reference/subscription/transition

Transition a subscription to new products and price plans.

Wechsle Produkte und Preispläne in einem bestehenden Abonnement mit automatischer Proration und Gutschriften.

<Warning>
  Gekündigte Abonnements können nicht mehr transitioniert werden.
</Warning>

## POST /api/subscriptions/\[subscriptionId]/transition

Führt einen Übergang zu neuen Produkten/Preisplänen durch.

### Request

```bash theme={null}
curl -X POST "https://coreapi.io/api/subscriptions/550e8400-e29b-41d4-a716-446655440000/transition" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "effectiveAt": "2026-02-15T00:00:00Z",
    "desiredItems": [
      {
        "productId": "prod-premium-plan",
        "pricePlanId": "price-100-monthly",
        "quantity": 1
      }
    ],
    "proration": "creditProrated",
    "invoiceTiming": "phaseStart"
  }'
```

### Request Body

<ParamField type="string">
  Zeitpunkt des Übergangs im ISO 8601 Format. Muss in der Zukunft oder jetzt sein. Ab diesem Zeitpunkt gelten die neuen Items.
</ParamField>

<ParamField type="array">
  Liste der gewünschten Items nach dem Übergang. Mindestens 1 Item erforderlich.

  <Expandable title="Item-Objekt">
    <ParamField type="string">
      UUID des Produkts
    </ParamField>

    <ParamField type="string">
      UUID des Preisplans
    </ParamField>

    <ParamField type="number">
      Menge (muss positiv sein). Für nutzungsbasierte Produkte ist dieser Wert immer `1` - die tatsächliche Menge wird durch Nutzungsereignisse bestimmt.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  Wie sollen Gutschriften für nicht genutzte Zeit berechnet werden?

  | Wert             | Beschreibung                                           |
  | ---------------- | ------------------------------------------------------ |
  | `creditProrated` | Anteilige Gutschrift basierend auf verbleibenden Tagen |
  | `none`           | Keine Gutschrift                                       |

  <Note>
    Die Gutschrift wird sofort finalisiert und an den Kunden gesendet. Der Guthabenbetrag wird automatisch mit der nächsten Rechnung verrechnet.
  </Note>
</ParamField>

<ParamField type="string">
  Wann sollen die neuen Items abgerechnet werden?

  | Wert          | Beschreibung                                                                                                                                              |
  | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `phaseStart`  | Rechnung wird zum Übergangszeitpunkt (`effectiveAt`) erstellt. Teilperioden von nutzungsbasierten Items werden ebenfalls zu diesem Zeitpunkt abgerechnet. |
  | `immediately` | Rechnung wird sofort erstellt mit Leistungsdatum ab `effectiveAt`. Teilperioden von nutzungsbasierten Items werden ebenfalls sofort abgerechnet.          |
</ParamField>

<ParamField type="string">
  Optionaler Grund für die Beendigung der alten Items (max. 255 Zeichen)
</ParamField>

<ParamField type="boolean">
  Wenn `true`, wird eine Vorschau der Änderungen zurückgegeben ohne sie zu speichern
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "previousPhase": {
    "phaseId": "phase-old-123",
    "status": "Completed",
    "startAt": "2026-01-01T00:00:00Z",
    "endAt": "2026-02-15T00:00:00Z",
    "items": [...]
  },
  "newPhase": {
    "phaseId": "phase-new-456",
    "status": "Active",
    "startAt": "2026-02-15T00:00:00Z",
    "endAt": null,
    "items": [...]
  },
  "changes": {
    "itemsRemoved": [
      {
        "subscriptionItemId": "item-old-789",
        "productId": "prod-basic-plan",
        "productName": "Basic Plan",
        "cancelReason": "Upgraded to Premium"
      }
    ],
    "itemsAdded": [
      {
        "subscriptionItemId": "item-new-101",
        "productId": "prod-premium-plan",
        "productName": "Premium Plan",
        "quantity": 1
      }
    ]
  },
  "creditNoteId": "cn-abc-123"
}
```

<ResponseField name="previousPhase" type="object">
  Die abgeschlossene Phase mit den alten Items
</ResponseField>

<ResponseField name="newPhase" type="object">
  Die neue aktive Phase mit den neuen Items
</ResponseField>

<ResponseField name="changes" type="object">
  Übersicht der entfernten und hinzugefügten Items
</ResponseField>

<ResponseField name="creditNoteId" type="string">
  ID der erstellten Gutschrift (falls vorhanden, nur bei Festpreis-Produkten)
</ResponseField>

***

## Beispiele

### Upgrade mit anteiliger Gutschrift

```json theme={null}
{
  "effectiveAt": "2026-02-01T00:00:00Z",
  "desiredItems": [
    {
      "productId": "prod-pro-plan",
      "pricePlanId": "price-pro-monthly",
      "quantity": 1
    }
  ],
  "proration": "creditProrated",
  "invoiceTiming": "phaseStart"
}
```

### Sofortige Abrechnung

```json theme={null}
{
  "effectiveAt": "2026-02-15T12:00:00Z",
  "desiredItems": [
    {
      "productId": "prod-enterprise",
      "pricePlanId": "price-enterprise-yearly",
      "quantity": 1
    }
  ],
  "proration": "creditProrated",
  "invoiceTiming": "immediately"
}
```

### Vorschau (Dry-Run)

```json theme={null}
{
  "effectiveAt": "2026-02-01T00:00:00Z",
  "desiredItems": [...],
  "proration": "creditProrated",
  "dryRun": true
}
```

***

## Fehler-Codes

| HTTP Status | Code                     | Beschreibung                     |
| ----------- | ------------------------ | -------------------------------- |
| 400         | `VALIDATION_ERROR`       | Ungültige Eingabedaten           |
| 404         | `SUBSCRIPTION_NOT_FOUND` | Abonnement nicht gefunden        |
| 422         | `SUBSCRIPTION_CANCELLED` | Abonnement ist bereits gekündigt |
| 422         | `CURRENCY_MISMATCH`      | Unterschiedliche Währungen       |
| 422         | `PRICE_PLAN_ARCHIVED`    | Preisplan ist archiviert         |

***

## Verwandte Dokumentation

* [Abonnement-Übergänge (Guide)](/guide/subscriptions/transitions) - Konzepte und Anwendungsfälle


# Update invoice address
Source: https://docs.fynn.eu/api-reference/subscription/update-invoice-address

put /subscriptions/{id}/invoice-address
Update the invoice address of the subscription.

<sup>Required permissions: `subscription:write`</sup>



# Update payment method
Source: https://docs.fynn.eu/api-reference/subscription/update-payment-method

put /subscriptions/{id}/payment-method
Update the payment method of the subscription.

<sup>Required permissions: `subscription:write`</sup>



# Update subscription
Source: https://docs.fynn.eu/api-reference/subscription/update-subscription

put /subscriptions/{id}
Update a subscription.

<sup>Required permissions: `subscription:write`</sup>



# Get a subscription item.
Source: https://docs.fynn.eu/api-reference/subscriptionitem/get-a-subscription-item

get /subscription-items/{id}
Get a subscription item.



# Get a subscription item applied discount.
Source: https://docs.fynn.eu/api-reference/subscriptionitem/get-a-subscription-item-applied-discount

get /subscription-item-applied-discounts/{id}
Retrieves a SubscriptionItemAppliedDiscount resource.



# Get estimated amount
Source: https://docs.fynn.eu/api-reference/subscriptionitem/get-estimated-amount

get /subscription-items/{id}/estimated-amount
Get the estimated amount of the subscription item.

<sup>Required permissions: `subscription:read`</sup>



# Remove a subscription item.
Source: https://docs.fynn.eu/api-reference/subscriptionitem/remove-a-subscription-item

delete /subscription-items/{id}
Removes a subscription item. This is only possible, if the subscription item is not billed yet.

<sup>Required permissions: `subscription:write`</sup>



# Update a subscription item.
Source: https://docs.fynn.eu/api-reference/subscriptionitem/update-a-subscription-item

patch /subscription-items/{id}
Updates the subscription item. Provided values in payload will be updated.

<sup>Required permissions: `subscription:write`</sup>



# Deactivate account
Source: https://docs.fynn.eu/api-reference/account/deactivate-account

put /accounts/{id}/deactivate
Deactivates an account. The account will not have any access to the tenant anymore. You cannot deactivate your own account.

<sup>Required permissions: `account:deactivate`</sup>



# Get all accounts of the current tenant.
Source: https://docs.fynn.eu/api-reference/account/get-all-accounts-of-the-current-tenant

get /tenant/accounts
Retrieves the collection of Account resources.



# Reactivate account
Source: https://docs.fynn.eu/api-reference/account/reactivate-account

put /accounts/{id}/reactivate
Reactivates an account. The account will have access again to their tenant.

<sup>Required permissions: `account:reactivate`</sup>



# Update account role
Source: https://docs.fynn.eu/api-reference/account/update-account-role

put /accounts/{id}/role
Update the role of an account. The changes will apply immediately after the next page navigation of the user. You cannot change the role of your own account.

<sup>Required permissions: `account:role:write`</sup>



# Get accounts
Source: https://docs.fynn.eu/api-reference/accounting/get-accounts

get /accounting/accounts
Get accounts for postings.

<sup>Required permissions: `accounting:accounts:read`</sup>



# Get postings
Source: https://docs.fynn.eu/api-reference/accounting/get-postings

get /accounting/postings
Get postings created for invoices, payments, invoice cancellations.

<sup>Required permissions: `accounting:accounts:read`</sup>



# Update account
Source: https://docs.fynn.eu/api-reference/accounting/update-account

put /accounting/accounts/{id}
Updates account name and number. Adapt the account number to your chart of accounts.

<sup>Required permissions: `accounting:accounts:write`</sup>



# Get series data
Source: https://docs.fynn.eu/api-reference/analytics/get-series-data

get /analytics/series/{type}
Get series data for analytics. Supported types are: customer, offer, subscription, revenue, signed-offer, open-offer.

<sup>Required permissions: `analytics:read`</sup>



# Get series data for subscription
Source: https://docs.fynn.eu/api-reference/analytics/get-series-data-for-subscription

get /analytics/subscription-revenue
Get series data for subscription analytics, including MRR, new-MRR, expansion-MRR, churn-MRR. The result has one data-point for each currency and date combination. The data-point contains the MRR, new-MRR, expansion-MRR, and churn-MRR for the given currency and date.

<sup>Required permissions: `analytics:read`</sup>



# Changes the quantity of a cart item.
Source: https://docs.fynn.eu/api-reference/cart/changes-the-quantity-of-a-cart-item

put /public/checkout/cart/{id}/change-quantity
Changes the quantity of a cart item.



# Confirms a cart.
Source: https://docs.fynn.eu/api-reference/cart/confirms-a-cart

put /public/checkout/cart/{id}/confirm
Confirms a cart.



# Confirms the OTP of a cart.
Source: https://docs.fynn.eu/api-reference/cart/confirms-the-otp-of-a-cart

put /public/checkout/cart/{id}/confirm-otp
Confirms the OTP of a cart to authenticate the customer.



# Prepares a cart for stripe.
Source: https://docs.fynn.eu/api-reference/cart/prepares-a-cart-for-stripe

put /public/checkout/cart/{id}/prepare-stripe
Prepares a cart for stripe.



# Retrieves a cart by its ID.
Source: https://docs.fynn.eu/api-reference/cart/retrieves-a-cart-by-its-id

get /checkout/carts/{id}
Retrieves a cart by its ID.

<sup>Required permissions: `cart:read`</sup>



# Retrieves a cart by its ID.
Source: https://docs.fynn.eu/api-reference/cart/retrieves-a-cart-by-its-id-1

get /public/checkout/cart/{id}
Retrieves a cart by its ID. The cart is only returned if it is not expired.



# Retrieves completed carts of the current tenant.
Source: https://docs.fynn.eu/api-reference/cart/retrieves-completed-carts-of-the-current-tenant

get /checkout/carts
Retrieves completed the carts of the current tenant.

<sup>Required permissions: `cart:read`</sup>



# Retrieves the invoice addresses of a cart.
Source: https://docs.fynn.eu/api-reference/cart/retrieves-the-invoice-addresses-of-a-cart

get /public/checkout/cart/{id}/invoice-addresses
Retrieves the invoice addresses of a cart.



# Retrieves the payment methods of a cart.
Source: https://docs.fynn.eu/api-reference/cart/retrieves-the-payment-methods-of-a-cart

get /public/checkout/cart/{id}/payment-methods
Retrieves the payment methods of a cart.



# Create a cart from a checkout link
Source: https://docs.fynn.eu/api-reference/checkoutlink/create-a-cart-from-a-checkout-link

post /checkout-links/{id}/cart
Create a cart from a checkout link by its ID

<sup>Required permissions: `cart:write`</sup>



# Create a checkout link
Source: https://docs.fynn.eu/api-reference/checkoutlink/create-a-checkout-link

post /checkout-links
Create a link to allow your customers to checkout the given line items.

<sup>Required permissions: `checkout-link:write`</sup>



# Get a checkout link
Source: https://docs.fynn.eu/api-reference/checkoutlink/get-a-checkout-link

get /checkout-links/{id}
Get a checkout link by its ID

<sup>Required permissions: `checkout-link:read`</sup>



# Update a checkout link
Source: https://docs.fynn.eu/api-reference/checkoutlink/update-a-checkout-link

put /checkout-links/{id}
Update a checkout link by its ID

<sup>Required permissions: `checkout-link:write`</sup>



# Get a checkout link item
Source: https://docs.fynn.eu/api-reference/checkoutlinkitem/get-a-checkout-link-item

get /checkout-link-items/{id}
Get a checkout link item by its ID

<sup>Required permissions: `checkout-link:read`</sup>



# Add a cost centre
Source: https://docs.fynn.eu/api-reference/costcentre/add-a-cost-centre

post /accounting/cost-centres
Add a cost centre. A cost centre can be of type KOST1 or KOST2 and must have a unique code.

<sup>Required permissions: `cost-centre:write`</sup>



# Get a cost centre
Source: https://docs.fynn.eu/api-reference/costcentre/get-a-cost-centre

get /accounting/cost-centres/{id}
Get a cost centre

<sup>Required permissions: `cost-centre:read`</sup>



# Get all cost centres
Source: https://docs.fynn.eu/api-reference/costcentre/get-all-cost-centres

get /accounting/cost-centres
Get all cost centres

<sup>Required permissions: `cost-centre:read`</sup>



# Import cost centres
Source: https://docs.fynn.eu/api-reference/costcentre/import-cost-centres

post /accounting/cost-centres/import
Import cost centres by CSV file. The file should contain the follwing headers: name, code, type.
The type can be "KOST1" or "KOST2". Already imported cost centres, identified by code, will be skipped.

<sup>Required permissions: `cost-centre:write`</sup>



# Update a cost centre
Source: https://docs.fynn.eu/api-reference/costcentre/update-a-cost-centre

patch /accounting/cost-centres/{id}
Update a cost centre. A cost centre can be of type KOST1 or KOST2 and must have a unique code.

<sup>Required permissions: `cost-centre:write`</sup>



# Add subscription entitlement
Source: https://docs.fynn.eu/api-reference/entitlement/add-subscription-entitlement

post /subscriptions/{subscriptionId}/entitlements
Creates a Entitlement resource.



# Add subscription item entitlement
Source: https://docs.fynn.eu/api-reference/entitlement/add-subscription-item-entitlement

post /subscription-items/{subscriptionItemId}/entitlements
Creates a Entitlement resource.



# Delete entitlement
Source: https://docs.fynn.eu/api-reference/entitlement/delete-entitlement

delete /entitlements/{id}
Delete an entitlement



# Get available features
Source: https://docs.fynn.eu/api-reference/entitlement/get-available-features

get /subscriptions/{id}/available-features
Get all current available features for a subscription



# Get subscription entitlements
Source: https://docs.fynn.eu/api-reference/entitlement/get-subscription-entitlements

get /subscriptions/{subscriptionId}/entitlements
Get all entitlements of a subscription. By default, expired entitlements are excluded from the response.



# Get subscription item entitlements
Source: https://docs.fynn.eu/api-reference/entitlement/get-subscription-item-entitlements

get /subscription-items/{subscriptionItemId}/entitlements
Get all entitlements of a subscription item. By default, expired entitlements are excluded from the response.



# Update entitlement status
Source: https://docs.fynn.eu/api-reference/entitlement/update-entitlement-status

put /entitlements/{id}/status
Update the status of an entitlement



# Assign feature
Source: https://docs.fynn.eu/api-reference/feature/assign-feature

post /entitlement/feature-assignments
Creates a Feature resource.



# Create feature
Source: https://docs.fynn.eu/api-reference/feature/create-feature

post /entitlement/features
Creates a Feature resource.



# Get feature
Source: https://docs.fynn.eu/api-reference/feature/get-feature

get /entitlement/features/{id}
Retrieves a Feature resource.



# Get feature assignments
Source: https://docs.fynn.eu/api-reference/feature/get-feature-assignments

get /entitlement/feature-assignments
Retrieves the collection of Feature resources.



# Get features
Source: https://docs.fynn.eu/api-reference/feature/get-features

get /entitlement/features
Retrieves the collection of Feature resources.



# Unassign feature
Source: https://docs.fynn.eu/api-reference/feature/unassign-feature

delete /entitlement/feature-assignments/{id}
Unassign a feature. Existing entitlements **will not** be removed from the subscriptions.



# Update feature
Source: https://docs.fynn.eu/api-reference/feature/update-feature

put /entitlement/features/{id}
Replaces the Feature resource.



# Update feature status
Source: https://docs.fynn.eu/api-reference/feature/update-feature-status

put /entitlement/features/{id}/status
Replaces the Feature resource.



# Create download token
Source: https://docs.fynn.eu/api-reference/media/create-download-token

post /media/{id}/download-token
 Create token to download media file by get request and without another authentication.

<sup>Required permissions: `media:read`</sup>



# Download by token
Source: https://docs.fynn.eu/api-reference/media/download-by-token

get /media/{id}/download/{token}
Download a media by download token. **No authentication required**



# Get a media
Source: https://docs.fynn.eu/api-reference/media/get-a-media

get /media/{id}
Get a media by id

<sup>Required permissions: `media:read`</sup>



# Get all medias
Source: https://docs.fynn.eu/api-reference/media/get-all-medias

get /media
Get all medias

<sup>Required permissions: `media:read`</sup>



# Get media folders
Source: https://docs.fynn.eu/api-reference/media/get-media-folders

get /media-folders
Get all media folders

<sup>Required permissions: `media:read`</sup>



# Upload a file
Source: https://docs.fynn.eu/api-reference/media/upload-a-file

post /media
Upload a file

<sup>Required permissions: `media:write`</sup>



# Add a recipient to an offer
Source: https://docs.fynn.eu/api-reference/offer/add-a-recipient-to-an-offer

post /offers/{id}/recipients
Add a recipient to an offer

<sup>Required permissions: `offer:write`</sup>



# [Deprecated, removed 2026-08-01] Get a public offer document
Source: https://docs.fynn.eu/api-reference/offer/get-a-public-offer-document

get /public/offers/{id}/document
Get a single public offer document



# [Deprecated, removed 2026-08-01] Start signing an offer
Source: https://docs.fynn.eu/api-reference/offer/start-signing-an-offer

get /public/offers/{id}/sign
Starts the signing process for a public offer and returns the signing link



# Change the role of an offer recipient
Source: https://docs.fynn.eu/api-reference/offerrecipient/change-the-role-of-an-offer-recipient

put /offer-recipients/{id}/role
Changes the role of an offer recipient. This cannot be done, when the offer is already signed.

<sup>Required permissions: `offer:write`</sup>



# Remove an offer recipient
Source: https://docs.fynn.eu/api-reference/offerrecipient/remove-an-offer-recipient

delete /offer-recipients/{id}
Removes an recipient from an offer. The recipient will no longer be able to access the offer. This cannot be done, when the offer is already signed.

<sup>Required permissions: `offer:write`</sup>



# Create an offer template
Source: https://docs.fynn.eu/api-reference/offertemplate/create-an-offer-template

post /offer-templates
Create a new offer template

<sup>Required permissions: `offer-template:write`</sup>



# Get an offer template
Source: https://docs.fynn.eu/api-reference/offertemplate/get-an-offer-template

get /offer-templates/{id}
Get a single offer template

<sup>Required permissions: `offer-template:read`</sup>



# Get offer templates
Source: https://docs.fynn.eu/api-reference/offertemplate/get-offer-templates

get /offer-templates
Get a list of offer templates

<sup>Required permissions: `offer-template:read`</sup>



# Update an offer template
Source: https://docs.fynn.eu/api-reference/offertemplate/update-an-offer-template

put /offer-templates/{id}
Update an existing offer template

<sup>Required permissions: `offer-template:write`</sup>



# Get a notification
Source: https://docs.fynn.eu/api-reference/sentnotification/get-a-notification

get /notifications/{id}
Get a notification by id



# Get notifications
Source: https://docs.fynn.eu/api-reference/sentnotification/get-notifications

get /notifications
Get all sent notifications



# Get settings
Source: https://docs.fynn.eu/api-reference/settings/get-settings

get /settings/{context}
Get all settings of the context

<sup>Required permissions: `settings:read`</sup>



# Update settings key
Source: https://docs.fynn.eu/api-reference/settings/update-settings-key

patch /settings/{context}
Update given setting key of the context.

<sup>Required permissions: `settings:write`</sup>



# Get tax group
Source: https://docs.fynn.eu/api-reference/tax/get-tax-group

get /tax-groups/{id}
Get a tax group

<sup>Required permissions: `tax-group:read`</sup>



# Get tax groups
Source: https://docs.fynn.eu/api-reference/tax/get-tax-groups

get /tax-groups
Get all tax groups

<sup>Required permissions: `tax-group:read`</sup>



# Add webhook
Source: https://docs.fynn.eu/api-reference/webhook/add-webhook

post /webhooks
Add webhook

<sup>Required permissions: `webhook:write`</sup>



# Delete webhook
Source: https://docs.fynn.eu/api-reference/webhook/delete-webhook

delete /webhooks/{id}
Delete webhook and all related webhook results

<sup>Required permissions: `webhook:write`</sup>



# Get available webhook events
Source: https://docs.fynn.eu/api-reference/webhook/get-available-webhook-events

get /available-webhook-events
Get available webhook events

<sup>Required permissions: `webhook:read`</sup>



# Get webhook
Source: https://docs.fynn.eu/api-reference/webhook/get-webhook

get /webhooks/{id}
Get webhook

<sup>Required permissions: `webhook:read`</sup>



# Get webhook result
Source: https://docs.fynn.eu/api-reference/webhook/get-webhook-result

get /webhook-results/{id}
Get webhook result

<sup>Required permissions: `webhook:read`</sup>



# Get webhook results
Source: https://docs.fynn.eu/api-reference/webhook/get-webhook-results

get /webhook-results
Get webhook results

<sup>Required permissions: `webhook:read`</sup>



# Get webhooks
Source: https://docs.fynn.eu/api-reference/webhook/get-webhooks

get /webhooks
Get webhooks

<sup>Required permissions: `webhook:read`</sup>



# Update webhook
Source: https://docs.fynn.eu/api-reference/webhook/update-webhook

patch /webhooks/{id}
Update webhook

<sup>Required permissions: `webhook:write`</sup>



# Annahme und Signatur
Source: https://docs.fynn.eu/v2-offers-api/acceptance-and-signing

Klick-Annahme, elektronische Signatur und manuelle Annahme, dazu die Sperre nach der Zusage.

Du legst je Angebot fest, wie der Empfänger zusagt. Den Modus wählst du im Editor in der Seitenleiste. Diese Seite beschreibt die drei Wege und was nach der Annahme passiert.

```mermaid theme={null}
flowchart TD
  Start[Empfänger öffnet das Angebot] --> Mode{Annahme-Modus}
  Mode -->|Klick| Klick[Name eingeben und verbindlich bestätigen]
  Mode -->|Signatur| Sign[Bedingungen bestätigen und unterschreiben]
  Mode -->|Drucken| Print[PDF herunterladen, unterschreiben, hochladen]
  Klick --> Done[Angebot angenommen]
  Sign --> Multi{Alle unterschrieben}
  Multi -->|nein| Wait[Wird signiert]
  Multi -->|ja| Done
  Print --> Done
  Done --> Lock[Angebot gesperrt, Abonnement entsteht]
```

## Klick-Annahme

Der schnellste Weg. Der Empfänger gibt seinen **Vor- und Nachnamen** ein, bestätigt mit einem Häkchen, dass er das Angebot verbindlich annimmt, und klickt auf **Verbindlich annehmen**. Zeitpunkt und technische Angaben der Annahme werden festgehalten.

## Elektronische Signatur

Für eine rechtssichere Unterschrift. Der Empfänger wählt die Unterzeichner aus, kann Kolleginnen und Kollegen hinzufügen und startet den Signaturvorgang.

<Steps>
  <Step title="Unterzeichner wählen">
    Der Empfänger bestimmt, wer unterschreibt, und kann eine kurze Nachricht mitgeben.
  </Step>

  <Step title="Bedingungen bestätigen">
    Vor der Unterschrift bestätigt der Empfänger, dass er die Nutzungsbedingungen und die Datenschutzhinweise gelesen hat. Erst dann gibt das Dokument die Unterschrift frei.
  </Step>

  <Step title="Unterschreiben">
    Der Empfänger unterschreibt online. Solange noch Unterschriften fehlen, steht das Angebot auf **Wird signiert**.
  </Step>

  <Step title="Abschluss">
    Haben alle unterschrieben, ist das Angebot abgeschlossen. Der Empfänger kann das signierte Dokument samt Abschlusszertifikat herunterladen.
  </Step>
</Steps>

<Info>
  Du kannst in den [Einstellungen](/v2-offers-api/settings) einen festen Gegenzeichner aus deiner Organisation aktivieren, der jedes Angebot mit unterschreibt.
</Info>

## Drucken und hochladen

Wenn eine Unterschrift auf Papier nötig ist. Der Empfänger lädt das Angebot als PDF herunter, unterschreibt es und lädt das unterschriebene Dokument wieder hoch.

## Manuelle Annahme

Schließt du den Abschluss außerhalb der Angebots-Ansicht ab, etwa telefonisch, markierst du das Angebot in der App selbst als angenommen. Du gibst das **Datum der Annahme** an, das nicht vor dem Erstelldatum liegen darf, und kannst ein vom Kunden unterschriebenes PDF hochladen.

## Sperre nach der Annahme

Sobald ein Angebot angenommen ist, ist es schreibgeschützt. Titel, Inhalt, Variablen, Gültigkeit und Annahme-Modus lassen sich nicht mehr ändern, und es kann nicht erneut veröffentlicht werden. So bleibt genau das verbindlich, was der Empfänger angenommen hat. Möchtest du während eines laufenden Signaturvorgangs noch etwas ändern, brichst du den Vorgang zuerst ab.

## Ablehnen

Ist das Ablehnen in den [Einstellungen](/v2-offers-api/settings) erlaubt, kann der Empfänger das Angebot statt einer Annahme auch ablehnen.


# Die Angebots-Ansicht
Source: https://docs.fynn.eu/v2-offers-api/angebots-ansicht

Die Ansicht, die dein Empfänger über seinen Link öffnet, und ihre Vorteile gegenüber einem PDF.

Die Angebots-Ansicht ist die Seite, die dein Empfänger über seinen persönlichen Link öffnet. Sie zeigt dein Angebot in deinem Erscheinungsbild, ganz ohne Anmeldung. Der Empfänger liest das Dokument, prüft die Konditionen und nimmt direkt an.

<Frame>
  <img alt="Empfängeransicht mit Angebotsdokument und Zusammenfassung" />
</Frame>

## Was der Empfänger sieht

* **Dein Erscheinungsbild**: Logo und Farbe stammen aus deinem Vertriebskanal. Das Angebot wirkt wie ein Teil deines Produkts, nicht wie ein angehängtes Dokument.
* **Das Angebotsdokument**: Überschriften, Texte, Tabellen, Bilder und Anhänge, dazu der Preis-Block mit den enthaltenen Leistungen.
* **Die Zusammenfassung am Rand**: die enthaltenen Leistungen, dazu **Vertragsbeginn**, **Laufzeit** und **Gültig bis**. Diese Leiste bleibt beim Scrollen sichtbar.
* **Der Status**: ein Hinweis zeigt, ob das Angebot offen ist, gerade signiert wird, angenommen wurde oder abgelaufen ist.

Auf dem Smartphone rückt die Zusammenfassung über das Dokument, alles bleibt gut lesbar.

## Annehmen

Über **Angebot annehmen** öffnet sich der für das Angebot freigegebene Weg: per Klick, mit elektronischer Signatur oder durch Drucken und Hochladen. Den genauen Ablauf beschreibt [Annahme und Signatur](/v2-offers-api/acceptance-and-signing).

Nach der Annahme erscheint eine Bestätigung, der Status wechselt, und das Angebot ist gegen weitere Änderungen gesperrt. Ist alles unterschrieben, kann der Empfänger das **signierte Dokument samt Abschlusszertifikat** herunterladen.

## Rechnungsdaten

Der Empfänger ergänzt oder bestätigt seine Rechnungsdaten direkt in der Ansicht: Rechnungsempfänger, Adresse, USt-IdNr. und optional Bestellnummer und Kostenstelle. Hat er bereits eine bekannte Adresse, bestätigt er sie mit einem Klick. Mehr dazu unter [Rechnungsdaten](/v2-offers-api/billing-details).

## Weiterleiten

Über **Weiterleiten** schickt der Empfänger das Angebot an eine weitere Person, etwa an die Buchhaltung oder die Geschäftsführung. Diese Person bekommt ihre eigene Einladung per E-Mail und einen eigenen Zugang.

## Als PDF speichern

Das Angebot lässt sich jederzeit als PDF herunterladen. Es enthält dieselben Inhalte und dasselbe Erscheinungsbild wie die Online-Ansicht, mit Briefkopf und Seitenzahlen. Nach der Unterschrift kommt das Abschlusszertifikat dazu.

## Abgelaufene Angebote

Ist die Gültigkeit verstrichen, zeigt die Ansicht einen deutlichen Hinweis, und das Annehmen ist nicht mehr möglich. Ein bereits angenommenes Angebot bleibt davon unberührt.

## Vorteile gegenüber einem PDF

<CardGroup>
  <Card title="Dein Erscheinungsbild" icon="palette">
    Logo, Farbe und ein persönlicher Link, statt eines anonymen Anhangs.
  </Card>

  <Card title="Kein Login nötig" icon="link">
    Der Empfänger öffnet das Angebot sofort. Jede weitergeleitete Person bekommt ihren eigenen Zugang.
  </Card>

  <Card title="Rechtssichere Signatur" icon="file-signature">
    Elektronische Signatur mit Bestätigung der Bedingungen, Zeitstempel und Abschlusszertifikat.
  </Card>

  <Card title="Rechnungsdaten ohne Umweg" icon="receipt">
    Der Empfänger erfasst Rechnungsempfänger und Adresse selbst, ohne Hin und Her per E-Mail.
  </Card>

  <Card title="Status in Echtzeit" icon="signal">
    Du siehst, ob das Angebot offen ist, signiert wird oder angenommen wurde.
  </Card>

  <Card title="Immer aktuell und mobil" icon="mobile">
    Die Ansicht zeigt stets den neuesten Stand und funktioniert auf jedem Gerät.
  </Card>
</CardGroup>


# Rechnungsdaten
Source: https://docs.fynn.eu/v2-offers-api/billing-details

Welche Rechnungsdaten Empfänger ergänzen oder bestätigen und wie sie in die Abrechnung einfließen.

Damit aus einem angenommenen Angebot eine korrekte Rechnung entsteht, braucht es einen Rechnungsempfänger mit Adresse. Diese Daten erfasst entweder der Empfänger selbst in der Angebots-Ansicht oder du in der App.

<Info>
  Die Rechnungsdaten erscheinen auf allen Rechnungen zum entstehenden Abonnement. Der Empfänger kann sie später jederzeit im Kundenportal ändern.
</Info>

## Rechnungsempfänger

Der Rechnungsempfänger ist entweder ein Unternehmen oder eine Privatperson:

* **Unternehmen**: ein **Firmenname** ist erforderlich, ein Ansprechpartner ist optional.
* **Privat**: **Vorname** und **Nachname** sind erforderlich.

Es muss mindestens eine Firma oder ein vollständiger Name angegeben sein.

## Adresse und Angaben

| Feld               | Pflicht | Beschreibung                                                       |
| ------------------ | ------- | ------------------------------------------------------------------ |
| Straße, Hausnummer | ja      | Die Rechnungsadresse.                                              |
| Adresszusatz       | nein    | Zusätzliche Angabe zur Adresse.                                    |
| PLZ, Stadt, Land   | ja      | Postleitzahl, Ort und Land.                                        |
| Rechnungs-E-Mail   | ja      | An diese Adresse werden alle Rechnungen gesendet.                  |
| USt-IdNr.          | nein    | Umsatzsteuer-Identifikationsnummer.                                |
| Bestellnummer      | nein    | Eine Bestell- oder PO-Nummer, optional mit hochgeladenem Dokument. |
| Kostenstelle       | nein    | Interne Kostenstelle des Empfängers.                               |
| Leitweg-ID         | nein    | Für die elektronische Rechnung an öffentliche Auftraggeber.        |

<Note>
  Für Empfänger im Drittland ist keine USt-IdNr. nötig. In diesem Fall wird ohne deutsche Umsatzsteuer abgerechnet.
</Note>

## Bestehende Adresse bestätigen

Hast du dem Angebot einen bekannten Kunden mit hinterlegter Adresse zugeordnet, sieht der Empfänger diese Adresse zunächst nur zur Prüfung. Mit **Bestätigen** übernimmt er genau diese Adresse, mit **Bearbeiten** passt er sie an. So entsteht keine doppelte Adresse.

## Wer zuerst speichert

Sind die Rechnungsdaten einmal erfasst, sind sie verbindlich. Ein weiterer Empfänger sieht sie dann nur noch zur Ansicht und kann sie nicht erneut ändern.

## In der App erfassen

Du kannst die Rechnungsdaten auch selbst in der App hinterlegen, mit demselben Aufbau aus Rechnungsempfänger, Adresse und den optionalen Angaben. Auf Wunsch werden die Kundenstammdaten mit diesen Angaben aktualisiert.


# Kernkonzepte
Source: https://docs.fynn.eu/v2-offers-api/concepts

Angebot, Status, Dokument-Blöcke, Empfänger und die Annahme-Optionen im Überblick.

Ein Angebot ist ein gestaltetes Dokument mit einer Gültigkeit, das du an eine oder mehrere Personen sendest. Diese Seite erklärt die Begriffe, die im Editor und in der Empfängeransicht immer wieder auftauchen.

## Das Angebot

| Merkmal        | Beschreibung                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------- |
| Angebotsnummer | Fortlaufende Nummer, die jedes Angebot eindeutig kennzeichnet.                                |
| Titel          | Anzeigename des Angebots.                                                                     |
| Status         | Wo das Angebot im Ablauf steht, von offen bis abgeschlossen.                                  |
| Gültig bis     | Datum, bis zu dem der Empfänger annehmen kann.                                                |
| Kunde          | Die verknüpfte Organisation oder Person. Du kannst sie auch erst nach der Annahme verknüpfen. |

## Status-Lebenszyklus

Ein Angebot durchläuft mehrere Stationen. Den aktuellen Status erkennst du in der Liste und in der Empfängeransicht an einem farbigen Hinweis.

```mermaid theme={null}
flowchart LR
  Entwurf -->|veröffentlichen| Offen
  Offen -->|Klick-Annahme| Angenommen
  Offen -->|elektronische Signatur| Signatur[Wird signiert]
  Signatur -->|alle haben unterschrieben| Angenommen
  Offen -->|Gültigkeit überschritten| Abgelaufen
  Angenommen -->|Rechnungsdaten offen| Rechnung[Rechnungsdaten ausstehend]
  Rechnung --> Abgeschlossen
  Angenommen --> Abgeschlossen
```

| Status                    | Bedeutung                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| Entwurf                   | In Bearbeitung, noch nicht gesendet.                                                     |
| Offen                     | Veröffentlicht und für die Empfänger sichtbar, wartet auf eine Entscheidung.             |
| Wird signiert             | Angenommen, es fehlen noch elektronische Unterschriften.                                 |
| Rechnungsdaten ausstehend | Angenommen, der Empfänger ergänzt noch seine Rechnungsdaten.                             |
| Abgeschlossen             | Vollständig angenommen und unterschrieben.                                               |
| Abgelaufen                | Die Gültigkeit ist verstrichen, bevor angenommen wurde. Annehmen ist nicht mehr möglich. |
| Archiviert                | Abgelegt und schreibgeschützt.                                                           |

<Note>
  Ein bereits angenommenes oder archiviertes Angebot läuft nie ab. Der Status `Abgelaufen` entsteht nur, wenn die Gültigkeit verstreicht, solange das Angebot noch offen ist.
</Note>

## Das Dokument und seine Blöcke

Den Inhalt baust du aus Blöcken zusammen. Jeder Block hat eine klare Aufgabe:

| Block                                               | Aufgabe                                                                                   |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Briefkopf                                           | Logo und Kopfzeile mit Angebotsnummer, Datum und Gültigkeit.                              |
| Parteien                                            | Anbieter, Kunde und Rechnungsempfänger. Pflicht, genau einmal pro Dokument.               |
| Abonnement                                          | Die Positionen mit Produkten, Mengen, Preisen und Rabatten.                               |
| Text, Überschriften, Listen, Tabelle, Bild, Anhänge | Frei gestaltbarer Inhalt rund um das Angebot.                                             |
| Unterschrift                                        | Der Bereich, in dem Anbieter und Kunde die Annahme bestätigen.                            |
| Variable                                            | Ein Platzhalter, der beim Anzeigen automatisch ersetzt wird, zum Beispiel der Kundenname. |

<Info>
  Der Parteien-Block ist Pflicht und lässt sich nicht löschen. So ist in jedem Angebot klar geregelt, wer anbietet, wer kauft und an wen die Rechnung geht.
</Info>

## Empfänger und Rollen

Jede eingeladene Person bekommt einen eigenen, persönlichen Link. Es gibt zwei Rollen:

| Rolle         | Was die Person kann                                   |
| ------------- | ----------------------------------------------------- |
| Unterzeichner | Das Angebot ansehen und annehmen oder unterschreiben. |
| Beobachter    | Das Angebot ansehen, aber nicht annehmen.             |

Ein Empfänger kann das Angebot zusätzlich an eine weitere Person weiterleiten. Diese erhält dann ihren eigenen Zugang.

## Annahme-Optionen

Du legst je Angebot fest, wie der Empfänger zusagt:

<CardGroup>
  <Card title="Klick" icon="hand-pointer">
    Der Empfänger bestätigt mit Namen und einem verbindlichen Klick.
  </Card>

  <Card title="Elektronische Signatur" icon="signature">
    Der Empfänger unterschreibt rechtssicher online, mehrere Unterzeichner sind möglich.
  </Card>

  <Card title="Drucken" icon="print">
    Der Empfänger druckt das Angebot, unterschreibt es und lädt das unterschriebene PDF hoch.
  </Card>
</CardGroup>

Die Details zu jeder Option findest du unter [Annahme und Signatur](/v2-offers-api/acceptance-and-signing).


# Der Angebots-Editor
Source: https://docs.fynn.eu/v2-offers-api/editor

Wie du ein Angebot zusammenstellst, Preise hinterlegst, Variablen nutzt und Vorlagen anlegst.

Im Angebots-Editor stellst du dein Angebot als gestaltetes Dokument zusammen. Du arbeitest direkt im fertigen Layout, fügst Blöcke hinzu und siehst sofort, wie das Angebot beim Empfänger aussieht. Deine Änderungen werden laufend automatisch gespeichert, der Speicherstand steht oben am Rand.

Mit **Bearbeiten** und **Vorschau** wechselst du zwischen dem Bearbeitungsmodus und der echten Empfängeransicht.

## Ein Angebot anlegen

Du startest ein Angebot auf mehreren Wegen:

* Über **Neues Angebot** in der Angebotsliste. Einen Kunden kannst du gleich verknüpfen oder später ergänzen.
* Aus einem Kunden heraus, dann ist der Kunde bereits vorausgewählt.
* Aus einem bestehenden Abonnement, zum Beispiel für eine Erweiterung oder Verlängerung.

<Frame>
  <img alt="Formular zum Anlegen eines Angebots mit optionalem Kunden" />
</Frame>

### Kunde verknüpfen

Im Parteien-Block verknüpfst du über **Kunde verknüpfen** eine bestehende Organisation. Die Daten für Kunde und Rechnungsempfänger werden dann aus den hinterlegten Adressen vorausgefüllt. Löst du die Verknüpfung wieder, bleiben die eingetragenen Felder erhalten.

## Blöcke

Den Inhalt baust du aus Blöcken. Du fügst sie über das Pluszeichen oder den Schrägstrich ein und ordnest sie per Ziehgriff neu an.

| Block                                            | Wofür                                                                             |
| ------------------------------------------------ | --------------------------------------------------------------------------------- |
| Briefkopf                                        | Logo und Kopfzeile mit Angebotsnummer, Datum und Gültigkeit. Einmal pro Dokument. |
| Parteien                                         | Anbieter, Kunde und Rechnungsempfänger. Pflicht und nicht löschbar.               |
| Abonnement                                       | Die Positionen mit Produkten, Mengen, Preisen und Rabatten.                       |
| Überschrift, Text, Aufzählung, Nummerierte Liste | Gliederung und Fließtext.                                                         |
| Tabelle, Bild, Anhänge                           | Zusätzlicher Inhalt und Dateien zum Download.                                     |
| Unterschrift                                     | Der Annahmebereich für Anbieter und Kunde. Einmal pro Dokument.                   |
| Seitenumbruch                                    | Erzwingt im PDF eine neue Seite.                                                  |
| Variable                                         | Ein Platzhalter, der beim Anzeigen ersetzt wird.                                  |

Über das Menü an jedem Block verschiebst du ihn, speicherst ihn in deiner Bibliothek oder löschst ihn. Bei Pflichtblöcken ist das Löschen ausgeblendet.

## Preise

Im **Abonnement**-Block fügst du die Positionen hinzu. Wiederkehrende und einmalige Posten erscheinen in getrennten Tabellen:

* Je Position siehst du **Beschreibung**, **Menge**, **Einzelpreis** und **Summe**.
* Ein **Rabatt** wird unter der Position ausgewiesen, der ursprüngliche Preis erscheint durchgestrichen.
* Unter den Tabellen stehen **Wiederkehrend gesamt** und **Einmalig gesamt**.

Zusätzlich werden Vertragsdaten wie **Laufzeit**, **Kündigungsfrist** und **Vertragsbeginn** angezeigt.

<Frame>
  <img alt="Preis-Block mit getrennten Tabellen für wiederkehrende und einmalige Posten" />
</Frame>

## Variablen

Variablen sind Platzhalter, die beim Anzeigen des Angebots automatisch ersetzt werden. Du fügst sie über `{{` oder den Schrägstrich ein und verwaltest sie in der Seitenleiste unter **Variablen**.

Diese Variablen stehen bereit:

| Variable           | Wird ersetzt durch                             |
| ------------------ | ---------------------------------------------- |
| Angebots-Nr.       | Die Nummer des Angebots.                       |
| Erstellt           | Das Erstelldatum.                              |
| Gültig bis         | Das Ablaufdatum.                               |
| Kunde              | Name der verknüpften Organisation oder Person. |
| Unternehmen        | Name deiner Organisation.                      |
| Vertragsbeginn     | Der Beginn der Laufzeit.                       |
| PO-Nummer, Währung | Bestellnummer und Währung des Angebots.        |

Eigene Platzhalter legst du als **Eigene Variablen** an und füllst ihre Werte.

## Parteien und Rechnungsempfänger

Der Parteien-Block hat drei Spalten:

* **Anbieter**: deine Organisation, aus dem Firmenprofil übernommen.
* **Kunde**: der Käufer.
* **Rechnung an**: der Rechnungsempfänger. Mit **Wie Kunde** entspricht er dem Kunden.

Kunde und Rechnungsempfänger füllst du manuell oder übernimmst eine gespeicherte Adresse. Pro Partei stehen Felder wie **Firma**, **Vorname** und **Nachname**, **Adresse**, **E-Mail** und **USt-IdNr.** bereit. Eine Firma macht den Empfänger zum Unternehmen, ohne Firma gilt er als Privatperson.

Wie der Empfänger seine Rechnungsdaten selbst ergänzt, steht unter [Rechnungsdaten](/v2-offers-api/billing-details).

## Gültigkeit

Unter **Gültig bis** legst du fest, bis wann das Angebot angenommen werden kann. Nach diesem Datum ist eine Annahme nicht mehr möglich, und das Angebot wird als abgelaufen angezeigt. Den Standardzeitraum stellst du in den [Einstellungen](/v2-offers-api/settings) ein.

## Vorlagen und Bibliothek

Wiederkehrende Inhalte sparst du dir:

* Einen einzelnen Block speicherst du über sein Menü in die **Bibliothek** und fügst ihn später wieder ein.
* Ein komplettes Angebot speicherst du über die Aktionen als **Vorlage**, um es als Ausgangspunkt für neue Angebote zu nutzen.

## Nächste Schritte

<CardGroup>
  <Card title="Veröffentlichen und einladen" icon="paper-plane" href="/v2-offers-api/sending-and-recipients">
    Empfänger einladen, Rollen vergeben und Links teilen.
  </Card>

  <Card title="Annahme und Signatur" icon="file-signature" href="/v2-offers-api/acceptance-and-signing">
    Die Annahme-Optionen und die Sperre nach der Annahme.
  </Card>
</CardGroup>


# Freigaben
Source: https://docs.fynn.eu/v2-offers-api/freigaben

Lege fest, dass bestimmte Angebote vor dem Versand intern freigegeben werden, und steuere den Ablauf über Regeln.

Mit Freigaben legst du fest, dass bestimmte Angebote erst intern bestätigt werden müssen, bevor sie an die Empfänger gehen. Du beschreibst über Regeln, wann eine Freigabe nötig ist, zum Beispiel bei einem hohen Rabatt oder einem großen Vertragswert, und wer dann zustimmen muss. Trifft eine Regel zu, hält das Angebot beim Veröffentlichen an und wartet auf die Entscheidung der Freigeber.

<Info>
  Ohne passende Regel ändert sich nichts: Ein Angebot wird wie gewohnt sofort veröffentlicht. Eine Freigabe greift nur, wenn eine deiner Regeln auf das Angebot zutrifft.
</Info>

## So läuft eine Freigabe ab

```mermaid theme={null}
flowchart TD
  V[Angebot veröffentlichen] --> P{Trifft eine Freigabe-Regel zu?}
  P -->|Nein| L[Angebot geht an die Empfänger]
  P -->|Ja| F[Freigabe ausstehend]
  F --> N[Freigeber werden per E-Mail informiert]
  N --> D{Entscheidung}
  D -->|Freigegeben| L
  D -->|Abgelehnt| R[Änderungen angefragt]
  R -->|überarbeiten und erneut veröffentlichen| V
```

Solange eine Freigabe aussteht, erreicht den Empfänger nichts. Es wird keine Benachrichtigung verschickt, und sichtbar bleibt höchstens eine zuvor freigegebene Fassung, bei einem ersten Angebot noch nichts. Der Status des Angebots bleibt die ganze Zeit **offen**, die Freigabe läuft daneben ab.

## Freigabe-Regeln

Regeln verwaltest du unter **Einstellungen, Freigabe-Regeln**. Eine Regel beschreibt, wann eine Freigabe nötig ist und wer sie erteilt.

| Feld        | Wirkung                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| Name        | Ein sprechender Name, zum Beispiel „Hoher Rabatt".                                                          |
| Priorität   | Reihenfolge der Prüfung. Bei mehreren passenden Regeln greift die mit der kleinsten Zahl zuerst.            |
| Aktiv       | Schaltet die Regel ein oder aus. Inaktive Regeln greifen nie.                                               |
| Bedingungen | Wann die Regel auslöst. Du verknüpfst mehrere Bedingungen mit **alle Bedingungen** oder **eine Bedingung**. |
| Freigeber   | Wer zustimmen darf, als Rollen, als einzelne Personen oder beides.                                          |
| Zustimmung  | Ob **alle** benannten Freigeber zustimmen müssen oder **eine** Zustimmung genügt.                           |

<Note>
  Lässt du die Bedingungen leer, greift die Regel für jedes Angebot. So verlangst du für alle Angebote eine Freigabe.
</Note>

### Bedingungen

Jede Bedingung prüft eine Größe des Angebots mit einem Operator gegen einen Wert:

| Bedingung            | Prüft auf                                                                 | Beispiel                               |
| -------------------- | ------------------------------------------------------------------------- | -------------------------------------- |
| Vertragswert         | Den Vertragswert des Angebots.                                            | größer oder gleich 10.000              |
| Gesamtrabatt         | Den Nachlass über das ganze Angebot gegenüber dem Listenpreis in Prozent. | größer als 20                          |
| Zeilenrabatt         | Den höchsten Rabatt auf einer einzelnen Position in Prozent.              | größer als 20                          |
| Geschäftsart         | Neugeschäft, Erweiterung, Verlängerung oder Einmalig.                     | ist eine von Erweiterung, Verlängerung |
| Rolle des Erstellers | Die Rolle der Person, die das Angebot erstellt hat.                       | ist eine von Vertrieb                  |
| Produkt              | Bestimmte Produkte im Angebot.                                            | ist eine von Produkt A, Produkt B      |
| Produktkategorie     | Produktkategorien der enthaltenen Produkte.                               | ist eine von Hardware                  |

Für Zahlen und Beträge stehen die Vergleiche **ist gleich**, **ist ungleich**, **ist größer als**, **ist größer oder gleich**, **ist kleiner als** und **ist kleiner oder gleich** bereit. Für Auswahlfelder gibt es **ist eine von** und **ist keine von**.

### Freigeber bestimmen

Du wählst die Freigeber über **Rollen** und **Personen**. Trägst du eine Rolle ein, ist jede Person mit dieser Rolle ein Freigeber. Mindestens eine Rolle oder Person ist Pflicht. Über die **Zustimmung** legst du fest, ob eine einzelne Zustimmung reicht oder alle benannten Freigeber zustimmen müssen.

<Info>
  Freigabe-Regeln anlegen und ändern darf nur, wer das Recht **Angebotsfreigaben** hat. Über eine konkrete Freigabe entscheidet dagegen nur, wer in der zutreffenden Regel als Freigeber benannt ist.
</Info>

## Gesamtrabatt und Zeilenrabatt

Für Rabatte gibt es zwei Bedingungen. Du wählst die, die zu deiner Regel passt:

* **Gesamtrabatt** prüft, wie weit das ganze Angebot unter dem Listenpreis liegt.
* **Zeilenrabatt** prüft den höchsten Rabatt auf einer einzelnen Position.

Grundlage ist bei beiden der **Nettopreis**, also ohne Steuer. Je Position wird bei **Menge eins** gerechnet, Freieinheiten und Mindestabnahmen bleiben dabei außen vor.

### Gesamtrabatt

Je Position wird der **Listenpreis** aus dem Katalog mit dem **angebotenen Preis** verglichen, über alle Positionen zusammen. So zählt auch ein Nachlass, den du nur über einen eigenen Preis gibst.

```
Gesamtrabatt in Prozent = (Summe Listenpreise − Summe angebotene Preise) / Summe Listenpreise × 100
```

<Note>
  Der Gesamtrabatt ist nach Wert gewichtet, nicht der Durchschnitt der einzelnen Prozentsätze. Eine teure Position wiegt also schwerer als eine günstige. Gestaffelte Preise und Positionen ohne Listenpreis aus dem Katalog zählen hier nicht mit.
</Note>

### Zeilenrabatt

Der Zeilenrabatt ist der **höchste Rabatt auf einer einzelnen Position**. So löst auch ein hoher Rabatt auf einer einzelnen, betragsmäßig kleinen Position eine Freigabe aus, statt im Gesamtschnitt unterzugehen.

Je Position zählt der höhere Wert aus dem Nachlass gegenüber dem Listenpreis und dem Rabatt in Prozent, den du direkt einträgst. Bei **gestaffelten Preisen** (Staffel, Volumen, Stufen) zählt ausschließlich der Rabatt in Prozent.

### Beispiel

Ein Angebot aus einer Grundgebühr von 149 Euro zum Listenpreis und einer nutzungsbasierten Position mit 50 Prozent Rabatt:

* **Gesamtrabatt:** rund 0 Prozent, weil die nutzungsbasierte Position betragsmäßig kaum ins Gewicht fällt.
* **Zeilenrabatt:** 50 Prozent.

Eine Regel auf den **Zeilenrabatt** greift hier, eine Regel auf den **Gesamtrabatt** nicht. Möchtest du dagegen erst eingreifen, wenn das ganze Angebot stark vergünstigt ist, nimmst du den Gesamtrabatt.

## Offene Freigaben finden

Offene Freigaben findest du unter **Freigaben**.

In der Liste siehst du je Angebot **Angebot**, **Kunde**, **Wert**, **Rabatt** und **Eingereicht**. Über **Prüfen** öffnest du das Angebot und entscheidest dort. Du filterst nach **Mir zugewiesen** und nach **Ausstehend** und suchst nach Angebot oder Kunde.

## Freigeben oder ablehnen

Am Angebot zeigt ein Hinweis den Stand der Freigabe und, je nach Rolle, die passenden Schaltflächen.

| Aktion               | Wer                                             | Wirkung                                                                                               |
| -------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Freigeben            | Benannte Freigeber                              | Stimmt der Freigabe zu. Sobald die nötige Zustimmung erreicht ist, geht das Angebot an die Empfänger. |
| Ablehnen             | Benannte Freigeber                              | Lehnt mit einem Pflicht-Kommentar ab. Der Kommentar sagt dem Ersteller, was zu ändern ist.            |
| Anfrage zurückziehen | Der Ersteller oder jede Person mit Schreibrecht | Bricht eine laufende Freigabe ab, das Angebot kann überarbeitet und erneut veröffentlicht werden.     |

Der Hinweis am Angebot nennt den Anforderer, die Freigeber und ob alle zustimmen müssen oder eine Zustimmung genügt. Je Freigeber siehst du, ob die Person bereits **freigegeben** hat, **Änderungen angefragt** hat oder noch **wartet**.

## Was nach der Entscheidung passiert

<CardGroup>
  <Card title="Freigegeben" icon="circle-check">
    Das Angebot wird veröffentlicht, die beim Veröffentlichen gewählten Empfänger werden informiert. Die Unterschrift folgt wie üblich, sobald ein Empfänger annimmt.
  </Card>

  <Card title="Abgelehnt" icon="circle-xmark">
    Das Angebot bleibt offen und erreicht die Empfänger nicht. Du überarbeitest es und veröffentlichst es erneut, dann wird es neu geprüft.
  </Card>

  <Card title="Zurückgezogen" icon="rotate-left">
    Die Anfrage ist beendet, das Angebot bleibt offen für eine erneute Veröffentlichung.
  </Card>
</CardGroup>

<Note>
  Veröffentlichst du ein Angebot erneut, während noch eine Freigabe läuft, wird die alte Anfrage automatisch ersetzt und die neue Fassung frisch geprüft.
</Note>

## Benachrichtigungen

Alle Beteiligten bleiben per E-Mail auf dem Laufenden:

| Ereignis             | Wer wird informiert                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Neue offene Freigabe | Die Freigeber des Angebots, also die benannten Personen und alle Träger der benannten Rollen. |
| Freigegeben          | Die Person, die das Angebot zur Freigabe eingereicht hat.                                     |
| Abgelehnt            | Die Person, die eingereicht hat, mit dem Kommentar des Freigebers.                            |

## Verwandte Themen

<CardGroup>
  <Card title="Veröffentlichen und Empfänger" icon="paper-plane" href="/v2-offers-api/sending-and-recipients">
    Wie du ein Angebot veröffentlichst und Personen einlädst.
  </Card>

  <Card title="Kernkonzepte" icon="book" href="/v2-offers-api/concepts">
    Angebot, Status und der Lebenszyklus im Überblick.
  </Card>
</CardGroup>


# Angebote
Source: https://docs.fynn.eu/v2-offers-api/introduction

Erstelle verbindliche Angebote als gestaltetes Dokument, sende sie an deine Empfänger und lass sie online annehmen oder elektronisch unterschreiben.

Mit Fynn Angeboten erstellst du ein **verbindliches Angebot als gestaltetes Dokument**, sendest es an deine Empfänger und lässt es online annehmen oder elektronisch unterschreiben. Aus einem angenommenen Angebot entsteht direkt das passende Abonnement, ohne erneute Dateneingabe.

<Info>
  Angebote erstellst und verwaltest du in der App. Für Integrationen bildest du denselben Ablauf über die [API](/v2-offers-api/offers/list-offers) ab. Beide Wege nutzen dieselben Daten, du wählst pro Anwendungsfall den passenden.
</Info>

## Die Bausteine

Ein Angebot besteht aus vier Bausteinen, die zusammenspielen:

<CardGroup>
  <Card title="Angebot" icon="file-lines">
    Die Klammer um deinen Vorschlag, mit Angebotsnummer, Titel, Status und einer Gültigkeit.
  </Card>

  <Card title="Dokument" icon="layer-group">
    Der gestaltete Inhalt aus Blöcken: Texte, Preise, Parteien, Briefkopf und Unterschrift.
  </Card>

  <Card title="Empfänger" icon="users">
    Die Personen, die das Angebot erhalten. Jede Person bekommt ihren eigenen, persönlichen Link.
  </Card>

  <Card title="Annahme" icon="signature">
    Der Weg, wie der Empfänger zusagt: per Klick, mit elektronischer Signatur oder durch Hochladen.
  </Card>
</CardGroup>

## Vom Angebot zum Abonnement

<CardGroup>
  <Card title="Schnellstart" icon="rocket" href="/v2-offers-api/quickstart">
    Vom ersten Angebot bis zur Annahme durch den Empfänger in wenigen Schritten.
  </Card>

  <Card title="Kernkonzepte" icon="book" href="/v2-offers-api/concepts">
    Angebot, Status, Dokument-Blöcke, Empfänger und die Annahme-Optionen.
  </Card>

  <Card title="Der Angebots-Editor" icon="pen-ruler" href="/v2-offers-api/editor">
    Wie du ein Angebot zusammenstellst, Preise hinterlegst und Variablen nutzt.
  </Card>

  <Card title="Die Angebots-Ansicht" icon="eye" href="/v2-offers-api/angebots-ansicht">
    Was dein Empfänger sieht und welche Vorteile die Ansicht gegenüber einem PDF hat.
  </Card>

  <Card title="Annahme und Signatur" icon="file-signature" href="/v2-offers-api/acceptance-and-signing">
    Klick-Annahme, elektronische Signatur und manuelle Annahme im Detail.
  </Card>

  <Card title="Freigaben" icon="circle-check" href="/v2-offers-api/freigaben">
    Angebote vor dem Versand intern freigeben lassen, gesteuert über Regeln.
  </Card>

  <Card title="API-Referenz" icon="code" href="/v2-offers-api/offers/list-offers">
    Alle Endpunkte mit Parametern, Antworten und Beispielen.
  </Card>
</CardGroup>


# Schnellstart
Source: https://docs.fynn.eu/v2-offers-api/quickstart

Vom ersten Angebot bis zur Annahme durch den Empfänger in wenigen Schritten.

Dieser Schnellstart führt dich einmal durch den gesamten Ablauf: ein Angebot anlegen, das Dokument zusammenstellen, veröffentlichen und vom Empfänger annehmen lassen. Du arbeitest dabei in der App, dein Empfänger in der Angebots-Ansicht.

<Steps>
  <Step title="Neues Angebot anlegen">
    Öffne **Angebote** und klicke auf **Neues Angebot**. Du kannst direkt einen Kunden verknüpfen oder das auch später tun.

    <Frame>
      <img alt="Angebotsliste mit hervorgehobener Schaltfläche Neues Angebot" />
    </Frame>
  </Step>

  <Step title="Dokument zusammenstellen">
    Baue das Angebot aus Blöcken zusammen. Über das Pluszeichen oder den Schrägstrich fügst du Texte, einen Preis-Block und weitere Inhalte hinzu. Briefkopf und Parteien sind bereits vorbereitet.

    <Frame>
      <img alt="Angebots-Editor mit Briefkopf, Text und Preis-Block" />
    </Frame>

    Mehr dazu unter [Der Angebots-Editor](/v2-offers-api/editor).
  </Step>

  <Step title="Preise hinterlegen">
    Im **Abonnement**-Block fügst du Produkte mit Mengen und Preisen hinzu. Wiederkehrende und einmalige Posten werden getrennt ausgewiesen, Rabatte erscheinen direkt an der Position.

    <Frame>
      <img alt="Preis-Block mit Positionen, Mengen und Summen" />
    </Frame>
  </Step>

  <Step title="Annahme und Gültigkeit festlegen">
    Wähle in der Seitenleiste, wie der Empfänger annimmt (Klick, elektronische Signatur oder Drucken), und setze unter **Gültig bis** das Ablaufdatum.

    <Frame>
      <img alt="Seitenleiste mit Annahme-Modus und Feld Gültig bis" />
    </Frame>
  </Step>

  <Step title="Veröffentlichen und einladen">
    Klicke auf **Veröffentlichen**. Im Dialog kannst du die Empfänger per E-Mail informieren und einen Begleittext mitgeben. Jede Person erhält einen eigenen Link zum Angebot.

    <Frame>
      <img alt="Veröffentlichen-Dialog mit Benachrichtigungsoption und Begleittext" />
    </Frame>
  </Step>

  <Step title="Der Empfänger nimmt an">
    Der Empfänger öffnet das Angebot über seinen Link, ohne Anmeldung. Er prüft das Dokument und nimmt es an, je nach gewähltem Modus per Klick oder mit elektronischer Signatur.

    <Frame>
      <img alt="Empfängeransicht mit Angebotsdokument und Annehmen-Schaltfläche" />
    </Frame>

    Was der Empfänger sieht, beschreibt [Die Angebots-Ansicht](/v2-offers-api/angebots-ansicht).
  </Step>

  <Step title="Abschluss">
    Nach der Annahme ergänzt der Empfänger bei Bedarf seine Rechnungsdaten. Aus dem angenommenen Angebot entsteht das passende Abonnement, ohne dass jemand die Daten erneut eingibt.
  </Step>
</Steps>

## Nächste Schritte

<CardGroup>
  <Card title="Der Angebots-Editor" icon="pen-ruler" href="/v2-offers-api/editor">
    Blöcke, Preise, Variablen und Vorlagen im Detail.
  </Card>

  <Card title="Annahme und Signatur" icon="file-signature" href="/v2-offers-api/acceptance-and-signing">
    Die drei Annahme-Optionen und die manuelle Annahme.
  </Card>
</CardGroup>


# Veröffentlichen und Empfänger
Source: https://docs.fynn.eu/v2-offers-api/sending-and-recipients

Angebote veröffentlichen, Personen einladen, Rollen vergeben und Links teilen.

Ein Angebot wird für deine Empfänger sichtbar, sobald du es veröffentlichst. Diese Seite beschreibt das Veröffentlichen, das Einladen von Personen und die Rollen.

## Veröffentlichen

Über **Veröffentlichen** machst du die aktuelle Version sichtbar. Im Dialog entscheidest du:

* ob die Empfänger **per E-Mail über die Veröffentlichung informiert** werden,
* welchen **Begleittext** sie dazu erhalten,
* und ob du in einem Schritt **weitere Personen** hinzufügst.

Hast du an einem bereits veröffentlichten Angebot etwas geändert, veröffentlichst du es erneut. Die Schaltfläche ist nur aktiv, wenn es gegenüber der gesendeten Version Änderungen gibt.

<Frame>
  <img alt="Veröffentlichen-Dialog mit Benachrichtigungsoption, Begleittext und weiteren Personen" />
</Frame>

## Personen einladen

Über die Personen-Übersicht fügst du Empfänger hinzu, jeweils **mit Einladung per E-Mail** oder **ohne E-Mail**. Für jede Person kannst du den **persönlichen Link** kopieren und auf deinem eigenen Weg teilen.

### Rollen

| Rolle         | Was die Person kann                                   |
| ------------- | ----------------------------------------------------- |
| Unterzeichner | Das Angebot ansehen und annehmen oder unterschreiben. |
| Beobachter    | Das Angebot nur ansehen.                              |

## Weiterleiten durch den Empfänger

Ein Empfänger kann das Angebot aus der Angebots-Ansicht heraus an eine weitere Person weiterleiten. Diese erhält ihre eigene Einladung und einen eigenen Zugang. So erreichst du auch Personen, die du anfangs nicht kanntest, etwa in der Buchhaltung.

## Freigabe vor dem Versand

Ist für Angebote eine Freigabe eingerichtet, wird das Angebot beim Veröffentlichen zunächst **zur Freigabe eingereicht**, statt sofort zu gehen. Ein Hinweis zeigt den Stand der Freigabe. Nach der Zustimmung wird das Angebot automatisch veröffentlicht und die gewählten Empfänger werden informiert. Ein abgelehntes Angebot kannst du überarbeiten und erneut veröffentlichen. Wie du Regeln einrichtest und wer entscheidet, steht unter [Freigaben](/v2-offers-api/freigaben).

## Weitere Aktionen

Über die Aktionen eines Angebots kannst du es **archivieren** oder **als Vorlage speichern**, um es als Ausgangspunkt für neue Angebote zu nutzen.


# Einstellungen
Source: https://docs.fynn.eu/v2-offers-api/settings

Standardwerte für Angebote: Gegenzeichner, Druck-Annahme, Ablehnen und Gültigkeitsdauer.

Unter **Einstellungen, Angebot** legst du die Standardwerte fest, die für alle neuen Angebote gelten.

<Frame>
  <img alt="Einstellungsseite für Angebote mit E-Signaturen, Angebotsannahme und Gültigkeit" />
</Frame>

## E-Signaturen

| Einstellung                              | Wirkung                                                               |
| ---------------------------------------- | --------------------------------------------------------------------- |
| Gegenzeichner aktivieren                 | Eine feste Person aus deiner Organisation zeichnet jedes Angebot mit. |
| Gegenzeichner-Name, Gegenzeichner-E-Mail | Wer mitzeichnet. Erforderlich, sobald der Gegenzeichner aktiv ist.    |

## Angebotsannahme

| Einstellung                  | Wirkung                                                                          |
| ---------------------------- | -------------------------------------------------------------------------------- |
| Druck-Annahme immer anbieten | Der Empfänger kann zusätzlich zur gewählten Annahme immer drucken und hochladen. |
| Ablehnen erlauben            | Der Empfänger kann das Angebot mit Begründung ablehnen, statt nur anzunehmen.    |

## Gültigkeit

| Einstellung      | Wirkung                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| Gültigkeitsdauer | Standardzeitraum in Tagen, der beim Veröffentlichen das Feld **Gültig bis** vorbelegt. Voreingestellt sind 30 Tage. |

<Info>
  Die Gültigkeit eines einzelnen Angebots passt du jederzeit im Editor unter **Gültig bis** an. Die Einstellung legt nur den Standard fest.
</Info>


# Authentifizierung
Source: https://docs.fynn.eu/v2-plans-api/authentication

API-Token für die Einrichtung und Kunden-Token für den Tarifwechsel im Kundenbereich.

Die Plan-API kennt zwei Kontexte. Die Einrichtung (Pläne anlegen, Checkout-Links erstellen) läuft serverseitig mit einem API-Token deiner Organisation. Der Tarifwechsel im Kundenbereich läuft im Namen eines Kunden mit einem Kunden-Token.

## Basis-URLs

| Umgebung   | Basis-URL                    |
| ---------- | ---------------------------- |
| Produktion | `https://coreapi.io`         |
| Sandbox    | `https://preview.coreapi.io` |

Alle Pfade in dieser Dokumentation beginnen mit `/api`, zum Beispiel `https://coreapi.io/api/plans`.

## Einrichtung: API-Token

Setup-Endpunkte (alles unter `/api/plans`) authentifizierst du mit einem API-Token deiner Organisation. Das Token ist fest an genau eine Organisation gebunden, du brauchst also keinen zusätzlichen Organisations-Header.

<Steps>
  <Step title="Token erstellen">
    Lege ein API-Token in den Entwickler-Einstellungen an. Eine ausführliche Anleitung findest du unter [Authentication](/api-reference/authentication).
  </Step>

  <Step title="Token senden">
    Schicke das Token bei jeder Anfrage im Authorization-Header mit.
  </Step>
</Steps>

```bash theme={null}
curl https://coreapi.io/api/plans \
  -H "Authorization: Bearer api_DEIN_TOKEN"
```

Referenz: [Plans listen](/v2-plans-api/plans/list-plans).

<Warning>
  Behandle API-Token wie ein Passwort. Sie haben vollen Zugriff im Rahmen ihrer Berechtigungen. Gib sie niemals im Browser oder in einer mobilen App preis.
</Warning>

## Kundenbereich: Kunden-Token

Die drei Wechsel-Endpunkte unter `/api/customer/...` laufen im Kontext eines angemeldeten Kunden. Sie erwarten ein Kunden-Token (Bearer) mit der Berechtigung `customer:plan:switch`.

Serverseitig erzeugst du ein solches Token mit deinem API-Token (Berechtigung `customer:authenticate`):

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://coreapi.io/customers/CUSTOMER_ID/authenticate \
    -H "Authorization: Bearer api_DEIN_TOKEN"
  ```

  ```json Response theme={null}
  {
    "data": {
      "accessToken": "...",
      "refreshToken": "...",
      "customerAreaLink": "https://..."
    }
  }
  ```
</CodeGroup>

Den `accessToken` schickst du dann als Bearer-Token an die Kundenbereich-Endpunkte:

```bash theme={null}
curl https://coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
  -H "Authorization: Bearer CUSTOMER_TOKEN"
```

Referenz: [Tarifoptionen abrufen](/v2-plans-api/customer/plan-options).

Alternativ stammt das Token aus einer Kundenbereich-Sitzung (Portal). Wie du Kunden anmeldest und welche Flows es gibt, beschreiben der [OAuth2-Flow](/guide/oauth2/introduction) und der Abschnitt zur Kunden-Authentifizierung unter [Authentication](/api-reference/authentication).

### Im Namen eines Kunden handeln (X-On-Behalf-Of)

Für Server-zu-Server-Integrationen musst du nicht für jeden Kunden ein eigenes Token erzeugen. Du verwendest deinen API-Token und legst über den Header `X-On-Behalf-Of` fest, in wessen Namen die Anfrage läuft:

```bash theme={null}
curl https://coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
  -H "Authorization: Bearer api_DEIN_TOKEN" \
  -H "X-On-Behalf-Of: customer:CUSTOMER_ID"
```

Die Anfrage läuft dann vollständig als dieser Kunde, mit dessen Berechtigungen wie `customer:plan:switch`. Voraussetzungen:

* Dein API-Token braucht die Berechtigung `customer:authenticate`.
* Der Kunde muss zu deiner Organisation gehören, sonst antwortet die API mit `404`.
* Während der Impersonation gelten ausschließlich die Kunden-Berechtigungen, nicht die Admin-Rechte deines Tokens. Reine Admin-Endpunkte sind in einer solchen Anfrage also nicht erreichbar.

So sparst du dir den separaten Token-Abruf und nutzt einen einzigen API-Token für alle Kundenbereich-Aktionen.

<Note>
  Ein Tarifwechsel ist bewusst nur im Kundenbereich möglich, nicht in der Wallet. So entscheidet immer der Kunde selbst über seinen Auf- oder Abstieg.
</Note>

## Berechtigungen

| Berechtigung            | Wofür                                                                   |
| ----------------------- | ----------------------------------------------------------------------- |
| `plan:read`             | Pläne und Checkout-Links lesen                                          |
| `plan:write`            | Pläne anlegen, ändern, aktivieren, löschen und Checkout-Links erstellen |
| `customer:plan:switch`  | Tarifoptionen abrufen, Wechsel-Vorschau und Wechsel (mit Kunden-Token)  |
| `customer:authenticate` | Kunden-Token erzeugen über `POST /customers/{id}/authenticate` (Admin)  |

Fehlt die nötige Berechtigung, antwortet die API mit `401` (nicht authentifiziert) oder `403` (authentifiziert, aber nicht berechtigt).


# Asynchrone Abrechnung
Source: https://docs.fynn.eu/v2-plans-api/billing

Wann abgerechnet wird, wie Änderungen in die nächste Rechnung einfließen und Rechnungen asynchron entstehen.

Die V2-Abrechnung folgt einem einheitlichen Muster: Änderungen werden gesammelt, und Rechnungen entstehen asynchron. Das gilt plattformweit und ist hier am Beispiel der Pläne erklärt. Für die Integration sind vor allem zwei Dinge wichtig: wann eine Rechnung entsteht und wie sich eine Änderung wie ein Tarifwechsel auf die Abrechnung auswirkt.

## Wann abgerechnet wird

* **Erstrechnung:** Beim Checkout entsteht das Abonnement und die erste Abrechnung für die gewählte Tarifstufe.
* **Wiederkehrend:** Danach wird das Abonnement regelmäßig im Intervall des Preisplans abgerechnet.
* **Bei Änderungen:** Ein Tarifwechsel erzeugt keine eigene, sofortige Rechnung. Die anteilige Gutschrift oder Berechnung wird gesammelt und fließt in die nächste reguläre Rechnung ein.

## Sammeln bis zur nächsten Rechnung

Solange für die laufende Periode noch keine Rechnung erstellt wurde, werden Positionen gesammelt. Rechnungen werden anschließend asynchron erzeugt, also nicht im selben Moment wie der API-Aufruf.

Für dich als Entwickler heißt das:

<Steps>
  <Step title="Die Wechsel-Antwort enthält keine fertige Rechnung">
    `switch-plan-tier` bestätigt den Wechsel, liefert aber keine Rechnung. Die Rechnung folgt kurze Zeit später.
  </Step>

  <Step title="Mehrere Änderungen werden gebündelt">
    Führst du mehrere Änderungen kurz nacheinander aus, landen sie gemeinsam auf einer Rechnung, statt einzeln abgerechnet zu werden.
  </Step>

  <Step title="Den Effekt vorab zeigen">
    Wenn du dem Kunden die Kosten sofort zeigen möchtest, nutze die [Vorschau](/v2-plans-api/upgrades-downgrades#anteilige-berechnung). Sie liefert die erwartete Gutschrift und Berechnung, ohne etwas zu verändern.
  </Step>
</Steps>

<Note>
  Plane in deiner Oberfläche damit, dass eine Rechnung nach einem Wechsel mit kurzer Verzögerung erscheint. Verlasse dich für die sofortige Anzeige der Kosten auf die Vorschau, nicht auf eine direkte Rechnung.
</Note>

## Zusammenspiel mit Abonnements

Ein über einen Plan verkauftes Abonnement ist ein ganz normales Abonnement. Es trägt zusätzlich einen Verweis auf die aktuell aktive Tarifstufe (`activePlanTier`).

* Beim Checkout wird das Abonnement angelegt und an die gewählte Tarifstufe gebunden.
* Ein Tarifwechsel ersetzt die Positionen des Abonnements durch die der Zielstufe und aktualisiert die aktive Tarifstufe.
* Status, Laufzeit und Abrechnung folgen den Regeln regulärer Abonnements. Eine Übersicht dazu findest du unter [Abonnements](/guide/subscriptions/introduction).


# Checkout
Source: https://docs.fynn.eu/v2-plans-api/checkout-and-sales-channels

Checkout-Links für Tarifstufen und der Weg vom Link zum Abonnement.

Verkauft wird eine Tarifstufe über einen Checkout-Link. Der Link erzeugt einen Warenkorb mit den Positionen der Tarifstufe und führt den Käufer durch den Checkout.

## Checkout-Link erstellen

```bash theme={null}
curl -X POST https://coreapi.io/api/plans/PLAN_ID/checkout-links \
  -H "Authorization: Bearer api_DEIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "planTierId": "TIER_PRO_ID",
    "couponsAllowed": false,
    "isEnabled": true,
    "salesChannel": "default"
  }'
```

| Feld             | Pflicht | Beschreibung                                                                                                                                     |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `planTierId`     | ja      | Die Tarifstufe, die der Link verkauft. Muss zum Plan gehören.                                                                                    |
| `slug`           | nein    | Eigener URL-Slug. Ohne Angabe wird automatisch einer erzeugt.                                                                                    |
| `couponsAllowed` | nein    | Ob Käufer im Checkout einen Gutschein eingeben dürfen. Standard `false`.                                                                         |
| `isEnabled`      | nein    | Ob der Link aktiv ist. Standard `true`.                                                                                                          |
| `salesChannel`   | nein    | Sales-Channel als UUID oder technischer Name (zum Beispiel `default`). Ohne Angabe greift der aktive Kanal der Anfrage, sonst der Standardkanal. |

Die Antwort enthält eine `url`. Das ist der öffentliche Einstiegspunkt: Er erzeugt einen Warenkorb und leitet den Käufer zur Customerfront des Sales-Channels weiter.

Alle Felder und Antworten: [Checkout-Link erstellen](/v2-plans-api/checkout-links/create-checkout-link) und [Checkout-Links listen](/v2-plans-api/checkout-links/list-checkout-links).

## Sales-Channel des Links

Jeder Checkout-Link gehört zu einem Sales-Channel. Der Kanal bestimmt Branding, die Customerfront-Domain und Standardeinstellungen des Checkouts. Vertriebskanäle sind ein plattformweiter Standard und gelten für V1 und V2 gleichermaßen, sie haben keine eigene V2-Variante.

<Info>
  Was ein Sales-Channel ist, wie du Domain, Branding und Standards einrichtest und wie die Customerfront-Domain aufgelöst wird, beschreibt die kanonische Anleitung [Vertriebskanäle](/guide/tenant/sales-channels). Für Pläne genügt es zu wissen: gib bei Bedarf `salesChannel` an, sonst greift der Standardkanal.
</Info>

## Vom Link zum Abonnement

<Steps>
  <Step title="Warenkorb">
    Der Aufruf der `url` erstellt einen Warenkorb. Die Positionen stammen aus der gewählten Tarifstufe.
  </Step>

  <Step title="Zahlung">
    Der Käufer schließt den Checkout in der Customerfront ab.
  </Step>

  <Step title="Abonnement mit Tarifstufe">
    Nach der Zahlung entsteht ein Abonnement, das fest an die gewählte Tarifstufe gebunden ist. Ab hier laufen weitere Wechsel über den [Tarifwechsel im Kundenbereich](/v2-plans-api/upgrades-downgrades), nicht über einen neuen Checkout.
  </Step>
</Steps>

<Note>
  Die Mengen einer Tarifstufe sind beim Plan-Checkout nicht editierbar. Es gelten die Standardmengen der Positionen. Mengenanpassungen sind erst beim Tarifwechsel im Kundenbereich möglich, sofern die Position das erlaubt.
</Note>


# Create a checkout link
Source: https://docs.fynn.eu/v2-plans-api/checkout-links/create-checkout-link

post /api/plans/{id}/checkout-links
Create a checkout link that sells one tier of the plan. The returned url is the public entry point that creates a cart and redirects the buyer to the customerfront of the sales channel.



# List checkout links of a plan
Source: https://docs.fynn.eu/v2-plans-api/checkout-links/list-checkout-links

get /api/plans/{id}/checkout-links
List all checkout links that belong to a plan, newest first.



# Kernkonzepte
Source: https://docs.fynn.eu/v2-plans-api/concepts

Plan, Tarifstufe und Position im Detail, dazu Status, Mengen und die wichtigsten Felder.

Ein Plan besteht aus einer geordneten Liste von Tarifstufen, und jede Tarifstufe enthält eine oder mehrere Positionen. Diese Seite erklärt die Felder, die du beim Anlegen setzt, und die Regeln dahinter.

Im Wallet verwaltest du Pläne unter **Pläne**. So sieht die Übersicht aus:

<Frame>
  <img alt="Übersicht der Pläne mit Status und Anzahl der Tarifstufen" />
</Frame>

Und so legst du einen Plan mit seinen Tarifstufen an:

<Frame>
  <img alt="Formular zum Anlegen eines Plans mit Tarifstufen und Positionen" />
</Frame>

## Plan

| Feld       | Typ            | Beschreibung                                                                                             |
| ---------- | -------------- | -------------------------------------------------------------------------------------------------------- |
| `code`     | string         | Stabiler, innerhalb der Organisation eindeutiger Bezeichner in Kleinbuchstaben, zum Beispiel `pro-plan`. |
| `name`     | string         | Anzeigename des Plans.                                                                                   |
| `status`   | string         | Lebenszyklus: `draft`, `active` oder `archived`.                                                         |
| `currency` | string \| null | Wird aus den Preisplänen abgeleitet. `null`, solange der Plan keine Positionen hat.                      |
| `tiers`    | array          | Die Tarifstufen, sortiert nach ihrer Position.                                                           |

### Status-Lebenszyklus

| Status     | Bedeutung                                                                      |
| ---------- | ------------------------------------------------------------------------------ |
| `draft`    | Entwurf. Bearbeitbar, aber noch nicht verkaufbar.                              |
| `active`   | Aktiv. Verkaufbar und als Quelle für Tarifwechsel nutzbar. Bleibt bearbeitbar. |
| `archived` | Archiviert. Schreibgeschützt und nicht reaktivierbar.                          |

Ein Plan startet immer als `draft`. Mit der [Aktivierung](/v2-plans-api/plans/activate-plan) wird er `active`. Beim [Löschen](/v2-plans-api/plans/delete-plan) wird er hart gelöscht, falls er nirgends referenziert ist, sonst archiviert.

<Note>
  Damit du einen Plan aktivieren kannst, muss er mindestens eine Tarifstufe haben, und jede Tarifstufe muss mindestens eine Position enthalten.
</Note>

## Tarifstufe

Eine Tarifstufe ist eine Stufe innerhalb des Plans.

| Feld               | Typ            | Beschreibung                                                                                                |
| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `position`         | integer        | Rang innerhalb des Plans. Ein kleinerer Wert ist eine niedrigere Tarifstufe. Eindeutig innerhalb des Plans. |
| `name`             | string         | Anzeigename, zum Beispiel Starter, Pro oder Business.                                                       |
| `upgradeable`      | boolean        | Ob diese Stufe nach oben verlassen werden darf. Standard `true`.                                            |
| `downgradeable`    | boolean        | Ob diese Stufe nach unten verlassen werden darf. Standard `false`.                                          |
| `changeTiming`     | string         | `immediately` oder `end_of_period`. Wann ein Wechsel in diese Stufe wirksam wird.                           |
| `creditType`       | string         | `pro_rata` oder `none`. Wie ungenutzte Zeit beim Wechsel in diese Stufe gutgeschrieben wird.                |
| `commitmentPeriod` | string \| null | Mindestlaufzeit als ISO-8601-Dauer, zum Beispiel `P1Y`. `null` bedeutet keine Mindestlaufzeit.              |

<Warning>
  Die Felder `upgradeable` und `downgradeable` beschreiben, ob eine Tarifstufe **verlassen** werden darf, nicht ob sie betreten werden darf. So kannst du gezielte Sperren zwischen Tarifstufen einbauen, etwa eine Testphase, die nur nach oben verlassen werden kann.
</Warning>

`changeTiming` und `creditType` der **Zielstufe** bestimmen gemeinsam die anteilige Berechnung. Details dazu findest du unter [Up- und Downgrades](/v2-plans-api/upgrades-downgrades#anteilige-berechnung).

## Position

Eine Position verbindet ein Produkt mit einem Preisplan innerhalb einer Tarifstufe.

| Feld              | Typ            | Beschreibung                                                                                     |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| `productId`       | string         | Produkt, das abonniert wird.                                                                     |
| `pricePlanId`     | string         | Preisplan, der zum Produkt gehört.                                                               |
| `defaultQuantity` | number         | Menge, die beim Checkout und beim Wechsel verwendet wird, wenn keine Mengenangabe gesendet wird. |
| `minQuantity`     | number \| null | Untere Grenze für Mengenanpassungen durch Kunden. `null` bedeutet keine untere Grenze.           |
| `maxQuantity`     | number \| null | Obere Grenze für Mengenanpassungen durch Kunden. `null` bedeutet keine obere Grenze.             |

<Info>
  Alle Preispläne innerhalb eines Plans müssen dieselbe Währung verwenden. Bei nutzungsbasierten Produkten ist die Menge nicht editierbar, da sie aus den Nutzungsdaten entsteht.
</Info>

### Editierbare Mengen

Ob ein Kunde die Menge einer Position anpassen darf, leitet die API automatisch ab. Eine Menge ist nicht editierbar, wenn

* das Produkt nutzungsbasiert ist (die Menge kommt aus Nutzungsereignissen), oder
* `minQuantity`, `defaultQuantity` und `maxQuantity` gleich sind (es gibt nur einen gültigen Wert).

In allen anderen Fällen ist die Menge editierbar. In der Antwort des Kundenbereichs erkennst du das am Feld `quantityEditable`.


# Get plan switch options
Source: https://docs.fynn.eu/v2-plans-api/customer/plan-options

get /api/customer/subscriptions/{id}/plan-options
Return the current tier of a subscription and all tiers it can reach, each with a financial preview. This endpoint runs in the customer context and requires a customer token with the customer.plan.switch scope.



# Preview a tier switch
Source: https://docs.fynn.eu/v2-plans-api/customer/preview-plan-tier-switch

post /api/customer/subscriptions/{id}/plan-tier-preview
Return a financial preview for switching the subscription into a target tier, with optional quantity overrides. This call does not change anything.



# Switch the plan tier
Source: https://docs.fynn.eu/v2-plans-api/customer/switch-plan-tier

post /api/customer/subscriptions/{id}/switch-plan-tier
Switch the subscription into a target tier. The change takes effect immediately or at the end of the current period, depending on the target tier. Any proration credit or charge is collected into the next invoice.



# Fynn API V2
Source: https://docs.fynn.eu/v2-plans-api/introduction

Modelliere dein Angebot als Pläne mit Tarifstufen, Up- und Downgrades und Checkout über die Fynn API V2.

Mit der Fynn API V2 modellierst du dein Angebot als **Pläne**: eine Leiter aus Tarifstufen, zwischen denen Kunden auf- und absteigen, mit Checkout und anteiliger Abrechnung beim Wechsel.

<Info>
  Pläne bildest du über die V2-Endpunkte ab. Für alle anderen Anwendungsfälle nutzt du weiterhin die [API-Referenz](/api-reference/introduction). Beide laufen parallel, du wählst pro Anwendungsfall die passende.
</Info>

## Plattformweite Grundlagen

Diese Bausteine gelten unabhängig vom Anwendungsfall:

<CardGroup>
  <Card title="Authentifizierung" icon="key" href="/v2-plans-api/authentication">
    API-Token für die Einrichtung, Kunden-Token für den Kundenbereich.
  </Card>

  <Card title="Asynchrone Abrechnung" icon="receipt" href="/v2-plans-api/billing">
    Wie Änderungen gesammelt und Rechnungen asynchron erzeugt werden.
  </Card>
</CardGroup>

<Note>
  Manche Konzepte sind plattformweiter Standard und gelten für V1 und V2 gleichermaßen. Vertriebskanäle (Sales-Channels) zum Beispiel steuern Branding, Domain und Standardeinstellungen für jeden Verkauf. Sie haben keine eigene V2-Variante. Die vollständige Anleitung findest du unter [Vertriebskanäle](/guide/tenant/sales-channels).
</Note>

## Pläne

Mit Plänen modellierst du dein Angebot als eine Leiter aus Tarifstufen, zwischen denen Kunden auf- und absteigen. Das Modell besteht aus drei Bausteinen:

<CardGroup>
  <Card title="Plan" icon="box">
    Die Klammer um dein Angebot, mit stabilem `code`, Namen und Status.
  </Card>

  <Card title="Tarifstufe" icon="stairs">
    Eine Stufe auf der Leiter, zum Beispiel Starter, Pro oder Business.
  </Card>

  <Card title="Position" icon="cube">
    Ein Produkt mit Preisplan innerhalb einer Stufe, inklusive Mengen.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Schnellstart" icon="rocket" href="/v2-plans-api/quickstart">
    Vom ersten Plan bis zum ersten Tarifwechsel in wenigen Aufrufen.
  </Card>

  <Card title="Kernkonzepte" icon="book" href="/v2-plans-api/concepts">
    Plan, Tarifstufe, Position, Status und die wichtigsten Felder.
  </Card>

  <Card title="Up- und Downgrades" icon="arrow-up-arrow-down" href="/v2-plans-api/upgrades-downgrades">
    Erreichbarkeit, Vorschau und die anteilige Berechnung.
  </Card>

  <Card title="Checkout" icon="cart-shopping" href="/v2-plans-api/checkout-and-sales-channels">
    Checkout-Links für Tarifstufen und der Weg zum Abonnement.
  </Card>

  <Card title="API-Referenz" icon="code" href="/v2-plans-api/plans/create-plan">
    Alle Endpunkte mit Parametern, Antworten und Beispielen.
  </Card>
</CardGroup>


# Activate a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/activate-plan

post /api/plans/{id}/activate
Move a plan from draft to active. The plan must have at least one tier and every tier must contain at least one item.



# Create a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/create-plan

post /api/plans
Create a new plan with its tiers and items. The plan starts in draft status. Activate it before you sell or switch into it.



# Delete or archive a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/delete-plan

delete /api/plans/{id}
Delete a plan. If the plan is not referenced anywhere it is hard deleted and the response is 204. If it is still referenced by checkout links, subscriptions or schedules it is archived instead and the response is 200 with the reference counts.



# Retrieve a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/get-plan

get /api/plans/{id}
Retrieve a single plan with all tiers and items.



# List plans
Source: https://docs.fynn.eu/v2-plans-api/plans/list-plans

get /api/plans
List the plans of your Organisation. Without a status filter all statuses are returned. Supports cursor based pagination by default and page based pagination when you pass page or offset.



# Update a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/update-plan

put /api/plans/{id}
Replace a plan as a whole. Send every tier and item you want to keep. Provide ids to keep existing rows stable, and omit rows you want removed. An archived plan cannot be updated.



# Schnellstart
Source: https://docs.fynn.eu/v2-plans-api/quickstart

Vom ersten Plan bis zum ersten Tarifwechsel in wenigen Aufrufen.

Dieser Schnellstart führt dich einmal durch den gesamten Ablauf: einen Plan anlegen, ihn aktivieren, einen Checkout-Link erstellen und im Kundenbereich einen Tarifwechsel ausführen. Alle Beispiele nutzen die Sandbox unter `https://preview.coreapi.io`. Die vollständigen Parameter und Antwortfelder findest du jeweils auf der verlinkten Referenzseite.

<Steps>
  <Step title="Plan anlegen">
    Lege einen Plan mit drei Stufen an. Die Stufe Starter ist die niedrigste, Business die höchste. Der Plan startet als `draft`.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/plans \
      -H "Authorization: Bearer api_DEIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "code": "pro-plan",
        "name": "Pro Plan",
        "tiers": [
          {
            "position": 0,
            "name": "Starter",
            "upgradeable": true,
            "downgradeable": false,
            "changeTiming": "immediately",
            "creditType": "pro_rata",
            "items": [
              { "productId": "PRODUCT_STARTER", "pricePlanId": "PRICEPLAN_STARTER", "defaultQuantity": 1 }
            ]
          },
          {
            "position": 1,
            "name": "Pro",
            "upgradeable": true,
            "downgradeable": true,
            "changeTiming": "immediately",
            "creditType": "pro_rata",
            "items": [
              { "productId": "PRODUCT_PRO", "pricePlanId": "PRICEPLAN_PRO", "defaultQuantity": 1 },
              { "productId": "PRODUCT_ADDON", "pricePlanId": "PRICEPLAN_ADDON", "defaultQuantity": 1, "minQuantity": 0, "maxQuantity": 50 }
            ]
          },
          {
            "position": 2,
            "name": "Business",
            "upgradeable": false,
            "downgradeable": true,
            "changeTiming": "end_of_period",
            "creditType": "none",
            "items": [
              { "productId": "PRODUCT_BUSINESS", "pricePlanId": "PRICEPLAN_BUSINESS", "defaultQuantity": 1 }
            ]
          }
        ]
      }'
    ```

    Die Antwort enthält den Plan mit generierten IDs. Notiere dir die `id` des Plans und die `id` der Tarifstufe Pro, beides brauchst du gleich.

    Alle Felder und Antworten: [Plan anlegen](/v2-plans-api/plans/create-plan).
  </Step>

  <Step title="Plan aktivieren">
    Ein Plan muss aktiv sein, bevor du ihn verkaufen kannst.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/plans/PLAN_ID/activate \
      -H "Authorization: Bearer api_DEIN_TOKEN"
    ```

    Die Antwort zeigt den Plan mit `"status": "active"`.

    Referenz: [Plan aktivieren](/v2-plans-api/plans/activate-plan).
  </Step>

  <Step title="Checkout-Link erstellen">
    Erstelle einen Checkout-Link für die Tarifstufe, mit der neue Kunden starten sollen, hier die Stufe Pro.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/plans/PLAN_ID/checkout-links \
      -H "Authorization: Bearer api_DEIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "planTierId": "TIER_PRO_ID",
        "couponsAllowed": false,
        "isEnabled": true,
        "salesChannel": "default"
      }'
    ```

    In der Antwort steht eine `url`. Über diese URL schließt ein Kunde sein Abonnement ab. Nach der Zahlung entsteht ein Abonnement, das fest an die gewählte Tarifstufe gebunden ist.

    Alle Felder und Antworten: [Checkout-Link erstellen](/v2-plans-api/checkout-links/create-checkout-link).
  </Step>

  <Step title="Tarifoptionen im Kundenbereich abrufen">
    Ab jetzt arbeitest du im Kundenkontext mit einem Kunden-Token. Ein solches Token erzeugst du serverseitig über `POST /customers/{id}/authenticate`, siehe [Authentifizierung](/v2-plans-api/authentication). Frage damit die erreichbaren Stufen für das Abonnement des Kunden ab.

    ```bash theme={null}
    curl https://preview.coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
      -H "Authorization: Bearer CUSTOMER_TOKEN"
    ```

    Die Antwort enthält die aktuelle Stufe und alle erreichbaren Optionen, jeweils mit einer Kostenvorschau.

    Referenz: [Tarifoptionen abrufen](/v2-plans-api/customer/plan-options).
  </Step>

  <Step title="Wechsel vorab prüfen">
    Zeige dem Kunden, was ein Wechsel kostet, bevor er ihn bestätigt. Die Vorschau ändert nichts.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-tier-preview \
      -H "Authorization: Bearer CUSTOMER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "planTierId": "TIER_BUSINESS_ID" }'
    ```

    Referenz: [Wechsel-Vorschau](/v2-plans-api/customer/preview-plan-tier-switch).
  </Step>

  <Step title="Wechsel ausführen">
    Bestätigt der Kunde, führst du den Wechsel aus.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/switch-plan-tier \
      -H "Authorization: Bearer CUSTOMER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "planTierId": "TIER_BUSINESS_ID" }'
    ```

    Die Antwort bestätigt die neue Tarifstufe. Eine eventuelle Gutschrift oder Nachberechnung landet in der nächsten Rechnung, siehe [Abrechnung](/v2-plans-api/billing).

    Referenz: [Tarif wechseln](/v2-plans-api/customer/switch-plan-tier).
  </Step>
</Steps>

## Nächste Schritte

<CardGroup>
  <Card title="Up- und Downgrades" icon="arrow-up-arrow-down" href="/v2-plans-api/upgrades-downgrades">
    Erreichbarkeit, Vorschau und die anteilige Berechnung im Detail.
  </Card>

  <Card title="API-Referenz" icon="code" href="/v2-plans-api/plans/create-plan">
    Alle Felder und Antworten der einzelnen Endpunkte.
  </Card>
</CardGroup>


# Up- und Downgrades
Source: https://docs.fynn.eu/v2-plans-api/upgrades-downgrades

Erreichbare Stufen, Kostenvorschau, Ausführung und die anteilige Berechnung.

Ein Tarifwechsel verschiebt ein Abonnement von seiner aktuellen Stufe auf eine andere Stufe desselben Plans. Der Wechsel passiert immer im Kundenbereich, mit einem Kunden-Token mit der Berechtigung `customer:plan:switch`.

## Der Ablauf

<Steps>
  <Step title="Optionen abrufen">
    `GET /api/customer/subscriptions/{id}/plan-options` liefert die aktuelle Stufe und alle erreichbaren Zielstufen, jeweils mit Richtung (`upgrade` oder `downgrade`) und einer Kostenvorschau. Referenz: [Tarifoptionen abrufen](/v2-plans-api/customer/plan-options).
  </Step>

  <Step title="Vorschau berechnen">
    `POST /api/customer/subscriptions/{id}/plan-tier-preview` berechnet die Kosten für eine konkrete Zielstufe, optional mit Mengenanpassungen. Dieser Aufruf ändert nichts. Referenz: [Wechsel-Vorschau](/v2-plans-api/customer/preview-plan-tier-switch).
  </Step>

  <Step title="Wechsel ausführen">
    `POST /api/customer/subscriptions/{id}/switch-plan-tier` führt den Wechsel aus. Alle Positionen der aktuellen Stufe werden durch die Positionen der Zielstufe ersetzt. Referenz: [Tarif wechseln](/v2-plans-api/customer/switch-plan-tier).
  </Step>
</Steps>

## Erreichbarkeit

Nicht jede Stufe ist von jeder anderen aus erreichbar. Eine Zielstufe ist erreichbar, wenn

1. sie zum selben Plan gehört wie die aktuelle Stufe,
2. sie eine andere Position hat (die Richtung ergibt sich aus dem Vergleich der Positionen), und
3. jede Stufe auf dem Weg dorthin in der passenden Richtung verlassen werden darf.

Für einen Aufstieg muss jede Stufe von der aktuellen Stufe (einschließlich) bis kurz vor der Zielstufe `upgradeable` sein. Für einen Abstieg gilt dasselbe mit `downgradeable`. Die Zielstufe selbst wird nicht geprüft, sie wird ja betreten, nicht verlassen.

<Tip>
  Verlasse dich nicht auf eigene Berechnungen, welche Stufen erreichbar sind. `plan-options` liefert dir genau die Stufen, die für dieses Abonnement gültig sind, inklusive Vorschau.
</Tip>

## Mengenanpassungen

Erlaubt eine Position editierbare Mengen, kannst du im `items`-Feld der Vorschau und des Wechsels abweichende Mengen senden:

```json theme={null}
{
  "planTierId": "TIER_PRO_ID",
  "items": [
    { "planTierItemId": "ITEM_ADDON_ID", "quantity": 5 }
  ]
}
```

Die Menge muss innerhalb von `minQuantity` und `maxQuantity` der Position liegen, und die Position muss editierbar sein (`quantityEditable: true`). Andernfalls antwortet die API mit `422`.

## Anteilige Berechnung

Ob und wie beim Wechsel anteilig abgerechnet wird, bestimmen `changeTiming` und `creditType` der **Zielstufe**. Der Kunde hat darauf keinen Einfluss, das Verhalten steckt in der Konfiguration der Stufe.

| `changeTiming`  | `creditType` | Verhalten                                                                                                                                                                 |
| --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `immediately`   | `pro_rata`   | Wechsel sofort. Für die ungenutzte Zeit der bisherigen Positionen gibt es eine Gutschrift, für den angebrochenen Zeitraum der neuen Positionen eine anteilige Berechnung. |
| `immediately`   | `none`       | Wechsel sofort, ohne Gutschrift für die ungenutzte Zeit.                                                                                                                  |
| `end_of_period` | `none`       | Wechsel zum Ende der laufenden Periode. Keine anteilige Berechnung, da kein Zeitraum angebrochen wird.                                                                    |

Die Werte `full` und `last_invoiced` stehen für Pläne nicht zur Verfügung, und bei `end_of_period` ist nur `none` zulässig.

### Vorschau lesen

Die Vorschau (`SwitchPreview`) liefert die Beträge als positive Dezimalzahlen, die Richtung ergibt sich aus dem Feldnamen:

| Feld             | Bedeutung                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `creditAmount`   | Gutschrift für die ungenutzte Zeit der bisherigen Positionen. `0.00`, wenn die Zielstufe nicht gutschreibt. |
| `chargeAmount`   | Berechnung für den angebrochenen Zeitraum der neuen Positionen.                                             |
| `recurringTotal` | Der wiederkehrende Betrag der Zielstufe pro Periode (netto, Steuer, brutto).                                |
| `effectiveAt`    | Datum, für das gerechnet wird.                                                                              |
| `warnings`       | Hinweise auf Nebenwirkungen, zum Beispiel `active_discount_will_be_lost`.                                   |

<Warning>
  Bei Stufen mit `end_of_period` rechnet die Vorschau mit dem aktuellen Zeitpunkt. Die angezeigten Beträge sind dann eine Näherung. Der tatsächliche Wechsel rechnet mit dem korrekten Datum am Periodenende.
</Warning>

<Note>
  Ein aktiver Rabatt auf den bisherigen Positionen wird bei einem Wechsel nicht automatisch übernommen. Die Vorschau weist mit `active_discount_will_be_lost` darauf hin. Plane diesen Fall in deiner Oberfläche ein.
</Note>

## Antwort des Wechsels

Ein erfolgreicher Wechsel bestätigt die neue Stufe:

```json theme={null}
{
  "subscriptionId": "0c2a8f1e-9b34-7d22-8e55-1a2b3c4d5e6f",
  "newPlanTierId": "7a3d5b90-2c61-74e8-8f09-9b8c7d6e5f40",
  "warnings": []
}
```

Die finanzielle Auswirkung erscheint nicht sofort als Rechnung. Sie wird gesammelt und in die nächste Rechnung übernommen, siehe [Abrechnung](/v2-plans-api/billing).


# Produkt-Updates Mai 2024
Source: https://docs.fynn.eu/changelog/2024-05

Neue Funktionen und Verbesserungen in Fynn im Mai 2024.

<Update>
  ## Preis-Update Assistent

  <Frame>
    <img />
  </Frame>

  Mit Hilfe des Preis-Update Assistenten können nun die Preise der Produkte in wenigen Schritten global angepasst werden. Der Assistent führt den Nutzer durch die notwendigen Schritte und ermöglicht es, die Preise für alle Produkte oder nur für eine bestimmte Auswahl zu aktualisieren.

  Hierbei können die Preise entweder um einen festen Betrag erhöht oder reduziert werden, oder um einen prozentualen Anteil angepasst werden. Optional kann jeder Preis individuell angepasst werden, um eine differenzierte Preisgestaltung zu ermöglichen.
</Update>

<Update>
  ## Kundengruppen

  Mit dem aktuellen Update ist es nun möglich, Kunden einzelnen Kundengruppen zuzweisen. Dies ermöglicht es, im Preis-Update Assistent die Preise für einzelne Kundengruppen zu aktualisieren. Weitere Funktionen, die auf Kundengruppen basieren, sind bereits in Planung.
</Update>


# Produkt-Updates Juni 2024
Source: https://docs.fynn.eu/changelog/2024-06

Neue Funktionen und Verbesserungen in Fynn im Juni 2024.

<Update>
  ## Kündigen von Abonnements

  <img alt="Kündigen von Abonnements" />

  Abonnements können nun zu verschiedenen Zeitpunkten gekündigt werden.
  Hierbei werden die verschiedenen Laufzeiten und Kündigungsfristen eines Abonnements berücksichtigt.

  Zudem erhält der Kunde auf Wunsch eine automatische Kündigungsbestätigung mit den wichtigsten Informationen per E-Mail.

  [Weitere Details in der Dokumentation](/guide/subscriptions/introduction#abonnement-kuendigen)
</Update>

<Update>
  ## Gutscheincodes im Warenkorb

  <img alt="Gutscheincodes im Warenkorb" />

  Im Warenkorb können nun erstellte Rabatte und Gutscheine eingelöst werden.
  Hierzu kann der Kunde den Gutscheincode im Warenkorb eingeben und der Rabatt wird automatisch abgezogen.

  [Weitere Details in der Dokumentation](/guide/discounts/introduction)
</Update>

<Update>
  ## Export von Kundendaten

  Es ist nun möglich alle Kundendaten mit nur einem Klick zu exportieren. Der Export kann im CSV-Format heruntergeladen werden und enthält alle relevanten Informationen zu den Kunden.

  [Zur Dokumentation](/guide/customers/introduction)
</Update>

<Update>
  ## Produkte archivieren

  Produkte können nun archiviert werden, sodass dein Produktkatalog mit der Zeit übersichtlich bleibt. Archivierte Produkte können jederzeit wiederhergestellt und bearbeitet werden.

  [Zur Dokumentation](/guide/catalogue/products)
</Update>

<Update>
  ## Produkte archivieren

  Produkte können nun archiviert werden, sodass dein Produktkatalog mit der Zeit übersichtlich bleibt. Archivierte Produkte können jederzeit wiederhergestellt und bearbeitet werden.

  [Zur Dokumentation](/guide/catalogue/products)
</Update>

<Update>
  ## SEPA-Lastschrift Einzug über EBICS Schnittstelle

  Bisher war es nur möglich, bei Verwendung der SEPA-Lastschrift Hausbank Integration, die Lastschriften manuell einzureichen. Mit Hilfe der EBICS Schnittstelle können nun die Lastschriften automatisiert eingereicht werden, sodass der Prozess effizienter gestaltet werden kann.

  Solltest du die EBICS Schnittstelle nutzen wollen, schreibe uns eine kurze Nachricht und wir helfen dir gerne weiter.
</Update>

<Update>
  ## Rechnungsabgleich: Mehrere Rechnungen in einer Überweisung

  Kunden überweisen gerne mal mehrere Rechnungen in einer Überweisung, anstatt für jede Rechnung eine separate Überweisung zu tätigen.

  Mit dem aktuellen Update ist es nun möglich, dass Fynn automatisch erkennt, welche Rechnungen in einer Überweisung beglichen wurden und die Zahlungen entsprechend zuordnet.
</Update>


# Produkt-Updates August 2024
Source: https://docs.fynn.eu/changelog/2024-08

Neue Funktionen und Verbesserungen in Fynn im August 2024.

<Update>
  ## Unternehmensangaben im Checkout erzwingen

  Bei Erstellung eines Checkout-Links kannst du nun unter “Weitere Optionen” festlegen, ob der Kunde verpflichtet ist, eine Unternehmensangabe zu machen. So kannst du sicherstellen, dass du nur an Unternehmen verkaufst.

  [Weitere Details in der Dokumentation](/guide/checkout/checkout-links#unternehmensangabe-erzwingen)
</Update>

<Update>
  ## Laufzeiten im Checkout festlegen

  Bei Erstellung eines Checkout-Links kannst du nun unter “Weitere Optionen” Vertrags- & Kündigungszeiträume für wiederkehrende Produkte festlegen. Die Laufzeiten werden anschließend in das Abonnement überführt.

  [Weitere Details in der Dokumentation](/guide/checkout/checkout-links#laufzeiten-festlegen)
</Update>

<Update>
  ## Metadaten & Platzhalter in Checkout-Links

  Du kannst nun bei der Erstellung eines Checkout-Links Metadaten und Platzhalter verwenden.
  Metadaten sind nützlich, um bspw. Informationen über den Kunden oder die Bestellung zu übermitteln und diese
  später in Webhooks oder Weiterleitungs-URLs zu verwenden.

  Zudem kannst du die Metadaten nun als Platzhalter in den Checkout-Links verwenden, um bspw. den Namen des Kunden oder die Bestellnummer zu übermitteln.

  [Weitere Details in der Dokumentation](/guide/checkout/checkout-links#metadaten-hinzufuegen)
</Update>

<Update>
  ## OPOS Listen-Export

  <Frame>
    <img alt="OPOS-Liste exportieren" />
  </Frame>

  Es ist nun möglich, OPOS Listen im CSV-Format zu exportieren. Die OPOS Listen enthalten alle offenen Posten (offene Rechnungen) und können beispielsweise für die Buchhaltung verwendet werden.

  [Weitere Details in der Dokumentation](/guide/invoices/introduction#opos-liste-exportieren)
</Update>


# Produkt-Updates September 2024
Source: https://docs.fynn.eu/changelog/2024-09

Neue Funktionen und Verbesserungen in Fynn im September 2024.

<Update>
  ### MRR Berechnung verbessert

  Die MRR Berechnung wurde verbessert und wurde um weitere Aktivitäten erweitert. Damit wird die MRR Berechnung noch genauer. Unter anderem werden nun folgende Daten berücksichtigt:

  * [Gutscheine](/guide/discounts/introduction#rabatte-und-mrr-monthly-recurring-revenue)
  * Mengenänderungen von Produkten
</Update>

<Update>
  ### Verbesserte Produkt-Auswahl

  <Frame>
    <img alt="Produkt-Auswahl" />
  </Frame>

  Die Produkt-Auswahl beim Hinzufügen eines Abonnements wurde verbessert und bietet nun eine bessere Übersicht über alle verfügbaren Produkte.
  Die Produkte werden nun nach Kategorie sortiert und sind einfacher zu finden.
</Update>

<Update>
  ## Mehrsprachigkeit von Produkten

  Es ist nun möglich, Produkte in mehreren Sprachen zu hinterlegen. Damit können Produkte in verschiedenen Sprachen angezeigt werden. Zudem wird die Rechnung in der Sprache des Kunden erstellt.
  Aktuell sind Deutsch und Englisch verfügbar. Weitere Sprachen können auf Anfrage hinzugefügt werden.

  Die Sprache lässt sich über die Einstellung in den Kunden-Stammdaten festlegen.
</Update>

<Update>
  ## Verbesserte Abo-/ Kunden-Liste

  <Frame>
    <img alt="Abonnements-Liste" />
  </Frame>

  Die Abo- und Kunden-Liste wurde überarbeitet und bietet nun eine verbesserte Übersicht über alle Abonnements und Kunden. Zudem sind nun weitere Filter- und Sortiermöglichkeiten verfügbar.
  Die Verwendung aller Tabellen wurde nun vereinheitlicht und bietet eine einfacherere Bedienung.

  Beispielsweise kann nun in der Abonnement-Liste nach Status (aktiv, gekündigt, beendet, **Testphase**) und der Zahlungsmethode gefiltert werden.
</Update>

<Update>
  ## Verbesserte Suche

  <Frame>
    <img alt="Globale Suche" />
  </Frame>

  Die globale Suche wurde grundlegend erneuert und bietet nun eine verbesserte Suche über alle Daten im System. Wir möchten damit die Suche noch einfacher und schneller gestalten.

  [Weitere Details in der Dokumentation](/guide/tenant/search)
</Update>

<Update>
  ## Verbesserte API-Dokumentation

  Die API-Dokumentation wurde verbessert und wurde um weitere Informationen erweitert oder angepasst.
  Die API ist weiterhin vollständig kompatibel und bietet alle bisherigen Funktionen.

  ## Webhooks

  Folgende Webhooks wurden hinzugefügt:

  * `feature.created` - Ein neues Feature wurde erstellt.
  * `feature.updated` - Ein Feature wurde aktualisiert.
  * `feature.archived` - Ein Feature wurde archiviert.
  * `entitlement.state.updated` - Die aktuell gültigen Features für ein Abonnement wurden aktualisiert (z.B. durch: eine Änderung des Abonnements; der Features; ein Feature wurde durch "gültig ab" / "gültig bis" hinzugefügt oder entfernt; ein Produkt wurde gekündigt / angepasst und entsprechend dessen Features).

  [Weitere Details in der Dokumentation](/guide/entitlements/introduction#webhooks)
</Update>


# Produkt-Updates Oktober 2024
Source: https://docs.fynn.eu/changelog/2024-10

Neue Funktionen und Verbesserungen in Fynn im Oktober 2024.

<Update>
  ## Custom-Fields

  <Frame>
    <img alt="Benutzerdefinierte Attribute erstellen" />
  </Frame>

  Mit den Custom-Fields kannst du nun zusätzliche Informationen zu Kunden, Rechnungen, Produkten und mehr nach deinen Anforderungen speichern.

  [Weitere Details in der Dokumentation](/guide/tenant/custom-fields)
</Update>

<Update>
  ## Feature-Management

  <Frame>
    <img alt="Feature zum Produkt hinzufügen" />
  </Frame>

  Mit dem Feature-Management kannst du nun Abonnements und Produkte mit Features verknüpfen.
  Dies erleichtert die Verwaltung von Features und ermöglicht es, Features für Abonnements und Produkte zu aktivieren oder deaktivieren.
  Behalte damit den Überblick über die Features, die für deine Kunden freigeschaltet sind.

  <Check>
    Diese Erweiterung ist vorerst für alle Kunden kostenfrei verfügbar.
  </Check>

  [Weitere Details in der Dokumentation](/guide/entitlements/introduction)
</Update>

<Update>
  ## Verbesserte E-Mail-Darstellung

  Die Darstellung von E-Mails wurde verbessert. Das Unternehmens-Logo wird nun in den E-Mails in einer optimalen Größe ausgegeben.
</Update>

<Update>
  ## Zahlungsmethode hinzufügen per Link

  Es ist nun möglich, Kunden einen Link zu senden, um eine neue Zahlungsmethode hinzuzufügen. Damit können Kunden einfach und schnell eine Zahlungsmethode hinzufügen, und offene Rechnungen begleichen.

  [Weitere Details in der Dokumentation](/guide/customers/customer-portal#zahlungsmethode-hinzufuegen)
</Update>

<Update>
  ### Kommentare hinterlegen

  Es ist nun möglich, Kommentare zu Aktivitäten zu hinterlegen. Damit können zusätzliche Informationen zu den Aktivitäten festgehalten werden.
  Dies erleichtert die Nachvollziehbarkeit und Dokumentation innerhalb des Teams.

  [Weitere Details in der Dokumentation](/guide/tenant/activities)
</Update>

<Update>
  ### Checkout-Sessions

  Es ist nun möglich, den Warenkorb wiederzuverwenden um bspw. mehrere Produkte in einem Checkout-Prozess zu verkaufen. Damit können Kunden mehrere Produkte in einem Checkout-Prozess kaufen, ohne den Warenkorb zu verlieren.

  [Weitere Details in der Dokumentation](/guide/checkout/checkout-links#checkout-session-erstellen)
</Update>

<Update>
  ### Anpassung der Menge eines Produkts

  Es ist nun möglich, die Menge eines Produkts im Warenkorb nachträglich zu verändern. Damit können Kunden die Menge eines Produkts im Warenkorb anpassen, ohne das ein neuer Checkout-Link generiert werden muss.

  [Weitere Details in der Dokumentation](/guide/checkout/checkout-links#menge-veraenderbar-machen)
</Update>

<Update>
  ### Login-Link versenden / generieren

  Du kannst nun Kunden einen personalisierten Login-Link senden oder in der Wallet generieren. Damit können Kunden sich einfach und sicher in ihrem Kundenbereich anmelden ohne ein Einmal-Passwort eingeben zu müssen.

  Zudem kannst du nun den Login in den Kundenbereich über die API anbieten, ohne das eine weitere Interaktion durch den Kunden notwendig ist.

  [Weitere Details in der Dokumentation](/guide/customers/customer-portal#link-zum-kundenbereich-erstellen)

  ### Erweiterte Anpassung möglich

  Es ist nun möglich, den Kundenbereich noch umfangreicher anzupassen. Damit kannst du den Kundenbereich noch besser an deine Anforderungen zuschneiden.
  Welche Bereiche angepasst werden können, findest du hier:

  [Weitere Details in der Dokumentation](/guide/customers/customer-portal#kundenbereich-anpassen)

  ### Verhalten bei Kündigung während Testphase

  Es ist nun möglich, das Verhalten bei Kündigung während der Testphase festzulegen. Damit kannst du festlegen, ob das Abonnement sofort oder zum Ende der Testphase beendet wird.

  [Weitere Details in der Dokumentation](/guide/customers/customer-portal#verhalten-bei-kuendigung-waehrend-testphase)
</Update>

<Update>
  ## Aktivitäts-Log

  Das Aktivitäts-Log wurde verbessert und zeigt nun detailiertere Informationen zu den Aktivitäten an. Zudem wird diese zusätzlich bei Abonnements, Kunden und Rechnungen angezeigt.

  <Frame>
    <img alt="Aktivitätsprotokoll - Kommentare" />
  </Frame>

  [Weitere Details in der Dokumentation](/guide/tenant/activities)
</Update>

<Update>
  ### Abrechnung von Abos mit Abrechnungsstart in der Vergangenheit

  Abonnements die bspw. verspätet erstellt wurden, können nun auch mit einem Abrechnungsstart in der Vergangenheit erstellt werden.
  Bisher war es so, dass jedes Abrechnungsinterval einmal nächtlich abgerechnet wurde, was widerrum zu mehreren Rechnungen und verzögerten Abrechnungen führte.

  **Bisher**
  Abo-Anlage am 18.12.2024

  Abo-Start am 01.10.2024

  Bei Abo-Anlage wird der 01.10. - 31.10. abgerechnet.

  Am 19.12. wird der 01.11. - 30.11. abgerechnet.

  Am 20.12. wird der 01.12. - 31.12. abgerechnet.

  **Neu**

  <Check>
    Bei Abo-Anlage am 18.12.2024 wird in einer Rechnung der Zeitraum 01.10. - 31.12. abgerechnet, ohne das dies in mehrere Rechnungen aufgeteilt wird. Dies erleichtert die Pflege und Nachvollziehbarkeit erheblich.
  </Check>
</Update>

<Update>
  ### Widerruf von Kündigungen

  Es ist nun möglich, Kündigungen von Abonnements in der Wallet zu widerrufen. Damit kannst du eine Kündigung rückgängig machen.

  [Weitere Details in der Dokumentation](/guide/subscriptions/introduction#kuendigung-widerrufen)
</Update>


# Produkt-Updates November 2024
Source: https://docs.fynn.eu/changelog/2024-11

Neue Funktionen und Verbesserungen in Fynn im November 2024.

<Update>
  ### Tägliche Benachrichtigung bei offenen SEPA-Aufträgen

  Es wird nun täglich eine Benachrichtigung versendet, wenn offene SEPA-Aufträge vorhanden sind.
  Damit wird sichergestellt, dass keine offenen SEPA-Aufträge vergessen werden und die Rechnungen pünktlich eingezogen werden.
</Update>

<Update>
  ### Platzhalter in Rechnungen

  Es werden nun Platzhalter in den Rechnungen nach Finalisierung ersetzt, sodass diese einfach lesbarer werden.
</Update>

<Update>
  ### Verbessertes Matching von Zahlungseingängen

  Das Matching von Zahlungseingängen wurde verbessert. Es werden nun mehr Informationen aus den Zahlungseingängen verwendet, um die Zuordnung zu Rechnungen zu verbessern.
  Zudem wird die Zuordnung nun Maschine-Learning basiert unterstützt, um die manuelle Zuordnung zu reduzieren. Wir konnten in unseren Tests eine deutliche Verbesserung der Zuordnungsrate (über 90%) feststellen.

  Dieses Feature wird nach und nach für alle Kunden aktiviert. Möchtest du dieses Feature bereits jetzt nutzen, kontaktiere uns bitte.
</Update>

<Update>
  ### e-Rechnung Compliance

  Die e-Rechnung Compliance wurde verbessert. Es werden nun mehr Informationen in den e-Rechnungen übermittelt, um den Anforderungen der e-Rechnung zu entsprechen.
  Zudem wird ZUGFeRD als e-Rechnungsformat für alle bestehenden und zukünftigen Kunden festgelegt, bei denen kein e-Rechnungsformat angegeben wurde. Hier ist somit keine Anpassung notwendig.

  Bisherige Rechnungen bleiben unverändert. Sollte eine Entwurfs- oder Freigabe-Rechnung als e-Rechnung versendet werden, kontaktiere uns bitte für Unterstützung.

  Es werden Gutschriften und Rechnungen als e-Rechnung unterstützt. Storno-Rechnungen werden aktuell nicht als e-Rechnung versendet.

  [Weitere Details in der Dokumentation](/guide/invoices/e-invoicing)
</Update>

<Update>
  ### Verbesserte Rechnungs-Liste

  <Frame>
    <img alt="Rechnungs-Liste" />
  </Frame>

  Die Rechnungs-Liste wurde überarbeitet und bietet nun eine verbesserte Übersicht über alle Rechnungen. Zudem sind nun weitere Filter- und Sortiermöglichkeiten verfügbar.
  Die Tabelle kann nun vollständig an die eigenen Bedürfnisse angepasst werden. Zudem kann die aktuelle Tabellenansicht als CSV exportiert werden.

  <Tip>
    Die Gesamtsumme aller aktuell dargestellten Rechnungen wird nun angezeigt und erleichtert die Nachvollziehbarkeit der Rechnungen.
  </Tip>
</Update>


# Produkt-Updates Dezember 2024
Source: https://docs.fynn.eu/changelog/2024-12

Neue Funktionen und Verbesserungen in Fynn im Dezember 2024.

<Update>
  ### BCC für Ausgangsrechnungen

  <Frame>
    <img alt="Zusätzliche Rechnungs-Empfänger" />
  </Frame>

  Es ist nun möglich, eine BCC-Adresse für Ausgangsrechnungen zu hinterlegen. Damit können global Rechnungen an eine weitere E-Mail-Adresse gesendet werden.
  Dies ist nützlich, um bspw. die Buchhaltung oder den Steuerberater über alle Rechnungen zu informieren.

  Dies kann für "Rechnung erstellt" und "Rechnung bezahlt" separat konfiguriert werden.

  [Weitere Details in der Dokumentation](/guide/accounting/introduction#zusaetzliche-rechnungs-empfaenger)
</Update>

<Update>
  ### Gutschriften erstellen

  <Frame>
    <img alt="Gutschrift erstellen" />
  </Frame>

  Es ist nun möglich, Gutschriften zu erstellen. Gutschriften können für (teil)bezahlte Rechnungen erstellt werden.

  [Weitere Details in der Dokumentation](/guide/invoices/introduction#gutschrift-erstellen)
</Update>

<Update>
  ### Zahlung erneut anstoßen

  Es ist nun möglich, den ausstehenden Betrag für eine Rechnung erneut anzustoßen.
  Konnte eine Zahlungsmethode mehrfach nicht belastet werden, kann der offene Betrag mit der gleichen oder einer anderen Zahlungsmethode erneut angestoßen werden.

  <Frame>
    <img alt="Zahlungsart ändern" />
  </Frame>

  [Weitere Details in der Dokumentation](/guide/invoices/introduction#zahlung-erneut-anstossen)
</Update>

<Update>
  ### Storno von Rechnungen mit SEPA-Lastschrift

  Wird eine Rechnung mit SEPA-Lastschrift storniert, wird die SEPA-Lastschrift automatisch aus den SEPA-Auftrags-Exporten entfernt, sofern der Auftrag noch nicht an die Bank übermittelt wurde.
  Ist der SEPA-Auftrag bereits an die Bank übermittelt, kann die Rechnung anschließend gutgeschrieben werden.
</Update>

<Update>
  ### Rechnung schließen

  <Frame>
    <img alt="Rechnung schließen" />
  </Frame>

  Es ist nun möglich, Entwurfs- oder Freigabe-Rechnungen zu schließen. Damit können Rechnungen, die nicht mehr relevant sind oder versehentlich erstellt wurden, verborgen werden.

  [Weitere Details in der Dokumentation](/guide/invoices/introduction#rechnung-schliessen)
</Update>


# Produkt-Updates März 2025
Source: https://docs.fynn.eu/changelog/2025-03

Neue Funktionen und Verbesserungen in Fynn im März 2025.

<Update>
  ## Up- & Downgrades

  Führe Up- und Downgrades von Abonnements durch, indem du mehrere Produkte gruppieren kannst. Dies ermöglicht es, zwischen den Produkten in einem Abonnement zu wechseln, ohne dass ein neues Abonnement erstellt werden muss.
  Zudem können Gutschriften für Restlaufzeiten erstellt werden.

  Innerhalb eines Abonnements können verschiedenste Produkte einzeln up- oder downgraded werden, ohne dass das gesamte Abonnement betroffen ist.
</Update>


# Produkt-Updates April 2025
Source: https://docs.fynn.eu/changelog/2025-04

Neue Funktionen und Verbesserungen in Fynn im April 2025.

<Update>
  ## Gegenzeichner von Angeboten

  Füge nun einen Gegenzeichner zu Angeboten hinzu, um bspw. Angebote von einem internen Mitarbeiter oder der Geschäftsführung gegenzeichnen zu lassen.
</Update>

<Update>
  ## Angebotsvorlagen

  Erstelle Angebotsvorlagen, um diese für zukünftige Angebote zu verwenden. Erstelle bereits fertige Produkt-Konfigurationen und Texte, die du in zukünftigen Angeboten mit nur einem Klick verwenden kannst.
</Update>


# Produkt-Updates Mai 2025
Source: https://docs.fynn.eu/changelog/2025-05

Neue Funktionen und Verbesserungen in Fynn im Mai 2025.

<Update>
  ## PRAP Reports

  Der PRAP Report ermöglicht dir eine einfache Übersicht über periodengerechte Abgrenzung von Rechnungen und den ausstehenden Beträgen.
</Update>

<Update>
  ## Berichte

  <Frame>
    <img alt="Berichte" />
  </Frame>

  Berichte wurden grundlegend überarbeitet und bieten nun eine bessere Übersicht über alle Berichte.
</Update>


# Produkt-Updates Juni 2025
Source: https://docs.fynn.eu/changelog/2025-06

Neue Funktionen und Verbesserungen in Fynn im Juni 2025.

<Update>
  ## Rollen & Berechtigungen

  <Frame>
    <img />
  </Frame>

  Erstelle fein granulare Rollen und Berechtigungen für deine Mitarbeiter, um den Zugriff auf sensible Daten zu steuern. Dies ermöglicht es dir, die Kontrolle über die Daten zu behalten und sicherzustellen, dass nur autorisierte Mitarbeiter Zugriff auf bestimmte Informationen haben.
</Update>

<Update>
  ## Abo Phasen

  <Frame>
    <img />
  </Frame>

  Erstelle Ramp-Up-Deals mit verschiedenen Phasen, um den Umsatz zu steigern. Dies ermöglicht es dir, den Umsatz in verschiedenen Phasen zu steigern und die Kundenbindung zu erhöhen.
  Zudem lassen sich nun Änderungen im Laufe der Vertragslaufzeit einfacher darstellen und verwalten.
</Update>

<Update>
  ## Mindestabnahmemenge

  Definiere eine Mindestabnahmemenge für Produktpreise, um sicherzustellen, dass das Produkt mit der Mindestmenge abgerechnet wird.
</Update>


# Produkt-Updates Juli 2025
Source: https://docs.fynn.eu/changelog/2025-07

Neue Funktionen und Verbesserungen in Fynn im Juli 2025.

<Update>
  ## Rabatte zu aktiven Abonnements hinzufügen

  <Frame>
    <img />
  </Frame>

  Du kannst nun Rabatte zu aktiven Abonnements hinzufügen, um den Kunden einen Rabatt auf die laufenden Kosten zu gewähren.
</Update>

<Update>
  ## Abonnements annullieren

  <Frame>
    <img />
  </Frame>

  Du kannst nun Abonnements annullieren, um sie zu beenden und aus den Auswertungen zu entfernen. Dies ist nützlich, wenn ein Abonnement nicht mehr relevant ist oder versehentlich erstellt wurde.
</Update>

<Update>
  ## Rechnung erstellen

  <Frame>
    <img />
  </Frame>

  Die Rechnungserstellung wurde grundlegend überarbeitet und bietet nun eine bessere Übersicht und Konfiguration der einzelnen Positionen. Zudem können nun prozentuale und fixe Rabatte auf einzelne Positionen angewendet werden.
</Update>


# Produkt-Updates August 2025
Source: https://docs.fynn.eu/changelog/2025-08

Neue Funktionen und Verbesserungen in Fynn im August 2025.

<Update>
  ## Kunden ohne aktives Abo sofort erkennen

  <Frame>
    <img />
  </Frame>

  Ab sofort erkennt ihr sofort, welche Kunden noch ein aktives Abo haben – und welche nicht.

  •	Klickbare Anzeige der aktiven Abos in der Kundenliste
  •	Filteroption: Nur Kunden mit oder ohne aktives Abo anzeigen
  •	Erweiterter Export: Anzahl aktiver Abos direkt im CSV/XLSX enthalten
  •	Berücksichtigt auch bereits gekündigte, aber noch laufende Abos

  Identifiziert Kunden ohne laufenden Vertrag in Sekunden – und schafft gezielte Reaktivierungs- oder Upselling-Möglichkeiten.
</Update>


# Produkt-Updates Oktober 2025
Source: https://docs.fynn.eu/changelog/2025-10

Neue Funktionen und Verbesserungen in Fynn im Oktober 2025.

<Update>
  ## Verbesserte Tabellen: Ansichten, Filter, Exporte

  <Frame>
    <img alt="Verbesserte Tabellen" />
  </Frame>

  ### Ansichten

  Speichere und verwalte deine eigenen Ansichten mit Filtern, Spalten und Sortierung. Damit hast du schnellen Zugriff auf häufig genutzte Datenansichten.

  ### Erweiterte Filter

  Nutze erweiterte, kombinierbare Regeln für präzise Ergebnisse.

  ### Anpassbare Spalten

  Wähle sichtbare Spalten und ändere die Reihenfolge per **Drag & Drop**. Alle Änderungen werden automatisch gespeichert.

  ### Individuelle Exporte

  Exportiere angelegte Ansichten direkt nach deinen Wünschen im **CSV**- oder **Excel**-Format. Hinweis: Die bisherigen Exporte findest du nun unter **Berichte**.

  ### Inline-Bearbeitung

  Benutzerdefinierte Attribute (Auswahl, Mehr-Auswahl) können jetzt direkt in der Bestellungs-Tabellenansicht bearbeitet werden – für eine schnellere Datenpflege.
</Update>


# Produkt-Updates November 2025
Source: https://docs.fynn.eu/changelog/2025-11

Neue Funktionen und Verbesserungen in Fynn im November 2025.

<Update>
  ## Neue Hubspot Karten für die Sidebar

  <Frame>
    <img alt="HubSpot Sidebar Karten" />
  </Frame>

  ### Kundendetails: Verknüpfung mit Fynn

  Die Karte ermöglicht es, HubSpot-Kontakte und -Unternehmen direkt mit Fynn-Kunden zu verknüpfen. Bestehende Kunden können zugeordnet oder neue Fynn-Kunden direkt aus HubSpot heraus angelegt werden.

  ### Datenübersicht: Abonnements, Belege und Zahlungen

  Die neuen Karten bieten einen schnellen Überblick über alle wichtigen Fynn-Daten direkt in HubSpot. Angezeigt werden Abonnements mit Produkten und Vertragsdaten, alle ausgestellten Belege (Rechnungen, Gutschriften) sowie die komplette Zahlungshistorie mit Status und Zahlungsgateway.

  ### Überfällige Rechnungen: Fälligkeitsanalyse

  Die Karte bietet eine detaillierte Fälligkeitsanalyse für offene Rechnungen. Sie unterteilt die Beträge in verschiedene Zeiträume (0–30, 31–60, 61–90, mehr als 90 Tage überfällig) und zeigt für jeden Zeitraum die Anzahl der Rechnungen und den Gesamtbetrag.
</Update>

<Update>
  ## Feinere Filter in Listen

  ### Neue Textfilter für Listen

  Filtere Rechnungen, Abonnements und Zahlungen jetzt noch einfacher:

  * **Ist gleich / Ist ungleich** für exakte Treffer
  * **Enthält / Enthält nicht** für Teilbegriffe
  * **Ist leer / Ist nicht leer** z.B. für interne Notizen

  Bei der Suche werden Groß- und Kleinschreibung nicht berücksichtigt.

  ### Optimierte Datumsfilter

  Datumsfilter wurden vereinfacht und verständlicher benannt. Zudem wurde "Ist gleich" als Operator hinzugefügt.

  ### Verbesserte Betragsfilter

  Für Beträge (z.B. Brutto, offen, Gebühren, Kontostand) wurden die Filter überarbeitet.

  ### Mehr Filterfelder in Übersichten

  In mehreren Listen wurden zusätzliche Filter ergänzt, u.a. für Kundennummer, Kundenname, PO-Nummer und Beschreibung.

  Damit kann direkt in den Übersichten präziser gesucht werden.

  ### Produkte als Spalte in Abonnement-Listen

  In der Abonnement-Übersicht können jetzt die Produkte als Spalte hinzugefügt werden. So ist auf einen Blick erkennbar, welche Produkte in den Abonnements enthalten sind.
</Update>

<Update>
  ## HubSpot Integration

  <iframe title="HubSpot Integration" />

  ### HubSpot Integration

  Verbinde Fynn mit HubSpot und optimiere deine Arbeitsabläufe zwischen CRM und Subscription-Management.

  **Hinweis:** Kontaktiere unser Sales-Team unter [sales@fynn.eu](mailto:sales@fynn.eu) oder den Support unter [support@fynn.eu](mailto:support@fynn.eu), um diese Integration zu aktivieren.

  ### Anlage von Kunden aus HubSpot Kontakten

  Erstelle Fynn-Kunden direkt aus deinen HubSpot-Kontakten – ohne manuelles Kopieren von Daten.

  ### Überblick über Abonnements, Belege und Zahlungen

  Sieh dir alle wichtigen Fynn-Daten direkt in HubSpot an – für einen vollständigen Kundenüberblick.

  ### Übertragung von Aktivitäten zu HubSpot Events

  Automatische Synchronisation von Fynn-Aktivitäten als HubSpot Events für lückenlose Dokumentation.
</Update>

<Update>
  ## re:cap-Berichte als ZIP-Download

  Die re:cap-Berichte bieten eine umfassende Übersicht über alle Verträge und Rechnungen, für das Finanzierungs- und Liquiditätsmanagement. Der Export enthält zwei CSV-Dateien in einer ZIP-Datei:

  * **Verträge (Contracts)**: Enthält alle Abonnements mit Details wie Kundeninformationen, Vertragsstatus, Abrechnungsperioden und nächstem Abrechnungsdatum
  * **Rechnungen (Invoices)**: Enthält alle Rechnungen mit Details wie Rechnungsnummer, Kunde, Leistungszeitraum, Rechnungsdatum, Fälligkeitsdatum und Status

  Der Export wird im Hintergrund vorbereitet und du erhältst eine E-Mail, sobald der Download bereit ist. Die Berichte findest du unter **Berichte** in der Übersicht.
  Die bereitgestellten Dateien können anschließend in re:cap hochgeladen werden.
</Update>

<Update>
  ## Verbesserte Filter in Listen

  Wir haben die Filter in den Listen-Ansichten (z.B. Rechnungen, Abonnements, Zahlungen) deutlich erweitert:

  * Neue Möglichkeiten für Textfilter: **Ist gleich**, **Ist ungleich**, **Enthält**, **Enthält nicht**, **Ist leer**, **Ist nicht leer**
  * Groß- und Kleinschreibung werden bei der Suche nicht berücksichtigt
  * Klare Datumsfilter (ab/bis, genau an einem Tag, Zeitraum von/bis)
  * Verbesserte Betragsfilter für Bereiche und exakte Beträge

  Außerdem wurden zusätzliche Filterfelder ergänzt, z.B. für Kundennummer, Kundenname oder Beschreibungen – so findest du gesuchte Einträge noch schneller.
</Update>


# Produkt-Updates Dezember 2025
Source: https://docs.fynn.eu/changelog/2025-12

Neue Funktionen und Verbesserungen in Fynn im Dezember 2025.

<Update>
  ## Debitorenkonto: Zentrale Übersicht für Kundenbuchhaltung

  ### Neuer Debitorenkonto-Tab

  Der neue Tab "Debitorenkonto" in der Kundendetailansicht bietet eine zentrale Übersicht über alle buchhaltungsrelevanten Informationen eines Kunden. Hier findest du den aktuellen Debitorensaldo, eine detaillierte Kontenübersicht und den monatlichen Salden-Verlauf auf einen Blick.

  ### Debitorenkonto-Karte

  Die Karte zeigt den aktuellen Debitorensaldo (Forderungen - Zahlungen) des Kunden. Ein positiver Saldo bedeutet, dass der Kunde noch Geld schuldet. Ein negativer Saldo bedeutet, dass der Kunde einen Guthaben hat. Zusätzlich werden Forderungen und Zahlungen für den ausgewählten Zeitraum angezeigt.

  ### Kontenübersicht: Aktiv und Passiv

  Die Kontenübersicht zeigt alle Aktiv- und Passiv-Konten des Kunden mit ihren aktuellen Salden. Aktiv-Konten (Soll) sind Forderungen und Vermögenswerte. Passiv-Konten (Haben) sind Erlöse und Verbindlichkeiten. Klicke auf ein Konto, um alle zugehörigen Buchungen in einem Dialog anzuzeigen.

  ### Salden-Verlauf mit detaillierten Buchungen

  Der Salden-Verlauf zeigt die monatliche Entwicklung der Kontosalden oder des Debitorensaldos über die Zeit. Es kann zwischen "Kontosalden" (einzelne Konten) und "Debitorensaldo" (Gesamtsaldo) gewechselt werden. Auf einen Monat klicken, um die Buchungen für diesen Monat anzuzeigen. Auf eine Buchung klicken, um Details zu sehen.

  ### Buchungsübersicht pro Konto

  Klicke auf ein Konto in der Kontenübersicht, um alle Buchungen für dieses Konto in einem Dialog anzuzeigen. Die Übersicht zeigt Datum, Belegnummer, Konto, Gegenkonto, Beschreibung und Betrag. Klicke auf eine Buchung, um weitere Details in einem Slideover zu sehen.
</Update>

<Update>
  ## Bankbuchungsabgleich: Verbesserte Zuordnung und Übersicht

  <Frame>
    <img alt="Bankbuchungsabgleich" />
  </Frame>

  ### Neue Bankbuchungsabgleich-Oberfläche

  Die neue Oberfläche für den Bankbuchungsabgleich bietet eine übersichtliche Darstellung aller Banktransaktionen mit detaillierten Informationen zu Datum, Gegenpartei und Verwendungszweck. Auf einen Blick ist erkennbar, welche Transaktionen bereits zugeordnet wurden und welche noch offen sind.

  ### Zuordnungshistorie

  Die neue Ansicht zeigt alle bereits vorgenommenen Zuordnungen einer Banktransaktion. Es wird angezeigt, welche Rechnungen zugeordnet wurden, der zugeordnete Betrag und das Datum der Zuordnung. Dies bietet vollständige Transparenz über den Abgleichprozess.

  ### Rückgängig-Funktion

  Falls eine Zuordnung korrigiert werden muss, kann sie jetzt einfach rückgängig gemacht werden. Die Rückgängig-Funktion macht den Abgleichprozess flexibler und fehlertoleranter.

  ### Detaillierte Transaktionsansicht

  In der Detailansicht werden alle wichtigen Informationen einer Banktransaktion auf einen Blick angezeigt: Datum, Gegenpartei, Verwendungszweck, Betrag und der offene Betrag. Die übersichtliche Darstellung erleichtert die Zuordnung zu Rechnungen erheblich.

  ### Bankbuchungsabgleich in der Rechnungsdetailansicht

  Die Zuordnungen von Banktransaktionen werden jetzt auch direkt in der Rechnungsdetailansicht angezeigt. Es wird angezeigt, welche Bankbuchungen einer Rechnung zugeordnet wurden, und die Details der Bankbuchung können direkt aus der Rechnung heraus eingesehen und bei Bedarf die Zuordnung rückgängig gemacht werden.
</Update>

<Update>
  ## Rechnungsprognose: Berücksichtigung von Rabatten

  ### Rabatte in der Rechnungsprognose

  Die Rechnungsprognose berücksichtigt jetzt auch Rabatte, die auf Abonnements angewendet wurden. Dadurch erhältst du eine genauere Vorhersage deiner zukünftigen Einnahmen.
</Update>


# Produkt-Updates Januar 2026
Source: https://docs.fynn.eu/changelog/2026-01

Neue Funktionen und Verbesserungen in Fynn im Januar 2026.

<Update>
  ## Nutzungsbasierte Abrechnung & Abonnement-Übergänge

  ### Neues Nutzungsmetriken-System

  Die nutzungsbasierte Abrechnung wurde grundlegend überarbeitet. Nutzungsmetriken werden jetzt direkt am Produkt konfiguriert – mit Event-Name, Aggregationstyp, Filtern und Gruppierung. Das neue System bietet mehr Flexibilität und eine einfachere Konfiguration.

  **Neue Features:**

  * **Aggregationstypen**: Anzahl, Summe, Maximum, Durchschnitt, Eindeutig, Letzter Wert
  * **Filter**: Events nach Eigenschaften filtern (equals, not-equals, gt, lt, in, contains, etc.)
  * **Gruppierung**: Separate Abrechnungspositionen pro Gruppe (z.B. pro AI-Modell oder Region)
  * **Inklusiveinheiten**: Kostenlose Einheiten mit automatischer Proration bei vorzeitiger Beendigung
  * **Mindestabnahme**: Garantierter Mindestumsatz pro Abrechnungsperiode

  ### Usage Events API

  Neue API-Endpoints für das Senden und Abrufen von Nutzungsereignissen:

  * `POST /api/usage-events` – Bis zu 1.000 Events pro Request senden
  * `GET /api/usage-events` – Events mit Filtern und Paginierung abrufen
  * `GET /api/usage-events/[id]` – Einzelnes Event abrufen
  * `GET /api/usage-events/discover` – Event-Namen und Properties automatisch entdecken

  [Zur API-Dokumentation](/api-reference/usage-events/overview)

  ### Abonnement-Übergänge (Transitions)

  Mit dem neuen Transition-Endpoint können Produkte und Preispläne in bestehenden Abonnements gewechselt werden – für Upgrades, Downgrades oder Produktwechsel.

  **Features:**

  * Automatische Gutschriften für nicht genutzte Zeit (anteilig)
  * Teilperioden-Abrechnung für nutzungsbasierte Produkte
  * Sofortige oder geplante Abrechnung
  * Dry-Run-Modus für Vorschau ohne Änderungen

  ```bash theme={null}
  POST /api/subscriptions/[id]/transition
  {
    "effectiveAt": "2026-02-01T00:00:00Z",
    "desiredItems": [{ "productId": "...", "pricePlanId": "...", "quantity": 1 }],
    "proration": "creditProrated",
    "invoiceTiming": "phaseStart"
  }
  ```

  [Zur Transitions-Dokumentation](/guide/subscriptions/transitions)
</Update>

<Update>
  ## Rechnungsaktionen, Monatsabschlüsse & Kundenbereich

  ### Neue Rechnungsaktionen

  Rechnungen können jetzt mit klaren, kontextabhängigen Aktionen bearbeitet werden. Je nach Rechnungsstatus stehen passende Optionen zur Verfügung: Stornieren, Erstatten, Anpassen, Gutschreiben oder Skonto gewähren. Das System prüft automatisch, welche Aktionen möglich sind – basierend auf Zahlungsstatus, offenen Transaktionen und Gutschriftfähigkeit der Positionen.

  ### Pflichtangabe von Gründen bei Rechnungsaktionen

  Für alle Rechnungsaktionen wie Stornierungen, Gutschriften oder Anpassungen muss jetzt ein Grund angegeben werden. Dies sorgt für mehr Transparenz und Nachvollziehbarkeit in der Buchhaltung.

  ### Debitor-Wallet für Kundenverrechnung

  Mit dem neuen Debitor-Wallet können Gutschriften direkt mit offenen Rechnungen verrechnet werden. Kundenguthaben wird zentral verwaltet und bei Stornierungen werden zuvor gebuchte Wallet-Anpassungen automatisch zurückgenommen.

  ### Monatsabschlüsse in der Buchhaltung

  Unter **Buchhaltung > Buchungsposten** können jetzt Monate abgeschlossen werden. Dadurch wird sichergestellt, dass keine Buchungen mehr in abgeschlossenen Monaten erfolgen – z.B. wenn eine Zahlung nachträglich erfasst oder eine Rechnung korrigiert wird. Diese Funktion erfordert die DATEV-Berechtigung unter **Einstellungen > Benutzer & Berechtigungen > Rollen**.

  ### Automatische Erlösaufteilung bei Geschäftsjahreswechsel

  Wenn ein Leistungszeitraum über das Geschäftsjahresende hinausgeht, werden die Buchungen automatisch aufgeteilt – sofern der entsprechende Monat noch nicht abgeschlossen ist. Das ermöglicht eine korrekte periodengerechte Abgrenzung.

  ### Debitorenkonto: Offene Auszahlungen auf einen Blick

  Im Tab "Debitorenkonto" der Kundendetails ist jetzt ersichtlich, welche Belege noch ausgezahlt werden müssen, ob ein Kunde mehr als erforderlich gezahlt hat, oder ob ein Wallet-Guthaben besteht. So behältst du den Überblick über alle offenen Posten.

  ### E-Mail-Zustellstatus in Kundendetails

  In den Kundendetails kann jetzt der E-Mail-Status eingesehen werden: Ob eine E-Mail zugestellt, geöffnet, zurückgewiesen (bounced) oder verzögert wurde, ist auf einen Blick erkennbar.

  ### Einfachere Adressverwaltung

  Adressen können jetzt in den Kundendetails komfortabel für mehrere Abonnements gleichzeitig verwaltet werden. Das vereinfacht die Pflege von Rechnungs- und Lieferadressen erheblich.

  ### Kundenbereich komplett überarbeitet

  Der Self-Service-Bereich für Kunden wurde grundlegend neu gestaltet mit modernem, klarem Design. Kunden können jetzt ihre Adressen verwalten, offene Rechnungen bezahlen und Standard-Zahlungsmethoden für alle Abonnements ändern – alles an einem Ort.

  ### Aktualisieren-Button in allen Tabellen

  Alle Daten-Tabellen verfügen jetzt über einen Aktualisieren-Button, um die Ansicht schnell auf den neuesten Stand zu bringen.

  ### Kontobewegungen: Filter bei Ansichtswechsel

  Die Filter in den Kontobewegungen werden jetzt korrekt angewendet, wenn zwischen Standard-Ansichten gewechselt wird.
</Update>

<Update>
  ## Abrechnungsläufe: Transparenz über Abonnement-Abrechnungen

  <Frame>
    <img alt="Abrechnungsläufe Übersicht" />
  </Frame>

  ### Vollständige Abrechnungshistorie

  Die Abrechnungshistorie listet alle vergangenen, aktuellen und zukünftigen Abrechnungsläufe eines Abonnements auf. Für jeden Lauf werden Zeitraum, Status, zugehörige Rechnung, Betrag und Abrechnungsdatum angezeigt. Die Tabelle kann gefiltert und sortiert werden.

  ### Übersprungene Abrechnungen mit Grund

  Wenn ein Abrechnungslauf übersprungen wurde (z.B. wegen Testphase, pausiertem Abonnement oder Nettobetrag 0,00 EUR), wird der Grund direkt in der Tabelle angezeigt. Ein Tooltip bietet weitere Details zur Begründung.

  ### Detailansicht für jeden Abrechnungslauf

  Klicke auf einen Abrechnungslauf, um eine detaillierte Ansicht mit allen beteiligten Abonnement-Positionen, Zeiträumen und Beträgen zu sehen. Bei abgeschlossenen Läufen ist die zugehörige Rechnung direkt verlinkt.
</Update>


# Produkt-Updates Februar 2026
Source: https://docs.fynn.eu/changelog/2026-02

Neue Funktionen und Verbesserungen in Fynn im Februar 2026.

<Update>
  ## Bankbuchungsabgleich: Zahlungshistorie bei manueller Zuordnung

  Bei der manuellen Zuordnung von Bankbuchungen zu Rechnungen kann jetzt die **bestehende Zahlungshistorie** einer Rechnung direkt in den Suchergebnissen eingesehen werden. Ein Klick auf den Pfeil neben einer Rechnung zeigt alle bisherigen Zahlungseingänge — inklusive Status, Datum, Zahlungsweg und Betrag.

  So erkennst du sofort, ob bereits Zahlungen für eine Rechnung vorliegen, bevor du eine weitere Bankbuchung zuordnest. Das verhindert versehentliche Doppelzuordnungen und gibt mehr Sicherheit bei der manuellen Zuordnung.

  * [Kontobewegungen Dokumentation](/guide/payments/bank-transactions#manuelle-zuordnung)
</Update>

<Update>
  ## Automatische Guthabenverrechnung bei Überzahlungen

  Wenn ein Kunde eine Rechnung überbezahlt, wird der überschüssige Betrag ab sofort automatisch dem Kundenguthaben (Wallet) gutgeschrieben. Das Guthaben kann anschließend automatisch auf offene Rechnungen angerechnet werden, beginnend mit der ältesten fälligen Rechnung.

  **So funktioniert es:**

  Sobald eine Zahlung den offenen Rechnungsbetrag übersteigt, erkennt Fynn die Differenz und bucht sie als Guthaben auf das Kundenkonto. Der offene Betrag der Rechnung wird dabei automatisch auf null gesetzt. Falls der Kunde weitere offene Rechnungen hat, kann das Guthaben automatisch darauf angerechnet werden.

  **Neue Einstellungen:**

  * **Überzahlungen als Guthaben verbuchen**: Steuert, ob Überzahlungen automatisch ins Kundenguthaben überführt werden
  * **Guthaben automatisch auf offene Rechnungen anrechnen**: Wenn aktiviert, wird vorhandenes Guthaben automatisch auf offene Rechnungen angewendet (älteste zuerst)

  Beide Einstellungen lassen sich global unter **Einstellungen > Abrechnung** konfigurieren und pro Kunde individuell überschreiben.

  **Szenarien:**

  * **Einfache Überzahlung**: Kunde zahlt 130 € auf eine 100 €-Rechnung. Die Rechnung wird als bezahlt markiert, 30 € landen im Guthaben.
  * **Mehrfache Zahlungen**: Geht nach einer Überzahlung eine weitere Zahlung ein, wird nur der neue Überschuss zusätzlich gutgeschrieben. Bereits verrechnete Beträge werden nicht doppelt gebucht.
  * **Automatische Anrechnung**: Bei 70 € Guthaben und zwei offenen Rechnungen (40 € und 60 €) wird zuerst die ältere Rechnung vollständig beglichen, die restlichen 30 € werden auf die zweite Rechnung angerechnet.

  Für spätere Auszahlungen speichert Fynn die ursprüngliche Zahlungsmethode, das Gateway und die Transaktionsreferenz mit jeder Guthaben-Transaktion.

  * [Kundenguthaben Dokumentation](/guide/invoices/wallet-balance)
  * [Abrechnungseinstellungen](/guide/tenant/billing)
</Update>

<Update>
  ## Konsolidierte Tagesabrechnung

  Fynn fasst ab sofort alle Abrechnungen eines Kunden an einem Kalendertag in **einer einzigen Rechnung** zusammen. Bisher konnte es vorkommen, dass mehrere Abonnements desselben Kunden zu separaten Rechnungen am gleichen Tag führten.

  **Verhalten:**

  * Alle fälligen Positionen eines Kunden werden gesammelt und als eine Rechnung erstellt
  * Dies betrifft reguläre Abo-Abrechnungen, die am selben Tag fällig werden
  * Manuell erstellte Rechnungen und Sofortabrechnungen sind davon nicht betroffen

  **Vorteil:** Weniger Rechnungen, weniger Zahlungsvorgänge und eine übersichtlichere Buchhaltung — besonders bei Kunden mit mehreren Abonnements.

  * [Abrechnungseinstellungen](/guide/tenant/billing)
</Update>

<Update>
  ## Passkey-Login

  Die Anmeldung bei Fynn ist ab sofort auch per **Passkey** möglich. Passkeys nutzen die biometrische Authentifizierung deines Geräts (Face ID, Touch ID, Windows Hello) oder einen Hardware-Sicherheitsschlüssel für einen schnellen und sicheren Login — ohne Passwort.

  **So funktioniert es:**

  * **Einrichten**: Unter **Mein Profil > Sicherheit** einen Passkey hinzufügen
  * **Anmelden**: Auf der Login-Seite **Mit Passkey anmelden** wählen und per Biometrie bestätigen
  * **Mehrere Geräte**: Für jedes Gerät kann ein eigener Passkey eingerichtet werden

  **Sicherheitsvorteile:**

  * Phishing-resistent — Passkeys sind an die Domain gebunden
  * Kein gemeinsames Geheimnis, das abgefangen werden kann
  * Der private Schlüssel verlässt dein Gerät nie

  Passkeys ergänzen den bestehenden Passwort-Login. Beide Methoden funktionieren parallel.

  * [Passkeys Dokumentation](/guide/tenant/passkeys)
</Update>

<Update>
  ## Globale Suche mit Vorschau

  Die globale Suche (`Ctrl+K` / `Cmd+K`) zeigt jetzt **detaillierte Vorschau-Panels** für Suchergebnisse an. Beim Navigieren durch die Ergebnisse siehst du sofort die wichtigsten Informationen — ohne die aktuelle Seite zu verlassen.

  **Vorschau verfügbar für:**

  * **Kunden**: Name, Kundennummer, Adresse, aktive Abonnements
  * **Rechnungen**: Betrag, Status, Kunde, Positionen
  * **Abonnements**: Produkte, Status, nächste Abrechnung
  * **Produkte & Preispläne**: Details und Konfiguration
  * **Transaktionen**: Betrag, Status, Zahlungsmethode
  * **Mahnungen**: Stufe, offener Betrag, verknüpfte Rechnung
  * **Rabatte**: Konfiguration und Einlösungen

  Zusätzlich werden **Treffer im Kontext** hervorgehoben — du siehst sofort, in welchem Feld (Name, Nummer, Adresse etc.) der Suchbegriff gefunden wurde.

  * [Suche Dokumentation](/guide/tenant/search)
</Update>

<Update>
  ## Übersicht-E-Mails (Digest)

  Fynn versendet jetzt regelmäßige Übersicht-E-Mails, die die wichtigsten Kennzahlen und offenen Aufgaben deiner Organisation zusammenfassen. Jeder Benutzer kann individuell konfigurieren, welche Informationen er erhalten möchte.

  **Neuer Benutzerkontobereich:**

  Im neuen persönlichen Benutzerkontobereich stehen die Tabs **Profil** und **Benachrichtigungen** zur Verfügung. Unter Benachrichtigungen lassen sich die Übersicht-E-Mails aktivieren und die einzelnen Abschnitte konfigurieren.

  **Verfügbare Abschnitte:**

  * **Kunden & Umsatz**: Neue Kunden, Umsatzübersicht
  * **Rechnungen & Zahlungen**: Rechnungen zur Freigabe, Offene SEPA-Exporte, Nicht zugeordnete Zahlungen
  * **Buchhaltung**: Monatsabschluss verfügbar
  * **Betrieb**: Fehlgeschlagene E-Mails, Xentral-Bestellungen

  **Frequenzoptionen:**

  * Täglich (Montag bis Freitag) oder wöchentlich — pro Abschnitt konfigurierbar
  * Kombinierte E-Mail am Montag, wenn tägliche und wöchentliche Abschnitte aktiv sind
  * Keine E-Mail bei leeren Zeiträumen

  **SEPA-Export-Benachrichtigung:** Die Benachrichtigung über ausstehende SEPA-XML-Exporte wird jetzt über die Übersicht-E-Mails gesteuert und kann individuell pro Benutzer konfiguriert werden.

  Die verfügbaren Abschnitte richten sich automatisch nach den Berechtigungen des jeweiligen Benutzers.

  * [Übersicht-E-Mails Dokumentation](/guide/notifications/digest-emails)
</Update>

<Update>
  ## Mahnungen: Korrektur der Betragsanzeige bei Teilzahlungen

  Die Platzhalter `totalGrossAmount` und `referencedInvoiceTotalGrossAmount` in Mahnungsvorlagen zeigen jetzt den **offenen Restbetrag** statt des ursprünglichen Rechnungsbetrags an. Bei Rechnungen mit Teilzahlungen wurde bisher fälschlicherweise der volle Bruttobetrag angezeigt.

  **Beispiel:** Eine Rechnung über 100,00 € mit einer Teilzahlung von 30,00 € und 5,00 € Mahngebühren zeigt jetzt korrekt 75,00 € als Gesamtbetrag (70,00 € offener Betrag + 5,00 € Mahngebühren) — statt zuvor 105,00 €.

  Diese Korrektur gilt für PDF-Belegvorlagen und E-Mail-Benachrichtigungsvorlagen.

  * [Belegvorlagen & Platzhalter](/guide/invoices/document-templates)
</Update>

<Update>
  ## Globale E-Mail-Übersicht

  Alle gesendeten E-Mails können jetzt zentral in einer mandantenweiten Übersicht eingesehen werden — unabhängig vom einzelnen Kunden.

  **Funktionen:**

  * Mandantenweite Liste aller gesendeten E-Mails mit Zustellstatus

  * Filter nach Zeitraum, Status, Betreff, Empfänger und Kunde

  * Detailansicht mit vollständigem E-Mail-Inhalt und Zustellungsverlauf

  * Per-Empfänger-Status bei E-Mails mit mehreren Empfängern

  * Organisationsübergreifende Ansicht: E-Mails aller Child-Kunden einer Organisation einbeziehen

  * [E-Mail-Versand und Statusverfolgung](/guide/customers/email-tracking)
</Update>

<Update>
  ## Abonnement-Platzhalter in Rechnungsvorlagen

  In Rechnungsvorlagen (Titel, Einleitung, Abschlusstext) stehen jetzt Abonnement-Platzhalter zur Verfügung. Damit lassen sich Abonnement-Daten wie Name, Nummer, Bestellnummer und benutzerdefinierte Felder direkt in Rechnungsdokumente einbinden.

  **Neue Platzhalter:**

  * `subscription.name` — Abonnementname
  * `subscription.number` — Abonnementnummer
  * `subscription.poNumber` — Bestellnummer (PO)
  * `subscription.customFields.<key>` — Benutzerdefinierte Felder des Abonnements

  Bei Rechnungen mit mehreren Abonnements werden die Werte automatisch kommagetrennt zusammengefasst.

  **Konfigurierbares Positionsgruppen-Format:**

  Der Name der Positionsgruppen auf Rechnungen kann jetzt unter **Einstellungen > Abrechnung** frei konfiguriert werden. Das Format unterstützt Variablen, Bedingungen und benutzerdefinierte Felder. Eine Live-Vorschau zeigt das Ergebnis direkt bei der Eingabe.

  * [Belegvorlagen & Platzhalter](/guide/invoices/document-templates)
  * [Abrechnungseinstellungen](/guide/tenant/billing)
</Update>

<Update>
  ## Organisationsstruktur: Parent-Child-Beziehungen zwischen Kunden

  Kunden können jetzt in einer Hierarchie organisiert werden. Mit der neuen Organisationsstruktur lassen sich Parent-Child-Beziehungen zwischen Kunden abbilden — ideal für Unternehmen mit mehreren Abteilungen, Standorten oder Tochtergesellschaften.

  **Funktionen:**

  * Bis zu 3 Hierarchieebenen (z. B. Hauptunternehmen → Tochtergesellschaft → Abteilung)
  * Zuweisung und Entfernung von Parent-Kunden über Web-App und API
  * Übersicht aller Child-Kunden mit Abo-Metriken
  * Vollständige Hierarchie als Baumstruktur abrufbar
  * Neue Filter: `parentCustomerId`, `isParent`, `hasParent`
  * Organisationsübergreifende Ansichten für Abonnements, Rechnungen und Transaktionen
  * Webhook-Events: `customer.parent.assigned`, `customer.parent.removed`

  Die Organisationsstruktur ist die Grundlage für zukünftige organisationsbasierte Abrechnungsfunktionen (Consolidated Billing).

  <Note>
    Diese Funktion erfordert die Aktivierung des Feature-Flags `customer.hierarchy`. Kontaktiere den Support zur Freischaltung.
  </Note>

  * [Organisationsstruktur Dokumentation](/guide/customers/organization-hierarchy)
  * [Set Parent Customer API](/api-reference/customer/set-parent-customer)
  * [Get Customer Hierarchy API](/api-reference/customer/get-customer-hierarchy)
</Update>

<Update>
  ## Alle auswählen: Untergeordnete Belege werden korrekt markiert

  Die Funktion „Alle auswählen" in Tabellen mit Baumstruktur (z.B. Rechnungsliste) markiert jetzt auch die untergeordneten Belege korrekt. Bisher wurden beim Klick auf die Checkbox im Tabellenkopf nur die übergeordneten Zeilen ausgewählt – Gutschriften und Stornos, die unter der Ursprungsrechnung gruppiert waren, blieben unmarkiert.

  * **Vollständige Auswahl**: Alle sichtbaren Zeilen inklusive aufgeklappter Unterbelege werden markiert
  * **Korrekte Anzeige**: Der Zustand der Kopf-Checkbox (alle/einige/keine) berücksichtigt jetzt die Gesamtzahl der sichtbaren Zeilen
  * **Massenaktionen**: Aktionen wie „Senden", „PDF herunterladen" oder „Klärung erstellen" werden auf alle markierten Belege angewendet
</Update>

<Update>
  ## Automatische Spracherkennung für Kunden

  Die Sprache eines Kunden wird jetzt automatisch anhand des Landes erkannt. Kunden aus Deutschland, Österreich und der Schweiz (DACH) erhalten automatisch **Deutsch** als Sprache, alle anderen Kunden **Englisch**. Die Sprache bestimmt, in welcher Sprache Benachrichtigungen, Rechnungen und andere Dokumente erstellt werden.

  **Verhalten bei Neuanlage:**

  * Wird keine Sprache angegeben, wird diese automatisch aus dem Ländercode ermittelt
  * DACH-Länder (DE, AT, CH) → Deutsch
  * Alle anderen Länder → Englisch
  * Eine explizit gewählte Sprache überschreibt die automatische Erkennung

  **Web-App:**
  Bei der Kundenanlage wird die Sprache automatisch vorgeschlagen, sobald ein Land ausgewählt wird. Die Auswahl kann manuell überschrieben werden.

  **API:**
  Das Feld `language` ist bei `POST /customers` jetzt optional. Wird es nicht angegeben, wird die Sprache automatisch aus dem `countryCode` ermittelt. Bei `PUT /customers` bleibt `language` weiterhin ein Pflichtfeld.

  **Bestehende Kunden:**
  Bestehende Kunden mit Sprache Deutsch und einem Nicht-DACH-Land wurden automatisch auf Englisch umgestellt, damit sie Dokumente in der richtigen Sprache erhalten.

  * [Kunde erstellen API](/api-reference/customer/create-customer)
  * [Kundeneinstellungen](/guide/customers/settings)
</Update>

<Update>
  ## Mehrsprachige E-Mail-Benachrichtigungen

  E-Mail-Benachrichtigungen können jetzt in **Deutsch und Englisch** versendet werden. Kunden erhalten Benachrichtigungen automatisch in der Sprache, die in ihren Stammdaten hinterlegt ist.

  **E-Mail-Vorlagen pro Sprache:**

  * Jede Benachrichtigung kann nun eine separate deutsche und englische Vorlage haben
  * Die Vorlagen werden unabhängig voneinander bearbeitet und versioniert
  * Im Vorlagen-Editor kann per Sprachreiter zwischen Deutsch und Englisch gewechselt werden

  **KI-gestützte Übersetzung:**

  * Mit einem Klick kann die deutsche Vorlage automatisch ins Englische übersetzt werden
  * Die Übersetzung berücksichtigt MJML-Struktur, Platzhalter und Template-Variablen
  * Die generierte Übersetzung kann vor dem Speichern überprüft und angepasst werden

  **Globaler Header & Footer:**

  * Header und Footer der E-Mails können ebenfalls pro Sprache konfiguriert werden
  * Systemtexte wie "Geschäftsführer" oder "E-Mail im Browser öffnen" werden automatisch übersetzt

  **Automatischer Fallback:**

  * Ist keine englische Vorlage konfiguriert, wird automatisch die deutsche Version verwendet

  * Die Sprache wird aus dem Kundenprofil ermittelt (Feld "Sprache")

  * [Benachrichtigungen konfigurieren](/guide/notifications/introduction)
</Update>

<Update>
  ## Up- & Downgrades dokumentiert

  Die API und Dokumentation für Up- & Downgrades ist jetzt vollständig verfügbar. Mit Produktgruppen definierst du, welche Produkte zusammengehören und wie Kunden zwischen ihnen wechseln können.

  **Features:**

  * Definiere Upgrade- und Downgrade-Pfade zwischen Produkten

  * Konfiguriere Wechselzeitpunkt (sofort oder zum Periodenende)

  * Steuere Gutschriften bei sofortigem Wechsel

  * Aktiviere Self-Service im Kundenbereich

  * [Up- & Downgrades Guide](/guide/catalogue/product-groups)

  * [API Guide: Upgrades implementieren](/api-reference/guides/implement-upgrades)

  * [API: Product Groups](/api-reference/productgroup/get-product-groups)
</Update>

<Update>
  ## Globale Suche: Kunden nach Adresse finden

  In der globalen Suche können Kunden jetzt auch nach Rechnungs- und Lieferadresse gesucht werden. So findest du Kunden schneller – auch wenn du nur die Adresse kennst.
</Update>

<Update>
  ## Kostenlose Positionen werden sofort aktiv

  Abonnement-Positionen mit einem Preis von 0,00 € werden jetzt direkt in den Status `active` überführt, anstatt im Status `pending` zu verbleiben. Dies betrifft z.B. kostenlose Add-ons oder Testprodukte.
</Update>

<Update>
  ## Zahlungsmethoden-Link: Redirect URL

  Beim Erstellen eines Zahlungsmethoden-Links kann jetzt eine `redirectUrl` angegeben werden. Nach dem Hinzufügen der Zahlungsmethode wird der Kunde auf diese URL weitergeleitet – anstatt auf die Standard-Statusseite.

  ```bash theme={null}
  POST /payment-methods/link
  {
    "customer": "customer-uuid",
    "redirectUrl": "https://example.com/done"
  }
  ```

  [API-Dokumentation](/api-reference/paymentmethod/create-payment-method-link)
</Update>

<Update>
  ## Abonnement-Positionen durchsuchen

  Bei Abonnements mit vielen Positionen wird jetzt eine Suchfunktion angezeigt:

  * **Phasen-Ansicht**: Ab 5 Positionen pro Phase können diese durchsucht werden
  * **Kündigung**: Bei mehr als 5 Positionen können einzelne Produkte zur Kündigung gesucht werden
  * **Aktivierung**: Bei mehr als 5 Positionen können einzelne Produkte zur Aktivierung gesucht werden
</Update>

<Update>
  ## Rechnungsliste: Zusammengehörige Belege auf einen Blick

  <Frame>
    <img alt="Rechnungsliste mit Baumansicht" />
  </Frame>

  Die Rechnungsliste zeigt jetzt zusammengehörige Belege in einer übersichtlichen Baumstruktur an. Gutschriften und Stornos werden direkt unter der zugehörigen Ursprungsrechnung gruppiert – so erkennst du auf einen Blick, welche Belege zusammengehören.

  * **Bessere Übersicht**: Zusammengehörige Belege sind visuell gruppiert
  * **Schnelle Navigation**: Per Klick auf den Pfeil werden verknüpfte Belege ein- oder ausgeklappt
</Update>

<Update>
  ## Custom PDF Rendering

  ### Eigene PDF-Rendering-Engine für Rechnungen, Gutschriften & Stornos

  Mit dem neuen Custom PDF Rendering Feature können Enterprise-Kunden ihre eigene PDF-Rendering-Engine für die Generierung von Rechnungen, Gutschriften und Stornos verwenden.

  Du möchtest Belege exakt nach deinen Corporate-Design-Vorgaben gestalten – ohne Einschränkungen durch Templates? Oder branchenspezifische Anforderungen an Beleglayouts erfüllen? Mit Custom PDF Rendering hast du die volle Kontrolle über das Erscheinungsbild deiner Dokumente.

  Nutze bewährte Tools wie LaTeX, Typst oder Puppeteer, generiere mehrsprachige Belege mit eigenen Übersetzungen und füge individuelle Inhalte wie QR-Codes oder kundenspezifische Anhänge hinzu – ganz nach deinen Anforderungen.

  **Funktionsweise:**

  1. Beim Finalisieren eines Belegs wechselt dieser in den Status `STATUS_FINALIZING`
  2. Fynn sendet den Webhook `invoice.pdf.generation_requested` mit allen Belegdaten
  3. Dein System generiert das PDF mit deiner eigenen Engine
  4. Das PDF wird über `POST /api/invoices/{id}/pdf` hochgeladen
  5. Fynn bettet optional ZUGFeRD-XML ein und schließt die Finalisierung ab

  **Konfigurationsoptionen** (unter Einstellungen > Abrechnung):

  | Option                                       | Beschreibung                                                    |
  | -------------------------------------------- | --------------------------------------------------------------- |
  | Benutzerdefiniertes PDF-Rendering aktivieren | Delegiert die Beleg-PDF-Generierung an ein externes System      |
  | ZUGFeRD-XML einbetten                        | Bettet e-Rechnungsdaten automatisch in das hochgeladene PDF ein |
  | Automatischer Fallback                       | Nutzt den internen Renderer bei Timeout                         |
  | Timeout                                      | Wartezeit bis zum Fallback (1-1440 Minuten)                     |

  <Note>
    Diese Funktion ist nur im Enterprise-Plan verfügbar.
  </Note>

  [Zur Dokumentation](/integrations/custom-pdf-rendering)
</Update>

<Update>
  ## Schnellerer Checkout

  Der Checkout-Prozess wurde deutlich beschleunigt. Kunden gelangen jetzt noch schneller zur Bestätigungsseite.
</Update>

<Update>
  ## Login per E-Mail-Link

  Der Login zum Kundenbereich ist jetzt noch einfacher: Kunden geben ihre E-Mail-Adresse ein und erhalten einen Login-Link per E-Mail. Ein Klick genügt – kein Code mehr nötig.

  Zusätzlich können Mitarbeiter jetzt direkt aus der Wallet eine Login-E-Mail an Kunden senden, z.B. für Support-Anfragen.

  Der Login-Link ist jetzt auch deutlich kürzer, sodass er problemlos in E-Mail-Clients und Messenger eingefügt werden kann.

  <Tip>
    Die E-Mail-Vorlage kann unter **Einstellungen > Benachrichtigungen** angepasst werden (Vorlage: "Kunden Login-Link angefordert").
  </Tip>

  * [Zur Dokumentation](/guide/customers/customer-portal#login-e-mail-an-kunden-senden)
  * [API: Login-E-Mail senden](/api-reference/customer/send-login-email)
  * [API: Login-Link anfordern](/api-reference/customerotp/request-login-link)
</Update>

<Update>
  ## Customer Authentication API

  ### Authentifizierte Kundenbereich-Links per API generieren

  Mit dem neuen Endpoint `POST /customers/{id}/authenticate` können authentifizierte Links zum Kundenbereich generiert werden. Kunden können damit direkt auf ihren Kundenbereich zugreifen – ohne Login.

  **Anwendungsfälle:**

  * **Kundenbereich-Zugang**: Generiere Links für E-Mails oder Kundenportale
  * **API im Kundenkontext**: Nutze den Access-Token für API-Aufrufe im Namen des Kunden
  * **Self-Service Integration**: Binde den Kundenbereich nahtlos in deine Anwendung ein

  **Response:**

  ```json theme={null}
  {
      "data": {
          "accessToken": "eyJhbGci...",
          "refreshToken": "eyJhbGci...",
          "customerAreaLink": "https://example.customerfront.app/customer-area/login?token=abc"
      }
  }
  ```

  [Zur API-Dokumentation](/api-reference/customer/authenticate-customer)
</Update>

<Update>
  ## Verbesserung: invoice.finalized Webhook

  ### Webhook wird jetzt nach Zahlungsinitialisierung ausgelöst

  **Bisheriges Verhalten:**

  * Der Webhook wurde ausgelöst, während die Rechnung noch im Status `STATUS_FINALIZING` war
  * Die Zahlungsabwicklung wurde erst danach initialisiert

  **Neues Verhalten:**

  * Der Webhook wird jetzt ausgelöst, **nachdem** die Zahlungsabwicklung initialisiert wurde
  * Die Rechnung hat zum Zeitpunkt des Webhooks den Status `STATUS_UNPAID`
  * Das `paymentIntent` ist bereits erstellt und in der Rechnung verfügbar

  **Vorteile:**

  * Vollständigere Rechnungsdaten im Webhook (inkl. Payment Intent)
  * Konsistenterer Zustand für nachgelagerte Systeme
  * Bessere Integration mit Zahlungsprozessen

  **Migration:**
  Falls dein System auf `status: "STATUS_FINALIZING"` prüft, aktualisiere die Prüfung auf `status: "STATUS_UNPAID"`.

  ```javascript theme={null}
  // Vorher
  if (invoice.status === 'STATUS_FINALIZING') { ... }

  // Nachher
  if (invoice.status === 'STATUS_UNPAID') { ... }
  ```
</Update>

<Update>
  ## Entitlement Status Feld

  ### Neues Status-Feld für Subscription Entitlements

  Die Subscription Entitlements API wurde um ein neues `status`-Feld erweitert. Dieses berechnete Feld zeigt den aktuellen Zustand eines Entitlements an und ergänzt das bestehende `active`-Flag.

  **Mögliche Status-Werte:**

  * **`active`**: Das Entitlement ist aktiviert und liegt innerhalb des Gültigkeitszeitraums. Der Kunde kann das Feature nutzen.
  * **`pending`**: Das Entitlement ist aktiviert, aber das `validFrom`-Datum liegt in der Zukunft. Das Feature wird automatisch aktiv, sobald das Datum erreicht ist.
  * **`disabled`**: Das Entitlement wurde manuell deaktiviert.
  * **`expired`**: Das `validUntil`-Datum ist abgelaufen. Das Entitlement war aktiv, ist aber nicht mehr gültig.

  **Beispiel API-Response:**

  ```json theme={null}
  {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "feature": { "id": "white-labeling", "name": "White Labeling" },
      "value": "true",
      "validFrom": "2026-03-01T00:00:00Z",
      "validUntil": null,
      "active": true,
      "status": "pending"
  }
  ```

  Das neue Feld ermöglicht eine präzisere Steuerung von Features basierend auf Gültigkeitszeiträumen. Bei Status-Änderungen wird weiterhin der `entitlement.state.updated` Webhook ausgelöst.

  **Neue Query-Parameter:**

  | Parameter        | Beschreibung                                                                  |
  | ---------------- | ----------------------------------------------------------------------------- |
  | `status`         | Filtert Entitlements nach Status (`active`, `pending`, `disabled`, `expired`) |
  | `includeExpired` | Schließt abgelaufene Entitlements ein (Standard: `false`)                     |

  **Beispiele:**

  ```bash theme={null}
  # Nur aktive Entitlements abrufen
  GET /subscriptions/{id}/entitlements?status=active

  # Alle Entitlements inkl. abgelaufener abrufen
  GET /subscriptions/{id}/entitlements?includeExpired=true
  ```

  <Note>
    Expired Entitlements werden standardmäßig ausgeblendet, um die API-Antworten übersichtlich zu halten.
  </Note>

  **Betroffene API-Endpoints:**

  * [GET /subscriptions//entitlements](/api-reference/entitlement/get-subscription-entitlements)
  * [POST /subscriptions//entitlements](/api-reference/entitlement/add-subscription-entitlement)
  * [GET /subscription-items//entitlements](/api-reference/entitlement/get-subscription-item-entitlements)
  * [POST /subscription-items//entitlements](/api-reference/entitlement/add-subscription-item-entitlement)
  * [PUT /entitlements//status](/api-reference/entitlement/update-entitlement-status)

  [Zur Dokumentation](/guide/entitlements/introduction#entitlement-status)
</Update>


# Produkt-Updates März 2026
Source: https://docs.fynn.eu/changelog/2026-03

Neue Funktionen und Verbesserungen in Fynn im März 2026.

<Update>
  ## Automatische Produktgruppen-Zuweisung

  Beim Erstellen von Abonnements oder Hinzufügen von Produkten zu bestehenden Abonnements kann die Produktgruppe jetzt automatisch zugewiesen werden. Das neue Feld `autoAssignProductGroup` in der ProductSelection ermöglicht es, die Produktgruppe basierend auf dem gewählten Produkt automatisch setzen zu lassen, ohne sie manuell angeben zu müssen.

  * Verfügbar bei `POST /subscriptions` und beim Hinzufügen von Produkten zu Abonnements (Orders)

  * Standardwert: `false` (bisheriges Verhalten bleibt unverändert)

  * [Abonnement erstellen API](/api-reference/subscription/create-subscription)
</Update>

<Update>
  ## Automatische Regeln für Bankbuchungen

  Wiederkehrende, irrelevante Bankbuchungen wie Kontogebühren, Kreditkartenabbuchungen oder interne Umbuchungen können jetzt mit konfigurierbaren Regeln automatisch ignoriert werden.

  **Regel-System:**

  * Regeln mit Bedingungen auf Gegenpartei, IBAN, Verwendungszweck, Betrag und weiteren Feldern
  * Automatische Auswertung beim Sync neuer Bankbuchungen
  * Nachträgliches Anwenden auf bestehende offene Buchungen per Klick
  * UND-Verknüpfung zwischen verschiedenen Feldern, ODER innerhalb desselben Felds
  * Autocomplete bei der Werteingabe basierend auf vorhandenen Transaktionsdaten

  **Intelligente Vorschläge:**

  * System erkennt Muster in bereits manuell ignorierten Transaktionen

  * Vorgeschlagene Regeln mit Beispiel-Transaktionen (Datum, Verwendungszweck, Betrag)

  * Ein-Klick-Übernahme oder Verwerfen einzelner Vorschläge

  * Inline-Vorschlag direkt nach dem Ignorieren einer Transaktion

  * [Regeln für Bankbuchungen (Anleitung)](/guide/payments/bank-transaction-rules)
</Update>

<Update>
  ## Verbesserter DATEV-Export

  Der DATEV-Buchungsdatenservice-Export wurde grundlegend überarbeitet. Der neue Export basiert auf einem generischen Background-Job-Framework und bietet deutlich bessere Transparenz und Zuverlässigkeit.

  **Neuerungen:**

  * **Echtzeit-Fortschrittsanzeige** mit Schritten: Dokumenten-Upload, Stammdaten-Export, Buchungsstapel-Export, DATEV-Verarbeitung
  * **Multi-Monats-Export**: Mehrere Monate in einem Durchgang exportieren
  * **Keine falschen Fehlermeldungen** mehr durch Transport-Timeouts
  * **Keine doppelten Exporte** durch ungewollte Retry-Mechanismen
  * Fortschritt bleibt auch beim Seitenwechsel sichtbar (Mercure-basiert)

  Die DATEV-Seite unter **Buchhaltung > DATEV** wurde mit einer neuen Tabellenansicht und einem kompakten Fortschrittsbalken ausgestattet.
</Update>

<Update>
  ## HubSpot-Integration: Mapping & Sync

  Die HubSpot-Integration wurde in mehreren Bereichen verbessert, um die Verknüpfung zwischen HubSpot und Fynn einfacher und schneller zu machen.

  **Neuer Mapping-Wizard:**

  * Verknüpfe HubSpot-Unternehmen mit Fynn-Kunden und Deals mit Abonnements in einem geführten Prozess
  * Intelligente Vorschläge erkennen passende Zuordnungen automatisch
  * Alle Vorschläge auf einmal übernehmen oder einzeln prüfen

  **Automatischer Sync:**

  * Kontakte und Unternehmen werden automatisch synchronisiert, sobald ein Deal eine bestimmte Stage erreicht

  **Weitere Verbesserungen:**

  * HubSpot Deal-ID, Company-ID und Contact-ID in Kunden- und Abo-Exporten sowie als Tabellenspalten verfügbar
  * Beim Anlegen eines Kunden aus HubSpot werden Adresse, E-Mail und Kontaktdaten automatisch vorausgefüllt
</Update>

<Update>
  ## Bankbuchungen über EBICS

  Wenn eine EBICS-Verbindung eingerichtet und konfiguriert ist, werden Bankbuchungen ab sofort über EBICS abgerufen – anstelle von GoCardless. Das ermöglicht einen direkten und unabhängigen Abruf der Kontotransaktionen über die eigene Bankverbindung.
</Update>

<Update>
  ## Provisionssystem

  Vertriebsprovisionen werden ab sofort automatisch auf Basis deiner Rechnungsdaten berechnet. Ohne Excel, ohne manuelle Zuordnung. Das vollständige Provisionssystem umfasst:

  **Provisionspläne:**

  * Flexible Provisionssätze auf Netto- oder Bruttobasis
  * Auslöser bei Rechnungsstellung oder Zahlungseingang
  * Geltungsbereich: alle Rechnungen oder nur erster Vertragszeitraum
  * Produktspezifische Sätze über Regelwerk
  * Auszahlungsschwelle pro Kunde

  **Vertriebsmitarbeiter & Zuweisungen:**

  * Mitarbeiter manuell anlegen oder aus HubSpot importieren
  * Kunden einzeln oder per Bulk-Zuweisung zuordnen
  * Kundenausschlüsse mit Begründung

  **Provisionen & Rückforderungen:**

  * Automatische Berechnung bei Rechnungserstellung
  * Automatische Rückforderung bei Stornierungen und Gutschriften (anteilig)
  * Batch-Genehmigung und -Stornierung

  **Auszahlungen:**

  * Auszahlungen pro Mitarbeiter und Monat bündeln

  * Freigabe-Workflow (Entwurf → Freigegeben → Bezahlt)

  * Export als Excel mit Zusammenfassung, Einzelpositionen und Deal-Bezug

  * [Provisionen einrichten (Anleitung)](/guide/commissions/introduction)

  * [Provisionspläne](/guide/commissions/plans)

  * [Auszahlungen](/guide/commissions/payouts)
</Update>

<Update>
  ## Mahnwesen-E-Mail

  Kunden können jetzt eine oder mehrere **dedizierte Mahnwesen-E-Mail-Adressen** erhalten. Zahlungserinnerungen und Mahnungen werden damit gezielt an den richtigen Ansprechpartner gesendet, unabhängig von Rechnungs-E-Mails.

  **Neue Funktionen:**

  * **Mahnwesen-E-Mail** als eigenständige Zuordnung pro Kunde (Mehrfachauswahl)
  * **Automatische Fallback-Kette**: Mahnwesen-E-Mail → Rechnungs-E-Mail → Primär-E-Mail
  * **Neues E-Mail-Karten-Design**: Drei übersichtliche Dropdowns für Primär, Rechnung und Mahnwesen ersetzen die bisherige Radio-Button- und Toggle-Ansicht

  <Frame>
    <img alt="Neue E-Mail-Adressverwaltung" />
  </Frame>

  Bestehende Kunden ohne konfigurierte Mahnwesen-E-Mail verhalten sich wie bisher. Mahnungen werden an die Rechnungs-E-Mail gesendet.

  * [E-Mail-Adressen verwalten (Anleitung)](/guide/customers/email-management)
  * [Mahnwesen](/guide/dunning/introduction)
</Update>

<Update>
  ## Wallet-Aufladung

  Das Kundenguthaben (Wallet) kann jetzt gezielt aufgeladen werden — manuell über die Web-App oder automatisch per Regel.

  **Manuelle Aufladung:**

  * Neuer **Aufladen**-Button in der Wallet-Guthaben-Karte im Debitorenkonto
  * Betrag und Zahlungsmethode wählbar
  * Aufladungshistorie mit Status-Tracking (ausstehend, abgeschlossen, fehlgeschlagen)

  **Automatische Aufladung:**

  * Regeln pro Kunde und Währung konfigurierbar
  * Automatische Aufladung wenn Guthaben unter Schwellenwert fällt
  * Aktivieren/Deaktivieren, Fehlerzähler und Sicherheitsmechanismen

  Alle Funktionen sind auch über die API verfügbar.

  * [Wallet aufladen (Anleitung)](/guide/invoices/wallet-top-up)
  * [Wallet Top-Up API](/api-reference/guides/wallet-top-up)
  * [Kundenguthaben](/guide/invoices/wallet-balance)
</Update>

<Update>
  ## Kontobewegungen: camt.052/053 Import

  Bankbuchungen können jetzt direkt aus camt-Dateien importiert werden. Fynn unterstützt die Formate **camt.052** (Vormerkposten) und **camt.053** (Tagesabschluss) im ISO 20022 Standard.

  **Funktionen:**

  * **Drag & Drop Upload**: camt-XML-Datei einfach in den Import-Dialog ziehen
  * **Duplikaterkennung**: Bereits importierte Buchungen werden automatisch erkannt und übersprungen
  * **Automatische Zuordnung**: Importierte Buchungen werden anhand von Rechnungsnummer, Betrag und Kundendaten automatisch offenen Rechnungen zugeordnet
  * **Alle gängigen Versionen**: Unterstützung für camt-Versionen 002, 003, 004 und 008

  Der Import ist unter **Buchhaltung > Kontobewegungen** über den Button **camt importieren** erreichbar.

  * [Kontobewegungen Dokumentation](/guide/payments/bank-transactions)
</Update>

<Update>
  ## Externe Kundennummer (External ID)

  Kunden können jetzt mit einer externen ID (`externalId`) versehen werden. Dieses Feld ermöglicht die Zuordnung zu Kundennummern aus externen Systemen — z. B. ERP, CRM oder eigenen Anwendungen.

  **Anwendungsfälle:**

  * Verknüpfung mit bestehenden Kundennummern aus Drittsystemen
  * Referenzierung bei Usage-Event-Ingestion
  * Vereinfachte Migration und Synchronisation

  Das Feld ist optional und kann bei der Kundenanlage sowie -bearbeitung über Web-App und API gesetzt werden.

  * [Kunde erstellen API](/api-reference/customer/create-customer)
  * [Kundeneinstellungen](/guide/customers/settings)
</Update>


# Produkt-Updates April 2026
Source: https://docs.fynn.eu/changelog/2026-04

Neue Funktionen und Verbesserungen in Fynn im April 2026.

<Update>
  ## Periodengerechte Verbuchung auf Monatsebene

  Fynn kann Erlöse jetzt automatisch im richtigen Monat verbuchen — auch wenn die Rechnung erst im Folgemonat finalisiert wird.

  Erstellst du eine Rechnung mit Leistungszeitraum März am 5. April, wird der Erlös im März verbucht, solange der März noch offen ist. Liegt der Leistungszeitraum über eine Monatsgrenze, splittet Fynn den Betrag anteilig (30/360-Konvention) auf beide Monate auf.

  Das gilt für Rechnungen, Gutschriften und Stornorechnungen gleichermaßen.

  **Was sich ändert:**

  * Erlöse werden dem Monat des Leistungszeitraums zugeordnet, nicht dem Rechnungsdatum
  * In abgeschlossene Monate wird nicht rückwirkend gebucht
  * Auch Buchungen über den Geschäftsjahreswechsel hinweg werden automatisch korrekt aufgeteilt

  Mehr dazu im [User Guide](/guide/accounting/period-close).
</Update>

<Update>
  ## Rechnungskorrektur neu gedacht

  ### Ein Dialog für Korrigieren und Neu ausstellen

  Der bisherige Weg über separate Modals für Stornieren, Gutschreiben, Skonto und Korrigieren ist einem einzigen, unifizierten Dialog gewichen. Öffnest du eine Rechnung und klickst auf **Korrigieren**, siehst du jetzt:

  * Die vollständige Positionsliste mit Restmengen und bereits durchgeführten Korrekturen pro Position.
  * Eine Live-Vorschau rechts, die in Echtzeit zeigt, welche Belege entstehen, mit welchen Beträgen und wie sie sich auf offenen Betrag und Kundenguthaben auswirken.
  * Den Modus-Umschalter **Korrigieren / Neu ausstellen**. Korrigieren erzeugt wie bisher Gutschriften und Stornorechnungen. Neu ausstellen gutschreibt die Originalrechnung und stellt sie mit korrigierten Werten sofort neu aus — in einem Schritt, als eine Transaktion.

  <Frame>
    <img alt="Der neue Korrektur-Dialog mit Positionsauswahl und Live-Vorschau" />
  </Frame>

  ### Neu ausstellen: Rechnungen reparieren ohne Datenschaden

  Bisher war der Weg zur korrigierten Rechnung umständlich: gutschreiben, duplizieren, manuell anpassen, finalisieren. Dabei gingen Produkt-, Abo- und Steuerreferenzen verloren, was MRR- und Umsatzberichte verfälschte.

  Mit **Neu ausstellen** passiert das alles atomar und referenzerhaltend:

  * Menge, Stückpreis, Rabatt, Beschreibung und Leistungszeitraum jeder Position sind überschreibbar. Alles andere wird 1:1 übernommen.
  * Produkt-, Abo-, Einheiten- und Steuergruppen-Referenzen bleiben auf der Ersatzrechnung erhalten. MRR, ARR und Revenue Recognition bleiben konsistent.
  * Die Rechnungsadresse kann gegen eine andere Adresse desselben Kunden getauscht werden.
  * Die Verteilung — Verrechnung mit offenem Betrag oder Kundenguthaben — wählt Fynn anhand des Zahlungsstatus automatisch. Bei bezahlten Rechnungen wird die Ersatzrechnung synchron gegen das entstehende Kundenguthaben verrechnet.
  * Ergeben sich gemischte Vorzeichen, teilt Fynn automatisch in Ersatzrechnung und Ersatz-Gutschrift.

  ### Batch-Bearbeitung für mehrere Positionen

  Bei mehreren ausgewählten Positionen erscheint eine Batch-Leiste. Damit lassen sich Leistungszeitraum, Menge oder Rabatt in einem Schritt auf alle ausgewählten Positionen anwenden — Preise werden bei Zeitraum-Änderungen automatisch proportional angepasst.

  ### Finanz-Vorschau in Echtzeit

  Die rechte Seite des Dialogs zeigt jederzeit:

  * Jeden entstehenden Beleg mit Typ, Positionen, Netto/Steuer/Brutto und der entstehenden Verteilung.
  * Den offenen Betrag der Rechnung vor und nach der Korrektur.
  * Bei Neu ausstellen zusätzlich die drei Kennzahlen Gutschrift, Ersatzrechnung und Netto-Differenz.

  Erst mit Klick auf **Korrektur durchführen** bzw. **Neu ausstellen** werden Belege persistiert. Davor kannst du beliebig viel ausprobieren, ohne Nebenwirkungen.

  ### Audit-Trail auf Positionsebene

  Jede Korrektur wird als `InvoiceCorrectionAction` auf Positionsebene aufgezeichnet. Bereits korrigierte Positionen können nicht doppelt korrigiert werden und zeigen ihre Historie direkt im Dialog — inklusive Belegnummer und Datum der vorherigen Korrektur.
</Update>

<Update>
  ## Neue Endpoints für Korrektur und Neu-Ausstellung

  Die neuen Funktionen stehen vollständig auch über die REST-API zur Verfügung:

  * `GET  /invoices/{id}/correct/positions` – korrigierbare Positionen auflisten
  * `POST /invoices/{id}/correct/preview` – Korrektur-Vorschau (seiteneffektfrei)
  * `POST /invoices/{id}/correct` – Korrektur ausführen
  * `POST /invoices/{id}/reissue/preview` – Reissue-Vorschau (seiteneffektfrei)
  * `POST /invoices/{id}/reissue` – Reissue ausführen

  Preview und Execute teilen sich dasselbe Request-Schema. Was die Vorschau zeigt, entsteht bei der Ausführung.

  Die bestehenden Endpoints `POST /invoices/{id}/cancel`, `/credit` und `/duplicate` bleiben erhalten und werden **nicht** abgekündigt. Sie bleiben der schlanke Weg für Ein-Klick-Aktionen auf der ganzen Rechnung. Für granulare Korrekturen mit Positionsauswahl, Overrides und Vorschau gibt es jetzt den neuen Pfad.

  <Info>
    Details und Code-Beispiele findest du unter [Invoice Correction API](/guide/developers/invoice-correction). Die Nutzer-Dokumentation liegt unter [Korrigieren & Neu ausstellen](/guide/invoices/correct-and-reissue).
  </Info>
</Update>


# Produkt-Updates Juli 2026
Source: https://docs.fynn.eu/changelog/2026-07

Steuerberater-Portal, neue Auswertungen, Wallet-Einzugsplan und Auszahlungen, automatische Bearbeitung von Rücklastschriften, Postversand, persönliche API-Token und MCP-Server, dazu der neue Angebots-Editor, Vertriebskanäle und vertikale Steuerberechnung.

<Update>
  ## Ein eigenes Portal für deine Steuerberatung

  Deine Steuerberatung bekommt jetzt einen eigenen Zugang zu Fynn, ganz ohne Zugriff auf dein operatives Konto. Nach einer Einladung meldet sie sich per Magic-Link an, also über einen Anmeldelink per E-Mail und ohne eigenes Passwort.

  Im Portal liegen Belege, DATEV-Auswertungen und die relevanten Buchhaltungsdaten an einem Ort. Ein geführter Einrichtungs-Assistent klärt zu Beginn Kontenrahmen, Nummernkreise und Wirtschaftsjahr, damit der DATEV-Export von Anfang an passt.

  Mehr dazu unter [Steuerberater-Portal](/guide/accounting/tax-advisor-portal).
</Update>

<Update>
  ## Überarbeitete Umsatz- und Analyseansichten

  Die Auswertungen wurden von Grund auf überarbeitet. Wiederkehrender Umsatz (MRR), Kohorten und eine Cash-Sicht zeigen jetzt genauer, wie sich dein Geschäft entwickelt.

  Die Kennzahlen beruhen auf den echten Rechnungs- und Zahlungsstatus und dem Zeitpunkt der Finalisierung. So stimmen Umsatz, Zahlungen und Buchhaltung zuverlässiger überein.

  Mehr dazu unter [Auswertungen](/guide/analytics/dashboard).
</Update>

<Update>
  ## Zugänge pro Benutzer und Anbindung an KI-Tools

  Jeder Benutzer kann jetzt eigene persönliche API-Token verwalten. Abgelaufene Token werden bei der Anmeldung zuverlässig abgewiesen.

  Zusätzlich lässt sich Fynn über den MCP-Server direkt mit KI-Tools verbinden. Rechnungen, Debitoren, Zahlungen und der DATEV-Export stehen dort als Werkzeuge bereit, die dein KI-Client aufruft.

  Mehr dazu unter [MCP-Server](/guide/developers/mcp-server).
</Update>

<Update>
  ## Mehr Kontrolle über das fertige Angebot

  Die Anzeigesprache eines Angebots lässt sich jetzt frei einstellen. AGB und Vertragsbedingungen erscheinen auf der ersten Seite und im PDF.

  Angebote lassen sich als PDF herunterladen, Dateianhänge werden dabei korrekt dargestellt.

  Mehr dazu in der [Angebots-Dokumentation](/v2-offers-api/introduction).
</Update>

<Update>
  ## Kunden pflegen ihre Lieferadresse selbst

  Kunden können ihre Lieferadresse jetzt direkt im Kundenbereich ändern. Das entlastet dein Team und hält die Adressdaten aktuell.

  Mehr dazu unter [Kundenbereich](/guide/customers/customer-portal).
</Update>

<Update>
  ## Kündigen in einem klaren Schritt

  Der Kündigungsprozess wurde überarbeitet und läuft jetzt in einem in sich abgeschlossenen Schritt ab. Die Kündigung wird als eine Transaktion ausgeführt, das vermeidet Zwischenzustände.

  Mehr dazu unter [Abonnement kündigen](/guide/subscriptions/cancel).
</Update>

<Update>
  ## Verlässlichere Provisionsdaten

  Rechnungen und Gutschriften aus Xentral werden jetzt täglich automatisch abgeglichen. Auszahlungen und Verdienste sind übersichtlicher dargestellt, und der Export wurde zuverlässiger.

  Mehr dazu unter [Provisionen](/guide/commissions/introduction).
</Update>

<Update>
  ## Weitere Verbesserungen

  * Zentrale Ansichten sind für die Nutzung auf dem Smartphone optimiert.
  * Checkout-Links öffnen spürbar schneller.
  * Mehrsprachige Fußzeilen in Rechnungsvorlagen bleiben beim Speichern zuverlässig erhalten, und ein Hinweis warnt vor ungespeicherten Änderungen beim Wechsel der Sprache.
  * Abgelaufene gekündigte Abonnements werden jetzt korrekt beendet.
  * Nutzungsbasierte Rechnungen zeigen die korrekte Einheit an.
  * Die Belegliste zeigt zugehörige Referenzen wieder in voller Tiefe an.
</Update>

<Update>
  ## Ein neuer Angebots-Editor

  Der Angebots-Editor wurde vollständig überarbeitet. Die Oberfläche ist übersichtlicher strukturiert, die Positionsverwaltung arbeitet zuverlässiger, und eine Live-Vorschau zeigt jederzeit, wie das Angebot beim Empfänger ankommt.

  Der gesamte Ablauf vom Entwurf bis zur Unterschrift bleibt in einer Ansicht. Entwürfe lassen sich anlegen, duplizieren, archivieren und löschen. Das fertige Angebot wird als gestaltetes PDF mit deinem Briefkopf ausgegeben.

  Mehr dazu in der [Angebots-Dokumentation](/v2-offers-api/introduction).
</Update>

<Update>
  ## Flexible Angebotsannahme

  Angebote lassen sich jetzt auf mehreren Wegen annehmen, passend zum jeweiligen Abschluss: per rechtsverbindlicher E-Signatur mit einem oder mehreren Unterzeichnern und optionalem Gegenzeichner, per Klick-Annahme oder als manuelle Annahme durch dein Team, wenn bereits außerhalb von Fynn unterschrieben wurde.

  Bei der manuellen Annahme kann das unterzeichnete Dokument hinterlegt werden. Angebote lassen sich zudem an weitere Empfänger weiterleiten. Nach der Annahme wird das Angebot automatisch in ein Abonnement überführt und gegen weitere Änderungen gesperrt.

  Mehr dazu unter [Annahme und Signatur](/v2-offers-api/acceptance-and-signing).
</Update>

<Update>
  ## Freigabeprozesse für Angebote

  Für Angebote lassen sich jetzt Freigaberegeln definieren, etwa ab einem festgelegten Rabatt-Schwellwert. Trifft eine Regel zu, wird das Angebot vor dem Versand automatisch zur Freigabe vorgelegt.

  Die zuständigen Freigeber werden benachrichtigt und können freigeben oder ablehnen. Der aktuelle Freigabestatus ist jederzeit direkt am Angebot einsehbar.

  Mehr dazu unter [Freigaben](/v2-offers-api/freigaben).
</Update>

<Update>
  ## Vertragsstart und Abrechnung in einem Schritt

  Beim Überführen eines Angebots in ein Abonnement lässt sich der Vertragsbeginn direkt auf „Ab Abschluss“ setzen. Der Abrechnungsstart übernimmt dieses Datum automatisch.

  Ein zusätzlicher API-Aufruf zum nachträglichen Angleichen von Vertrags- und Abrechnungsstart entfällt damit. Für Abschlüsse, die exakt zum Annahme- oder Go-Live-Datum starten und abgerechnet werden sollen, ist das der direkte Weg.

  Mehr dazu im [Angebots-Editor](/v2-offers-api/editor).
</Update>

<Update>
  ## Vertriebskanäle für mehrere Marken

  Mehrere Marken lassen sich jetzt über Vertriebskanäle innerhalb einer Organisation abbilden. Jeder Kanal tritt mit eigenem Logo, eigenen Farben, eigener Domain, eigenen Zahlungsmethoden und eigenem Kundenbereich auf.

  Die Daten bleiben dabei gemeinsam: Kunden, Abonnements, Rechnungen und Produkte werden weiterhin zentral verwaltet. Angebote und Checkout-Links lassen sich einem Kanal zuordnen und erscheinen im jeweiligen Branding.

  Mehr dazu unter [Vertriebskanäle](/guide/tenant/sales-channels).
</Update>

<Update>
  ## Pläne in neuer Version

  Die Pläne stehen in einer neuen Version zur Verfügung. Über die Fynn API V2 modellierst du dein Angebot als Pläne mit Tarifstufen, Up- und Downgrades sowie integriertem Checkout.

  Die neue Fassung ist klarer strukturiert und lässt sich einfacher in eigene Oberflächen einbinden.

  Mehr dazu in der [Pläne-Dokumentation](/v2-plans-api/introduction).
</Update>

<Update>
  ## Vertikale Steuerberechnung

  Die Umsatzsteuer lässt sich jetzt wahlweise horizontal (pro Position) oder vertikal (auf Belegebene je Steuersatz) berechnen. Die vertikale Methode rundet je Steuersatz einmal auf die Summe und vermeidet so Rundungsdifferenzen von wenigen Cent bei Belegen mit vielen Positionen.

  Das Verfahren ist konform zur E-Rechnung (EN 16931): Der ausgewiesene Steuerbetrag entspricht exakt der Summe der Buchungen. Die Methode wird in den Einstellungen unter Buchhaltung gewählt.

  Mehr dazu unter [Steuerberechnung](/guide/accounting/tax-calculation).
</Update>

<Update>
  ## Eigener Buchungsschlüssel für PRAP-Buchungen

  PRAP-Buchungen (passive Rechnungsabgrenzung) wurden bisher fest mit Buchungsschlüssel 40 erzeugt. Ab sofort lässt sich ein eigener Buchungsschlüssel hinterlegen.

  Damit passt der DATEV-Export zum jeweiligen Kontenrahmen und der Buchungsstapel wird korrekt übernommen.

  Mehr dazu unter [PRAP-Buchungsschlüssel](/guide/accounting/prap#prap-buchungsschlüssel).
</Update>


# KI-Assistent
Source: https://docs.fynn.eu/guide/ai-assistant/introduction

Nutze den integrierten KI-Assistenten, um schnell Informationen zu finden, Daten abzufragen und durch die Plattform zu navigieren.

Der KI-Assistent in Fynn hilft dir, schnell Antworten auf Fragen zu deinen Kunden, Belegen, Zahlungen und Abonnements zu finden – direkt in der App, ohne manuelles Suchen und Filtern.

## Assistent öffnen

Klicke auf das **Chat-Symbol** unten rechts in der App oder nutze den Tastaturkürzel, um den Assistenten zu öffnen.

<Tip>
  Der Assistent erkennt automatisch, auf welcher Seite du dich befindest. Wenn du z.B. auf einer Kundendetailseite bist, bezieht er Fragen direkt auf diesen Kunden.
</Tip>

## Was kann der Assistent?

<CardGroup>
  <Card title="Daten abfragen" icon="magnifying-glass">
    Suche nach Kunden, Belegen, Abonnements, Zahlungen und mehr – in natürlicher Sprache.
  </Card>

  <Card title="Kundeneinstellungen" icon="sliders">
    Kundeneinstellungen abfragen und ändern – Mahnwesen, Abrechnung, Rechnungsfreigabe und Zahlungsziel.
  </Card>

  <Card title="Navigation" icon="compass">
    Öffne Seiten, Detailansichten oder Erstellungsdialoge per Sprachbefehl.
  </Card>

  <Card title="Berichte erstellen" icon="chart-bar">
    Lass dir Berichte generieren und per E-Mail zusenden.
  </Card>

  <Card title="Dokumentation" icon="book">
    Stelle Fragen zur Plattform und erhalte Antworten aus der Dokumentation.
  </Card>
</CardGroup>

***

## Beispiel-Anfragen

Hier findest du typische Fragen, die du dem Assistenten stellen kannst, gruppiert nach Anwendungsfall.

### Kunden finden

| Anfrage                                       | Was passiert                                      |
| --------------------------------------------- | ------------------------------------------------- |
| "Suche Kunde Müller"                          | Findet alle Kunden mit dem Namen Müller           |
| "Zeige mir die E-Mail von Kunde D26-00100043" | Ruft die Kundendetails anhand der Kundennummer ab |
| "Wie viele aktive Kunden haben wir?"          | Zählt aktive Kunden über das Gesamtergebnis       |

### Belege & Rechnungen

| Anfrage                                     | Was passiert                                    |
| ------------------------------------------- | ----------------------------------------------- |
| "Offene Rechnungen"                         | Listet unbezahlte Belege                        |
| "Überfällige Belege von Kunde Müller"       | Zeigt Mahnübersicht für einen bestimmten Kunden |
| "Zeige Belege aus dem letzten Monat"        | Filtert Belege nach Finalisierungsdatum         |
| "Was ist der Status von Beleg RE-2024-001?" | Ruft Belegdetails ab                            |

### Zahlungen & Transaktionen

| Anfrage                                        | Was passiert                                                                                                                                                                                                                                            |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Wann hat der Kunde zuletzt bezahlt?"          | **Letzte-Zahlung-Workflow**: Sucht die letzte Zahlungstransaktion des Kunden und zeigt Status, Zahlungsmethode, Gateway, Betrag, Datum und verknüpften Beleg. Bei fehlgeschlagenen Zahlungen wird zusätzlich die letzte erfolgreiche Zahlung angezeigt. |
| "Was ist die letzte Zahlung von D26-00100030?" | Wie oben – der Kunde wird zuerst per Kundennummer aufgelöst                                                                                                                                                                                             |
| "Wie wurde Beleg RE-2024-001 bezahlt?"         | **Belegzahlungen-Workflow**: Listet alle Transaktionen zu einem Beleg                                                                                                                                                                                   |
| "Welche Zahlungen gibt es zu diesem Beleg?"    | Zeigt Transaktionen zum aktuellen Beleg (auf der Belegdetailseite)                                                                                                                                                                                      |
| "Zeige fehlgeschlagene Zahlungen"              | Filtert Transaktionen nach Status                                                                                                                                                                                                                       |

<Info>
  **Transaktions-Karten** zeigen dir auf einen Blick: Zahlungsanbieter (z.B. Stripe, GoCardless), Status (Erfasst, Ausstehend, Fehlgeschlagen), Betrag, Datum und verknüpften Beleg. Du kannst auf eine Transaktion klicken, um direkt zum Beleg zu springen.
</Info>

<Tip>
  Mehr Details zu den Zahlungs-Workflows findest du unter [Workflows](/guide/ai-assistant/workflows).
</Tip>

### Kundeneinstellungen

| Anfrage                                                       | Was passiert                                                                      |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| "Ist das Mahnwesen für Kunde Müller aktiv?"                   | Ruft die Einstellungen ab und zeigt den Dunning-Status                            |
| "Welche Einstellungen hat Kunde D26-00100043?"                | Zeigt alle Einstellungen (Mahnwesen, Abrechnung, Rechnungsfreigabe, Zahlungsziel) |
| "Deaktiviere das Mahnwesen für Kunde Müller"                  | Zeigt eine Bestätigungskarte und deaktiviert nach Bestätigung                     |
| "Aktiviere die manuelle Rechnungsfreigabe für Kunden A und B" | Ändert die Einstellung für mehrere Kunden gleichzeitig                            |
| "Setze das Zahlungsziel für Kunde Müller auf 30 Tage"         | Ändert das Zahlungsziel nach Bestätigung                                          |

<Tip>
  Details zu allen unterstützten Einstellungsänderungen findest du unter [Kundeneinstellungen](/guide/ai-assistant/customer-settings).
</Tip>

### Abonnements

| Anfrage                                    | Was passiert                         |
| ------------------------------------------ | ------------------------------------ |
| "Aktive Abonnements von Kunde Müller"      | Filtert Abos nach Kunde und Status   |
| "Welche Testphasen laufen diese Woche ab?" | Nutzt den Filter `trialEndsBefore`   |
| "Abos die in 30 Tagen enden"               | Nutzt den Filter `contractEndBefore` |

### Navigation

| Anfrage                       | Was passiert                                                          |
| ----------------------------- | --------------------------------------------------------------------- |
| "Öffne Kunde Müller"          | Navigiert zur Kundendetailseite (bei Mehrdeutigkeit wird nachgefragt) |
| "Neuen Kunden anlegen"        | Öffnet den Erstellungsdialog                                          |
| "Gehe zu Einstellungen"       | Navigiert zur Einstellungsseite                                       |
| "Öffne Transaktionsübersicht" | Navigiert zu `/finance/transactions`                                  |

### Berichte

| Anfrage                                  | Was passiert                                                                                  |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| "Erstelle einen Umsatz-Bericht für 2025" | Schlägt den Bericht vor, erfasst Parameter automatisch und zeigt eine Bestätigungskarte       |
| "Ich brauche eine Offene-Posten-Liste"   | Generiert den OPOS-Bericht (keine Parameter nötig – direkte Bestätigung)                      |
| "Zahlungsbericht für Januar 2026"        | Erstellt einen Zahlungsbericht, fragt gezielt nach fehlenden Parametern (z.B. Zahlungsstatus) |
| "PRAP-Bericht bis Ende 2025"             | Erstellt den PRAP-Bericht mit Stichtag 31.12.2025                                             |
| "Exportiere die re:cap-Berichte"         | Generiert die re:cap-Berichte (keine Parameter nötig)                                         |

<Warning>
  Berichte werden erst nach deiner expliziten Bestätigung über den **Bestätigen-Button** generiert. Ein einfaches "Ja" im Chat reicht nicht aus.
</Warning>

<Tip>
  Details zum vollständigen Ablauf mit Parametererfassung, Validierung und Bestätigung findest du unter [Berichterstellung](/guide/ai-assistant/reports).
</Tip>

### Dokumentation & Hilfe

| Anfrage                              | Was passiert                                                         |
| ------------------------------------ | -------------------------------------------------------------------- |
| "Wie erstelle ich eine Rechnung?"    | Sucht in der Dokumentation und gibt eine Schritt-für-Schritt-Antwort |
| "Was bedeutet Mahnstufe?"            | Erklärt den Begriff aus der Dokumentation                            |
| "Wie funktioniert SEPA-Lastschrift?" | Liefert eine Erklärung zur Zahlungsmethode                           |

***

## Seitenkontext

Der Assistent erkennt, auf welcher Seite du dich befindest, und bezieht seine Antworten darauf:

| Seite                             | Verhalten                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Kundendetail**                  | Fragen beziehen sich automatisch auf diesen Kunden. "Offene Belege" → zeigt nur Belege dieses Kunden. |
| **Belegdetail**                   | "Wie wurde dieser Beleg bezahlt?" → zeigt Transaktionen zu genau diesem Beleg.                        |
| **Abo-Detail**                    | Fragen beziehen sich auf dieses Abonnement und den zugehörigen Kunden.                                |
| **Listen** (Kunden, Belege, Abos) | Fragen beziehen sich auf die jeweilige Entität allgemein.                                             |
| **Dashboard**                     | Kein spezieller Kontext – der Assistent fragt bei Bedarf nach.                                        |

<Tip>
  Du kannst den Seitenkontext jederzeit übersteuern. Auch auf einer Kundendetailseite kannst du fragen: "Zeige mir alle überfälligen Belege" – der Assistent erkennt, dass du eine allgemeine Abfrage meinst.
</Tip>

***

## Mehrdeutige Ergebnisse

Wenn der Assistent bei einer Suche mehrere passende Ergebnisse findet (z.B. mehrere Kunden mit dem Namen "Müller"), zeigt er dir **klickbare Auswahloptionen** an, anstatt einfach eines auszuwählen.

<Steps>
  <Step title="Frage stellen">
    Du fragst z.B. "Wann hat Kunde Müller zuletzt bezahlt?"
  </Step>

  <Step title="Auswahl angezeigt">
    Der Assistent findet 3 Kunden mit dem Namen Müller und zeigt dir Karten mit Name, Kundennummer und E-Mail.
  </Step>

  <Step title="Auswahl treffen">
    Du klickst auf den richtigen Kunden – der Assistent setzt den Workflow automatisch fort.
  </Step>
</Steps>

***

## Tipps für bessere Ergebnisse

<AccordionGroup>
  <Accordion title="Sei spezifisch">
    Je genauer deine Frage, desto besser das Ergebnis. "Offene Belege von Kunde D26-00100043" ist besser als "Offene Rechnungen".
  </Accordion>

  <Accordion title="Nutze den Seitenkontext">
    Auf einer Kundendetailseite reicht "Letzte Zahlung?" – der Assistent weiß, welcher Kunde gemeint ist.
  </Accordion>

  <Accordion title="Kundennummern verwenden">
    Bei häufigen Namen (z.B. "Müller") ist die Kundennummer eindeutiger und vermeidet Rückfragen.
  </Accordion>

  <Accordion title="Berichte für komplexe Auswertungen">
    Für Dinge wie "Umsatzentwicklung der Top-10-Kunden" ist ein Bericht besser geeignet als eine Chat-Antwort. Der Assistent schlägt das automatisch vor.
  </Accordion>
</AccordionGroup>


# Aggregationstypen
Source: https://docs.fynn.eu/guide/catalogue/measurements/aggregation-types/overview

Wie Nutzungsdaten zusammengefasst werden - Summe, Anzahl, Maximum und mehr.

Der Aggregationstyp bestimmt, wie die eingehenden Events zu einem Abrechnungswert zusammengefasst werden.

## Übersicht

| Typ              | Braucht Feld? | Beschreibung                      |
| ---------------- | ------------- | --------------------------------- |
| **Anzahl**       | Nein          | Zählt die Anzahl der Events       |
| **Summe**        | Ja            | Addiert die Werte eines Feldes    |
| **Maximum**      | Ja            | Nimmt den höchsten Wert           |
| **Minimum**      | Ja            | Nimmt den niedrigsten Wert        |
| **Durchschnitt** | Ja            | Berechnet den Mittelwert          |
| **Eindeutig**    | Ja            | Zählt einzigartige Werte          |
| **Letzter Wert** | Ja            | Nimmt den zuletzt gemeldeten Wert |

***

## Anzahl (Count)

Zählt, wie oft ein Event aufgetreten ist. Kein Feld nötig.

**Beispiel:** API-Aufrufe zählen

| Event        | Aggregation   |
| ------------ | ------------- |
| `api_call`   | +1            |
| `api_call`   | +1            |
| `api_call`   | +1            |
| **Ergebnis** | **3 Aufrufe** |

**Wann nutzen:**

* API-Aufrufe
* Logins
* Transaktionen
* Nachrichten gesendet

***

## Summe (Sum)

Addiert die Werte eines bestimmten Feldes.

**Beispiel:** Token-Verbrauch summieren (Feld: `tokens`)

| Event        | tokens | Aggregation    |
| ------------ | ------ | -------------- |
| `ai_request` | 150    | +150           |
| `ai_request` | 300    | +300           |
| `ai_request` | 50     | +50            |
| **Ergebnis** |        | **500 Tokens** |

**Wann nutzen:**

* Token-/Credit-Verbrauch
* Datenvolumen (GB)
* Transaktionsbeträge
* E-Mails versendet

***

## Maximum (Max)

Nimmt den höchsten Wert im Abrechnungszeitraum.

**Beispiel:** Maximale gleichzeitige Nutzer (Feld: `active_users`)

| Event        | active\_users | Aggregation   |
| ------------ | ------------- | ------------- |
| `user_count` | 10            | max = 10      |
| `user_count` | 25            | max = 25      |
| `user_count` | 18            | max = 25      |
| **Ergebnis** |               | **25 Nutzer** |

**Wann nutzen:**

* Gleichzeitige Nutzer (Seats)
* Peak-Speicherverbrauch
* Maximale Bandbreite
* Höchste CPU-Auslastung

***

## Minimum (Min)

Nimmt den niedrigsten Wert im Abrechnungszeitraum.

**Beispiel:** Minimaler Kontostand (Feld: `balance`)

| Event           | balance | Aggregation |
| --------------- | ------- | ----------- |
| `balance_check` | 1000    | min = 1000  |
| `balance_check` | 500     | min = 500   |
| `balance_check` | 750     | min = 500   |
| **Ergebnis**    |         | **500**     |

**Wann nutzen:**

* Mindestguthaben
* Niedrigste Verfügbarkeit
* Minimale Ressourcennutzung

***

## Durchschnitt (Average)

Berechnet den Mittelwert aller gemeldeten Werte.

**Beispiel:** Durchschnittliche Response Time (Feld: `response_ms`)

| Event        | response\_ms | Aggregation |
| ------------ | ------------ | ----------- |
| `api_call`   | 100          |             |
| `api_call`   | 150          |             |
| `api_call`   | 200          |             |
| **Ergebnis** |              | **150 ms**  |

**Wann nutzen:**

* Durchschnittliche Verarbeitungszeit
* Mittlere Dateigröße
* Durchschnittlicher Verbrauch pro Request

***

## Eindeutig (Unique Count)

Zählt, wie viele unterschiedliche Werte ein Feld hatte.

**Beispiel:** Aktive Nutzer im Monat (Feld: `user_id`)

| Event        | user\_id | Aggregation                   |
| ------------ | -------- | ----------------------------- |
| `login`      | user-A   | 1 eindeutig                   |
| `login`      | user-B   | 2 eindeutig                   |
| `login`      | user-A   | 2 eindeutig (bereits gezählt) |
| `login`      | user-C   | 3 eindeutig                   |
| **Ergebnis** |          | **3 aktive Nutzer**           |

**Wann nutzen:**

* Monthly Active Users (MAU)
* Eindeutige Kunden
* Verschiedene verwendete Features
* Anzahl verschiedener Produkte

***

## Letzter Wert (Latest)

Nimmt den zuletzt gemeldeten Wert. Setzt sich nicht zurück nach Abrechnung.

**Beispiel:** Aktueller Speicherverbrauch (Feld: `storage_gb`)

| Event           | storage\_gb | Aggregation  |
| --------------- | ----------- | ------------ |
| `storage_check` | 50          | letzter = 50 |
| `storage_check` | 55          | letzter = 55 |
| `storage_check` | 52          | letzter = 52 |
| **Ergebnis**    |             | **52 GB**    |

**Wann nutzen:**

* Aktueller Speicherverbrauch
* Aktuelle Seat-Anzahl
* Lizenzstand
* Persistente Werte, die nicht summiert werden

<Note>
  **Wichtig:** Bei "Letzter Wert" wird der Wert **nicht** nach jeder Abrechnung auf 0 zurückgesetzt. Der letzte gemeldete Wert bleibt bestehen.
</Note>

***

## Vergleich: Wann welchen Typ?

| Use Case             | Aggregation  | Feld           |
| -------------------- | ------------ | -------------- |
| API-Calls zählen     | Anzahl       | -              |
| Token summieren      | Summe        | `tokens`       |
| Speicher (aktuell)   | Letzter Wert | `storage_gb`   |
| Speicher (Peak)      | Maximum      | `storage_gb`   |
| Aktive User (unique) | Eindeutig    | `user_id`      |
| Seats (Peak)         | Maximum      | `active_seats` |
| Response Time (Ø)    | Durchschnitt | `response_ms`  |


# Nutzungsmetriken
Source: https://docs.fynn.eu/guide/catalogue/measurements/billable-metrics

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 alt="Nutzungsbasierte Abrechnung am Produkt konfigurieren" />
    </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 alt="Nutzungsmetriken im Abonnement" />
</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 alt="Metrik Details" />
</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>
  <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>


# Nutzungsbasierte Abrechnung
Source: https://docs.fynn.eu/guide/catalogue/measurements/introduction

Rechne nach tatsächlichem Verbrauch ab - fair und transparent.

Mit nutzungsbasierter Abrechnung zahlst du nur, was du wirklich nutzt. Ideal für APIs, SaaS-Produkte, AI-Services oder Cloud-Dienste.

## Wie funktioniert's?

<Steps>
  <Step title="Nutzungsmetrik definieren">
    Du legst fest, was gemessen wird: Welches Ereignis? Wie aggregieren?

    Beispiel: "Zähle alle `ai_request` Ereignisse und summiere das Feld `tokens_used`"
  </Step>

  <Step title="Nutzungsereignisse senden">
    Deine Anwendung sendet Nutzungsereignisse an Fynn - per API oder CSV-Import.

    ```json theme={null}
    {
      "eventName": "ai_request",
      "properties": { "tokens_used": 350, "model": "gpt-4" }
    }
    ```
  </Step>

  <Step title="Automatische Abrechnung">
    Am Ende des Abrechnungszeitraums erstellt Fynn automatisch eine Rechnung basierend auf der tatsächlichen Nutzung.
  </Step>
</Steps>

***

## Beispiele

<CardGroup>
  <Card title="AI / LLM" icon="microchip-ai">
    Token-Verbrauch pro Modell, API-Aufrufe, Bildgenerierungen
  </Card>

  <Card title="API Services" icon="code">
    API-Calls, Datentransfer, Webhook-Zustellungen
  </Card>

  <Card title="Cloud / Hosting" icon="cloud">
    Speicherplatz, Bandbreite, Compute-Zeit
  </Card>

  <Card title="Kommunikation" icon="envelope">
    E-Mails, SMS, Push-Notifications
  </Card>
</CardGroup>

***

## Die Bausteine

| Baustein             | Beschreibung                                                    |
| -------------------- | --------------------------------------------------------------- |
| **Nutzungsmetrik**   | Definiert, was und wie gemessen wird                            |
| **Nutzungsereignis** | Einzelnes Ereignis aus deiner App                               |
| **Aggregation**      | Wie Ereignisse zusammengefasst werden (Summe, Anzahl, Max, ...) |
| **Filter**           | Welche Ereignisse berücksichtigt werden                         |
| **Gruppierung**      | Aufschlüsselung nach Dimensionen (z.B. pro Modell)              |

***

## Dokumentation

<CardGroup>
  <Card title="Nutzungsmetriken" icon="chart-line" href="/guide/catalogue/measurements/billable-metrics">
    Erstelle und konfiguriere Nutzungsmetriken mit Filtern und Gruppierung.
  </Card>

  <Card title="Nutzungsereignisse senden" icon="paper-plane" href="/guide/catalogue/usage-events-import">
    Sende Nutzungsereignisse per API oder importiere sie per CSV.
  </Card>

  <Card title="Aggregationstypen" icon="calculator" href="/guide/catalogue/measurements/aggregation-types/overview">
    Verstehe Summe, Anzahl, Maximum und andere Aggregationstypen.
  </Card>

  <Card title="API Referenz" icon="code" href="/api-reference/guides/collect-usage-data">
    Technische Details zur Nutzungsereignisse-API.
  </Card>
</CardGroup>


# Nutzungsbasierte Abrechnung verstehen
Source: https://docs.fynn.eu/guide/catalogue/measurements/usage-based-billing

Erfahre, wie die nutzungsbasierte Abrechnung funktioniert und wie du die Nutzungsdaten interpretierst

<Frame>
  <img alt="Nutzungsbasierte Abrechnung" />
</Frame>

Die nutzungsbasierte Abrechnung ermöglicht es dir, Kunden basierend auf ihrer tatsächlichen Nutzung abzurechnen. Anstatt eines festen monatlichen Preises werden Kunden nur für das berechnet, was sie tatsächlich verwenden.

## Wie funktioniert die nutzungsbasierte Abrechnung?

### Grundprinzip

1. **Nutzungsereignisse werden erfasst**: Deine Anwendung sendet Nutzungsereignisse (z.B. API-Aufrufe, gesendete E-Mails, Speicherplatz) an Fynn
2. **Ereignisse werden aggregiert**: Fynn sammelt alle Ereignisse und berechnet die Gesamtnutzung basierend auf dem Aggregationstyp
3. **Abrechnung erfolgt nachträglich**: Am Ende des Abrechnungszeitraums wird die tatsächliche Nutzung abgerechnet

### Abrechnungsmodus: Nachträglich (Arrears)

Im Gegensatz zu festen Abonnements, die im Voraus (Advance) abgerechnet werden, erfolgt die nutzungsbasierte Abrechnung **nachträglich (Arrears)**:

* **Feste Abonnements**: Du zahlst am 1. Januar für den gesamten Januar im Voraus
* **Nutzungsbasierte Abrechnung**: Du zahlst am 1. Februar für die Nutzung im Januar

## Was zeigen die Metriken?

Die angezeigten Metriken zeigen die **aggregierten Nutzungswerte für noch nicht abgerechnete Ereignisse**. Das bedeutet:

* ✅ **Enthalten**: Alle Nutzungsereignisse, die noch nicht auf einer Rechnung stehen
* ❌ **Nicht enthalten**: Bereits abgerechnete Ereignisse (die bereits auf einer Rechnung erscheinen)

### Beispiel

Angenommen, du hast ein Produkt "API-Aufrufe" mit nutzungsbasierter Abrechnung:

```
01.01.2026: 100 API-Aufrufe → noch nicht abgerechnet
15.01.2026: 200 API-Aufrufe → noch nicht abgerechnet
01.02.2026: Rechnung wird erstellt für Januar → 300 API-Aufrufe werden abgerechnet
02.02.2026: 50 API-Aufrufe → noch nicht abgerechnet
```

**Angezeigte Metrik am 02.02.2026:**

* **Menge**: 50 API-Aufrufe (nur die noch nicht abgerechneten)
* **Zeitraum**: 01.02.2026 bis 02.02.2026

## Den Zeitraum verstehen

Jede Metrik zeigt einen **Zeitraum** an, z.B. "01.01.2026 bis 01.02.2026". Dieser Zeitraum hat eine klare Bedeutung:

### Startdatum

Das **Startdatum** ist das Datum, ab dem noch nicht abgerechnete Ereignisse erfasst werden:

* **Wenn bereits abgerechnet wurde**: Das Datum der letzten Abrechnung (z.B. 01.01.2026)
* **Wenn noch nie abgerechnet wurde**: Das Startdatum des Abonnements

**Wichtig**: Wenn eine Schwellenwert-Abrechnung (Threshold Billing) stattfindet, ändert sich das Startdatum entsprechend, da dann ein neuer Abrechnungszeitraum beginnt.

### Enddatum

Das **Enddatum** ist immer das aktuelle Datum und die aktuelle Uhrzeit. Es zeigt, bis wann die Nutzung erfasst wurde.

### Beispiel: Zeitraum-Interpretation

```
Zeitraum: 01.01.2026 bis 01.02.2026
```

**Bedeutung:**

* **01.01.2026**: Letztes Abrechnungsdatum (oder Start des Abonnements)
* **01.02.2026**: Heutiges Datum

**Was wird angezeigt:**

* Alle Nutzungsereignisse vom 01.01.2026 00:00:00 bis zum 01.02.2026 (aktueller Zeitpunkt)
* Die aggregierte Gesamtnutzung in diesem Zeitraum
* **Nur** noch nicht abgerechnete Ereignisse

## Wann wird abgerechnet?

### Reguläre Abrechnung (Period Billing)

Die nutzungsbasierte Abrechnung erfolgt **am Ende des Abrechnungszeitraums**:

* **Monatliche Abrechnung**: Am 1. des Monats wird die Nutzung des Vormonats abgerechnet
* **Quartalsweise Abrechnung**: Am 1. des Quartals wird die Nutzung des Vorquartals abgerechnet

**Beispiel:**

```
Abrechnungsintervall: Monatlich
Abrechnungsdatum: 01.02.2026
Abrechnungszeitraum: 01.01.2026 - 31.01.2026
```

### Schwellenwert-Abrechnung (Threshold Billing)

Zusätzlich zur regulären Abrechnung kannst du **Schwellenwerte** definieren, die eine Abrechnung auslösen, wenn ein bestimmter Nutzungswert oder Betrag erreicht wird:

* **Beispiel**: Wenn 1000 API-Aufrufe erreicht werden, wird sofort eine Rechnung erstellt
* **Vorteil**: Du erhältst früher Zahlungen und reduzierst das Ausfallrisiko

**Wichtig**: Nach einer Schwellenwert-Abrechnung beginnt ein neuer Abrechnungszeitraum. Das Startdatum der Metriken wird entsprechend aktualisiert.

## Wie werden die Werte aggregiert?

Die Art der Aggregation hängt vom **Aggregationstyp** deiner Messung ab:

| Aggregationstyp       | Beschreibung              | Beispiel                         |
| --------------------- | ------------------------- | -------------------------------- |
| **Summe**             | Alle Werte werden addiert | 100 + 200 + 50 = 350 API-Aufrufe |
| **Anzahl**            | Anzahl der Ereignisse     | 3 Ereignisse                     |
| **Durchschnitt**      | Durchschnittswert         | (100 + 200 + 50) / 3 = 116,67    |
| **Maximum**           | Höchster Wert             | max(100, 200, 50) = 200          |
| **Zuletzt**           | Letzter gemeldeter Wert   | 50 (letzter Wert)                |
| **Eindeutige Anzahl** | Anzahl eindeutiger Werte  | 3 eindeutige Kunden              |

## Praktisches Beispiel

### Szenario: E-Mail-Versand-Service

Du bietest einen E-Mail-Versand-Service an, der pro gesendeter E-Mail abgerechnet wird.

**Setup:**

* Produkt: "E-Mail-Versand"
* Messung: "Gesendete E-Mails" (Aggregation: Summe)
* Preis: 0,01 € pro E-Mail

**Ablauf:**

1. **01.01.2026**: Abonnement startet
   * Angezeigte Nutzung: 0 E-Mails
   * Zeitraum: 01.01.2026 bis 01.01.2026

2. **15.01.2026**: Kunde sendet 1.000 E-Mails
   * Angezeigte Nutzung: 1.000 E-Mails
   * Zeitraum: 01.01.2026 bis 15.01.2026
   * **Noch nicht abgerechnet**

3. **25.01.2026**: Kunde sendet weitere 500 E-Mails
   * Angezeigte Nutzung: 1.500 E-Mails
   * Zeitraum: 01.01.2026 bis 25.01.2026
   * **Noch nicht abgerechnet**

4. **01.02.2026**: Reguläre Abrechnung
   * Rechnung wird erstellt für 1.500 E-Mails × 0,01 € = 15,00 €
   * Zeitraum der Rechnung: 01.01.2026 - 31.01.2026

5. **02.02.2026**: Kunde sendet 200 weitere E-Mails
   * Angezeigte Nutzung: 200 E-Mails
   * Zeitraum: 01.02.2026 bis 02.02.2026
   * **Neuer Abrechnungszeitraum beginnt**

## Häufige Fragen

### Warum zeigt die Metrik einen anderen Wert als erwartet?

**Mögliche Gründe:**

1. **Ereignisse wurden bereits abgerechnet**: Die Metrik zeigt nur noch nicht abgerechnete Ereignisse
2. **Falscher Zeitraum**: Prüfe, ob der Zeitraum korrekt ist (Startdatum = letztes Abrechnungsdatum)
3. **Ereignisse wurden noch nicht erfasst**: Prüfe, ob die Nutzungsereignisse korrekt an Fynn gesendet wurden

### Warum ändert sich das Startdatum?

Das Startdatum ändert sich, wenn:

* Eine reguläre Abrechnung stattgefunden hat
* Eine Schwellenwert-Abrechnung ausgelöst wurde
* Das Abonnement neu gestartet wurde

### Was passiert, wenn Ereignisse verspätet eintreffen?

Fynn berücksichtigt auch verspätet eintreffende Ereignisse korrekt:

* Ereignisse werden basierend auf ihrem **Zeitstempel** (timestamp) dem richtigen Abrechnungszeitraum zugeordnet
* Auch wenn ein Ereignis erst später erfasst wird, wird es dem korrekten Zeitraum zugeordnet

### Wie kann ich die Details einer Metrik einsehen?

Du kannst die Details einer Metrik einsehen, um:

* Alle einzelnen Nutzungsereignisse zu sehen
* Den Zeitraum im Detail zu verstehen
* Die Aggregation nachzuvollziehen

Nutze hierfür die Detailansicht der Metrik in der Abonnementübersicht.

## Zusammenfassung

* ✅ **Metriken zeigen**: Aggregierte Nutzungswerte für noch nicht abgerechnete Ereignisse
* ✅ **Startdatum**: Letztes Abrechnungsdatum (oder Abonnementstart)
* ✅ **Enddatum**: Aktuelles Datum und Uhrzeit
* ✅ **Abrechnung**: Nachträglich am Ende des Abrechnungszeitraums
* ✅ **Schwellenwerte**: Können eine frühere Abrechnung auslösen

Die nutzungsbasierte Abrechnung gibt dir vollständige Transparenz über die Nutzung deiner Kunden und ermöglicht eine faire, verbrauchsabhängige Abrechnung.


# Preis-Assistent
Source: https://docs.fynn.eu/guide/catalogue/price-assistant

Erstelle und bearbeite Preispläne in natürlicher Sprache mit dem KI-Preis-Assistenten.

Der KI-Preis-Assistent ermöglicht es, Preise in natürlicher Sprache zu beschreiben und automatisch strukturierte Preispläne generieren zu lassen. Statt Preistypen, Intervalle und Staffeln manuell zu konfigurieren, beschreibst du einfach, wie dein Produkt abgerechnet werden soll.

<Info>
  Der Preis-Assistent ist über die Preiskonfiguration im Produktkatalog verfügbar. Du findest den Button **Mit KI erstellen** beim Anlegen neuer Preise.
</Info>

***

## Einzelnen Preis erstellen

Erstelle einen einzelnen Preisplan per Beschreibung.

<Steps>
  <Step title="Preis-Assistent öffnen">
    Klicke beim Erstellen eines neuen Preises auf **Mit KI erstellen**.
  </Step>

  <Step title="Preis beschreiben">
    Beschreibe den Preis in natürlicher Sprache, z.B.:

    * "99 € monatlich"
    * "10 € pro Nutzer pro Monat"
    * "Die ersten 10 Einheiten kosten 5 €, danach 3 € pro Stück"
    * "2 % vom gemeldeten Umsatz"
  </Step>

  <Step title="Vorschau prüfen">
    Der Assistent zeigt den erkannten Preisplan mit einer Abrechnungsvorschau an. Du siehst Preistyp, Intervall, Beträge und ggf. Staffeln auf einen Blick.
  </Step>

  <Step title="Übernehmen oder anpassen">
    Klicke auf **Übernehmen**, um den Preis zu erstellen. Alternativ kannst du mit **Neu generieren** eine neue Interpretation anfordern.
  </Step>
</Steps>

### Beispiele

| Beschreibung                                                       | Erkannter Preistyp                |
| ------------------------------------------------------------------ | --------------------------------- |
| "49 € pro Monat"                                                   | Pauschale (Flat Fee), monatlich   |
| "299 € einmalige Setup-Gebühr"                                     | Pauschale, einmalig               |
| "9 € pro Nutzer pro Monat"                                         | Pro Einheit (Per Unit), monatlich |
| "1-10 Stück: 5 € je Stück, 11+: 3 € je Stück"                      | Staffel (Tiered)                  |
| "Bis 100: 10 €/Stück, ab 101: 7 €/Stück (alle zum gleichen Preis)" | Volumen (Volume)                  |
| "1-10 Nutzer: 49 €, 11-50 Nutzer: 99 €"                            | Stufen (Stair Step)               |
| "2 % von jeder Transaktion"                                        | Prozent (Percentage)              |

***

## Gesamtes Produkt mit mehreren Preisen beschreiben

Beschreibe ein komplettes Produkt mit allen Preiskomponenten in einem Schritt. Der Assistent erkennt automatisch, welche Teile getrennte Preispläne erfordern.

<Steps>
  <Step title="Produktbeschreibung eingeben">
    Beschreibe alle Preiskomponenten deines Produkts, z.B.:

    > "Unser CRM kostet 49 € Grundgebühr monatlich plus 9 € pro Nutzer. Einmalige Setup-Gebühr 299 €."
  </Step>

  <Step title="Generierte Preise prüfen">
    Der Assistent zeigt alle erkannten Preispläne als Karten an – jeweils mit Preistyp, Intervall und Abrechnungsvorschau. In diesem Beispiel:

    * Setup-Gebühr: 299 € einmalig (Pauschale)
    * Grundgebühr: 49 € monatlich (Pauschale)
    * Nutzergebühr: 9 € pro Nutzer/Monat (Pro Einheit)
  </Step>

  <Step title="Einzelne Preise entfernen oder übernehmen">
    Entferne nicht benötigte Preise per Klick auf das Papierkorb-Symbol. Klicke dann auf **Preise übernehmen**, um alle verbleibenden Preise auf einmal zu erstellen.
  </Step>
</Steps>

<Tip>
  Der Assistent trennt automatisch zwischen einmaligen und wiederkehrenden Kosten sowie zwischen verschiedenen Abrechnungseinheiten (z.B. Grundgebühr vs. pro Nutzer).
</Tip>

***

## Unterstützte Preistypen

Der Assistent erkennt alle in Fynn verfügbaren Preistypen:

| Preistyp                   | Wann erkannt                                         |
| -------------------------- | ---------------------------------------------------- |
| **Pauschale** (Flat Fee)   | Fester Betrag ohne Mengenbezug – "99 € pro Monat"    |
| **Pro Einheit** (Per Unit) | Betrag pro Stück/Nutzer/Einheit – "10 € pro Nutzer"  |
| **Staffel** (Tiered)       | Mehrere Mengenbereiche mit unterschiedlichen Preisen |
| **Volumen** (Volume)       | Gesamtmenge bestimmt den Einheitspreis für alle      |
| **Stufen** (Stair Step)    | Fester Betrag pro Mengenstufe                        |
| **Prozent** (Percentage)   | Prozentualer Anteil eines gemeldeten Werts           |

Eine detaillierte Erklärung der Berechnungslogik findest du unter [Preisberechnung](/guide/catalogue/prices/calculation).

***

## Tipps für bessere Ergebnisse

<AccordionGroup>
  <Accordion title="Intervall angeben">
    Nenne das Abrechnungsintervall explizit: "monatlich", "jährlich", "einmalig" oder "vierteljährlich".
  </Accordion>

  <Accordion title="Einheit benennen">
    Bei mengenbasierten Preisen hilft es, die Einheit zu nennen: "pro Nutzer", "pro API-Aufruf", "pro GB".
  </Accordion>

  <Accordion title="Staffeln klar beschreiben">
    Für Staffelpreise nenne die Grenzen und Preise: "1-10 Stück: 5 €, 11-50 Stück: 3 €, ab 51: 2 €".
  </Accordion>

  <Accordion title="Inklusiv-Einheiten nennen">
    Wenn Einheiten inklusive sein sollen: "Die ersten 100 API-Aufrufe sind kostenlos, danach 0,02 € pro Aufruf."
  </Accordion>
</AccordionGroup>


# Preisberechnung
Source: https://docs.fynn.eu/guide/catalogue/prices/calculation

So berechnet Fynn die verschiedenen Preistypen im Detail

Fynn unterstützt sechs verschiedene Preistypen, die jeweils einer festen Berechnungslogik folgen. Dieser Guide erklärt, wie die Berechnung für jeden Typ funktioniert und wie Zusatzfunktionen wie freie Einheiten, Mindestabnahme und Basisgebühren einbezogen werden.

## Berechnungsreihenfolge

Bevor die eigentliche Preisberechnung startet, werden zwei optionale Anpassungen auf die Menge angewendet:

<Steps>
  <Step title="Mindestabnahme anwenden">
    Ist eine Mindestabnahme konfiguriert, wird die Menge auf mindestens diesen Wert gesetzt.

    `Menge = max(Menge, Mindestabnahme)`
  </Step>

  <Step title="Freie Einheiten abziehen">
    Sind freie Einheiten konfiguriert, werden diese von der Menge abgezogen. Die Menge kann nicht negativ werden.

    `Menge = max(Menge − freie Einheiten, 0)`
  </Step>

  <Step title="Preisberechnung">
    Die bereinigte Menge wird an die Berechnungslogik des jeweiligen Preistyps übergeben.
  </Step>
</Steps>

<Note>
  Die Mindestabnahme wird **vor** den freien Einheiten angewendet. Dadurch ist sichergestellt, dass die Mindestabnahme die Basis bildet, von der anschließend die freien Einheiten abgezogen werden.
</Note>

**Beispiel:** 5 Benutzer, Mindestabnahme 10, freie Einheiten 3

1. Mindestabnahme: max(5, 10) = **10**
2. Freie Einheiten: max(10 − 3, 0) = **7**
3. Es werden 7 Einheiten berechnet.

***

## Pauschale (Flat Fee)

Ein fester Betrag pro Abrechnungsperiode, unabhängig von der Menge.

| Eingabe | Wert    |
| ------- | ------- |
| Preis   | 29,00 € |

**Berechnung:** 29,00 € (fest, keine Mengenabhängigkeit)

<Tip>
  Pauschale eignet sich für Basispakete, Grundgebühren oder einmalige Setup-Gebühren.
</Tip>

***

## Pro Einheit (Per Unit)

Der Stückpreis wird mit der bereinigten Menge multipliziert.

| Eingabe    | Wert        |
| ---------- | ----------- |
| Stückpreis | 5,00 €      |
| Menge      | 10 Benutzer |

**Berechnung:** 10 × 5,00 € = **50,00 €**

**Mit freien Einheiten:** 10 Benutzer, 3 frei → 7 × 5,00 € = **35,00 €**

***

## Staffelpreis (Tiered)

Jeder Mengenbereich hat seinen eigenen Stückpreis. Die Bereiche werden **nacheinander** abgerechnet — jede Einheit erhält den Preis der Stufe, in die sie fällt.

### Stufenkonfiguration

| Stufe | Ab Menge | Stückpreis |
| ----- | -------- | ---------- |
| 1     | 0        | 10,00 €    |
| 2     | 10       | 8,00 €     |
| 3     | 50       | 6,00 €     |

Eine Stufe deckt die Menge von ihrem `Ab Menge`-Wert bis zum `Ab Menge`-Wert der nächsten Stufe ab. Die erste Stufe beginnt immer bei 0.

### Berechnungsbeispiel

**25 Einheiten:**

| Stufe     | Einheiten | Stückpreis | Zwischensumme |
| --------- | --------- | ---------- | ------------- |
| 1 (0–9)   | 10        | 10,00 €    | 100,00 €      |
| 2 (10–24) | 15        | 8,00 €     | 120,00 €      |

**Gesamt: 220,00 €**

**60 Einheiten:**

| Stufe     | Einheiten | Stückpreis | Zwischensumme |
| --------- | --------- | ---------- | ------------- |
| 1 (0–9)   | 10        | 10,00 €    | 100,00 €      |
| 2 (10–49) | 40        | 8,00 €     | 320,00 €      |
| 3 (50–59) | 10        | 6,00 €     | 60,00 €       |

**Gesamt: 480,00 €**

<Info>
  Bei Staffelpreisen mit freien Einheiten werden die freien Einheiten **vor** der Stufenzuordnung abgezogen. Die bereinigte Menge durchläuft dann die Stufen von vorne.
</Info>

**Mit freien Einheiten:** 25 Einheiten, 5 frei → 20 bereinigte Einheiten

| Stufe     | Einheiten | Stückpreis | Zwischensumme |
| --------- | --------- | ---------- | ------------- |
| 1 (0–9)   | 10        | 10,00 €    | 100,00 €      |
| 2 (10–19) | 10        | 8,00 €     | 80,00 €       |

**Gesamt: 180,00 €**

***

## Volumenpreis (Volume)

Der Stückpreis wird anhand der **Gesamtmenge** bestimmt. Alle Einheiten erhalten dann denselben Preis.

### Stufenkonfiguration

| Stufe | Ab Menge | Stückpreis |
| ----- | -------- | ---------- |
| 1     | 0        | 10,00 €    |
| 2     | 10       | 8,00 €     |
| 3     | 50       | 6,00 €     |

### Berechnungsbeispiel

**25 Einheiten:** Stufe 2 greift (25 ≥ 10) → 25 × 8,00 € = **200,00 €**

**60 Einheiten:** Stufe 3 greift (60 ≥ 50) → 60 × 6,00 € = **360,00 €**

**8 Einheiten:** Stufe 1 greift (8 ≥ 0) → 8 × 10,00 € = **80,00 €**

<Warning>
  Beim Volumenpreis mit freien Einheiten wird die Stufe anhand der **Gesamtmenge** (vor Abzug der freien Einheiten) bestimmt. Die Preisberechnung erfolgt dann mit der **bereinigten Menge** (nach Abzug).
</Warning>

**Mit freien Einheiten:** 25 Einheiten, 5 frei

1. Stufenbestimmung: Gesamtmenge 25 → Stufe 2 (8,00 €)
2. Berechnung: (25 − 5) × 8,00 € = 20 × 8,00 € = **160,00 €**

***

## Stufenpreis (Stair Step)

Ein **fester Betrag** pro Mengenstufe. Der Preis ist unabhängig von der genauen Menge innerhalb der Stufe.

### Stufenkonfiguration

| Stufe | Ab Menge | Festpreis |
| ----- | -------- | --------- |
| 1     | 0        | 50,00 €   |
| 2     | 10       | 150,00 €  |
| 3     | 50       | 300,00 €  |

### Berechnungsbeispiel

**8 Einheiten:** Stufe 1 greift (8 ≥ 0) → **50,00 €**

**25 Einheiten:** Stufe 2 greift (25 ≥ 10) → **150,00 €**

**60 Einheiten:** Stufe 3 greift (60 ≥ 50) → **300,00 €**

<Info>
  Beim Stufenpreis bestimmt — wie beim Volumenpreis — die **Gesamtmenge** (vor Abzug der freien Einheiten) die Stufe.
</Info>

***

## Prozentual (Percentage)

Ein Prozentsatz wird auf den gemeldeten Wert angewendet.

| Eingabe         | Wert            |
| --------------- | --------------- |
| Prozentsatz     | 2,5 %           |
| Stückpreis      | 1,00 €          |
| Gemeldeter Wert | 1.000 Einheiten |

**Berechnung:** 1.000 × 2,5 % × 1,00 € = 25 × 1,00 € = **25,00 €**

Zusätzlich können beim prozentualen Preistyp eigene Freibeträge konfiguriert werden:

* **Frei pro Ereignis:** Anzahl Einheiten, die pro Nutzungsereignis abgezogen werden
* **Frei pro Gesamt:** Anzahl Einheiten, die von der Gesamtsumme abgezogen werden

***

## Basisgebühr (flatAmount)

Neben dem mengenabhängigen Preis kann auf jeder Stufe eine **Basisgebühr** konfiguriert werden. Diese wird als fester Betrag zusätzlich zum Stückpreis berechnet, sobald die jeweilige Stufe Einheiten enthält.

<Tip>
  Basisgebühren eignen sich für monatliche Grundgebühren, die zusätzlich zu einem nutzungsabhängigen Preis anfallen.
</Tip>

### Beispiel: Staffelpreis mit Basisgebühr

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 5,00 €     | 199,00 €    |

**15 Einheiten:** 15 × 5,00 € + 199,00 € = **274,00 €**

### Beispiel: Mehrere Stufen mit Basisgebühr

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 10,00 €    | 99,00 €     |
| 2     | 20       | 7,00 €     | 0,00 €      |

**30 Einheiten:**

| Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
| --------- | --------- | ---------- | ------------- | ----------- |
| 1 (0–19)  | 20        | 10,00 €    | 200,00 €      | 99,00 €     |
| 2 (20–29) | 10        | 7,00 €     | 70,00 €       | 0,00 €      |

**Gesamt: 200,00 € + 99,00 € + 70,00 € = 369,00 €**

<Note>
  Die Basisgebühr wird nur berechnet, wenn die Stufe mindestens eine Einheit enthält. Bei Stufen ohne Einheiten fällt keine Basisgebühr an.
</Note>

***

## Freie Einheiten mit Basisgebühr

Wenn ein Preis sowohl freie Einheiten als auch eine Basisgebühr hat, ist es wichtig zu verstehen, wie diese zusammenwirken. Es gibt zwei Varianten:

### Variante 1: Basisgebühr fällt immer an

Die freien Einheiten werden als eigene Stufe mit einem Stückpreis von 0 konfiguriert. Die Basisgebühr wird auf dieser Stufe hinterlegt und fällt dadurch **immer** an — auch wenn die Nutzung innerhalb der freien Einheiten liegt.

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 0,00 €     | 199,00 €    |
| 2     | 10       | 99,00 €    | 0,00 €      |

<AccordionGroup>
  <Accordion title="5 Benutzer">
    | Stufe   | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | ------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9) | 5         | 0,00 €     | 0,00 €        | 199,00 €    |

    **Gesamt: 199,00 €** (nur die Basisgebühr, alle Benutzer sind inklusive)
  </Accordion>

  <Accordion title="15 Benutzer">
    | Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | --------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9)   | 10        | 0,00 €     | 0,00 €        | 199,00 €    |
    | 2 (10–14) | 5         | 99,00 €    | 495,00 €      | 0,00 €      |

    **Gesamt: 199,00 € + 495,00 € = 694,00 €**
  </Accordion>
</AccordionGroup>

### Variante 2: Basisgebühr fällt erst nach Verbrauch der freien Einheiten an

Die freien Einheiten werden über das Feld `Freie Einheiten` konfiguriert. Die Basisgebühr wird als `flatAmount` auf der ersten Stufe hinterlegt. Da die freien Einheiten **vor** der Stufenberechnung abgezogen werden, greift die Stufe erst, wenn die Nutzung die freien Einheiten übersteigt.

**Konfiguration:** 10 freie Einheiten

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 99,00 €    | 199,00 €    |

<AccordionGroup>
  <Accordion title="5 Benutzer">
    Abzug freie Einheiten: max(5 − 10, 0) = **0 bereinigte Einheiten**

    Keine Stufe greift, da keine bereinigten Einheiten vorhanden sind.

    **Gesamt: 0,00 €** (alle Benutzer liegen innerhalb der freien Einheiten)
  </Accordion>

  <Accordion title="15 Benutzer">
    Abzug freie Einheiten: max(15 − 10, 0) = **5 bereinigte Einheiten**

    | Stufe | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | ----- | --------- | ---------- | ------------- | ----------- |
    | 1     | 5         | 99,00 €    | 495,00 €      | 199,00 €    |

    **Gesamt: 495,00 € + 199,00 € = 694,00 €**
  </Accordion>
</AccordionGroup>

<Warning>
  Verwende niemals freie Einheiten und eine Stufe mit Stückpreis 0 gleichzeitig. Das würde dazu führen, dass Einheiten doppelt als kostenlos gewertet werden.
</Warning>

***

## Komplexbeispiel

**Szenario:** 99 € pro Benutzer/Monat, 10 Benutzer inklusive, ab dem 15. Benutzer 80 € pro Benutzer, Basisgebühr 199 €.

**Konfiguration** (Basisgebühr fällt immer an):

| Stufe | Ab Menge | Stückpreis | Basisgebühr |
| ----- | -------- | ---------- | ----------- |
| 1     | 0        | 0,00 €     | 199,00 €    |
| 2     | 10       | 99,00 €    | 0,00 €      |
| 3     | 15       | 80,00 €    | 0,00 €      |

<AccordionGroup>
  <Accordion title="5 Benutzer">
    | Stufe   | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | ------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9) | 5         | 0,00 €     | 0,00 €        | 199,00 €    |

    **Gesamt: 199,00 € pro Monat**
  </Accordion>

  <Accordion title="12 Benutzer">
    | Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | --------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9)   | 10        | 0,00 €     | 0,00 €        | 199,00 €    |
    | 2 (10–11) | 2         | 99,00 €    | 198,00 €      | 0,00 €      |

    **Gesamt: 199,00 € + 198,00 € = 397,00 € pro Monat**
  </Accordion>

  <Accordion title="20 Benutzer">
    | Stufe     | Einheiten | Stückpreis | Zwischensumme | Basisgebühr |
    | --------- | --------- | ---------- | ------------- | ----------- |
    | 1 (0–9)   | 10        | 0,00 €     | 0,00 €        | 199,00 €    |
    | 2 (10–14) | 5         | 99,00 €    | 495,00 €      | 0,00 €      |
    | 3 (15–19) | 5         | 80,00 €    | 400,00 €      | 0,00 €      |

    **Gesamt: 199,00 € + 495,00 € + 400,00 € = 1.094,00 € pro Monat**
  </Accordion>
</AccordionGroup>


# Vorausabrechnung vs. Nachgelagert
Source: https://docs.fynn.eu/guide/catalogue/pricing-and-billing-timing

Wann zahlt der Kunde im Voraus, wann erst danach? Entscheidungshilfe und saubere Modellierung von Mischformen.

Fynn unterstützt zwei Abrechnungszeitpunkte: **Vorausabrechnung** (`payInAdvance = true`) und **Nachgelagert** (`payInAdvance = false`). Welcher davon richtig ist, hängt davon ab, ob die abzurechnende Menge zum Periodenstart bereits feststeht.

Dieser Artikel richtet sich an Solution Architects und Power‑User, die Preismodelle abbilden. Wenn du nur ein einfaches Abo mit Festpreis konfigurierst, brauchst du nicht weiterzulesen — der Default ist Vorausabrechnung und das ist meistens richtig.

***

## Entscheidungsmatrix

| Konstellation                                                                   | Abrechnungszeitpunkt             | Begründung                                        |
| ------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------- |
| Festpreis pro Periode (z.B. „99 €/Monat")                                       | **Vorausabrechnung**             | Menge und Preis stehen zum Periodenstart fest     |
| Mengenpreis mit fester Anzahl Einheiten (z.B. „10 Lizenzen × 8 €/Monat")        | **Vorausabrechnung**             | Menge ist im Vertrag/Abonnement gesetzt           |
| Nutzungsbasiert (BillableMetric, z.B. „pro API‑Call")                           | **Nachgelagert** (erzwungen)     | Menge ergibt sich erst aus den Events der Periode |
| Staffelpreis ohne Nutzungsmetrik (z.B. „bis 100 Lizenzen 8 €, ab 101 dann 6 €") | **Vorausabrechnung**             | Menge bleibt im Abonnement gesetzt                |
| Einmalige Setup‑Gebühr                                                          | **Vorausabrechnung** (`OneTime`) | Wird sofort fällig                                |

<Warning>
  Nutzungsbasierte Produkte werden technisch zwingend nachgelagert abgerechnet. Der `Vorausabrechnung`‑Schalter ist im PricePlan‑Editor automatisch gesperrt, sobald das verknüpfte Produkt eine Nutzungsmetrik trägt. Wenn du eine Hybridform brauchst, modellierst du das als zwei Positionen (siehe unten).
</Warning>

***

## Warum Nutzungsbasiert immer nachgelagert ist

Eine Nutzungsmetrik wie „Tokens", „API‑Calls" oder „Storage‑GB" aggregiert Ereignisse, die **während** einer Abrechnungsperiode entstehen. Vor Periodenende kennt das System die Summe nicht.

Wäre die Vorausabrechnung erlaubt, müsste der Wert geschätzt werden. Das führt zu zwei Problemen, die in der Praxis immer auftreten:

1. **Schätzfehler**: Der Schätzwert weicht von der tatsächlichen Nutzung ab. Die erste Rechnung müsste später korrigiert werden — entweder durch eine Gutschrift oder eine Nachberechnung. Bei vielen Abonnements bedeutet das eine Welle korrigierter Rechnungen mit allem Buchhaltungs‑Overhead.
2. **Falsche Signale an den Kunden**: Eine Rechnung, deren Betrag nicht den tatsächlichen Verbrauch widerspiegelt, untergräbt das Versprechen „du zahlst nur, was du verbrauchst".

Deshalb: Nutzung wird gemessen, dann abgerechnet, nie umgekehrt.

***

## Mischformen sauber modellieren

Drei gängige Anforderungen werden oft fälschlich als „BillableMetric mit Vorausabrechnung" formuliert. Alle drei lassen sich sauber mit **zwei Abonnementpositionen** abbilden:

### Mindestabnahme + Mehrverbrauch

**Anforderung:** „Mindestens 10.000 API‑Calls im Monat sind inklusive und werden monatlich im Voraus berechnet. Was darüber hinausgeht, kostet 0,01 € pro Call und wird am Monatsende abgerechnet."

**Modellierung:**

<Steps>
  <Step title="Position 1 – Grundgebühr (Vorausabrechnung)">
    * Produkt: „API‑Zugang Standard"
    * PricePlan: `flat_fee`, **Vorausabrechnung**, 100 €/Monat
    * Keine Nutzungsmetrik
  </Step>

  <Step title="Position 2 – Verbrauch (Nachgelagert)">
    * Produkt: „API‑Calls" mit Nutzungsmetrik (`COUNT` auf Event `api_call`)
    * PricePlan: `per_unit`, **Nachgelagert**, 0,01 €/Call
    * **Freikontingent: 10.000 Calls/Monat** im PricePlan
  </Step>
</Steps>

Effekt: Der Kunde bekommt am 1. eine Rechnung über 100 € (Grundgebühr). Am Monatsende wird Position 2 abgerechnet — wenn er unter 10.000 Calls geblieben ist, beträgt der Betrag 0 €. Liegt er bei 12.000 Calls, sind das 2.000 × 0,01 € = 20 €.

### Prepaid‑Credits / Volumenpaket

**Anforderung:** „Der Kunde kauft ein Paket mit 50.000 Tokens für 200 €. Die Tokens werden verbraucht, dann muss er ein neues Paket kaufen."

**Modellierung:**

<Steps>
  <Step title="Position 1 – Token‑Paket (Vorausabrechnung, einmalig)">
    * Produkt: „Token‑Paket 50k"
    * PricePlan: `OneTime`, **Vorausabrechnung**, 200 € fix
    * Wird beim Kauf abgerechnet
  </Step>

  <Step title="Position 2 – Nutzungs‑Tracking (Nachgelagert, mit Filter)">
    * Produkt: „Token‑Nutzung" mit Nutzungsmetrik (`SUM` auf `tokens_used`)
    * PricePlan: `per_unit`, **Nachgelagert**, 0 €/Token
    * **Freikontingent entspricht dem gekauften Paket‑Volumen**
    * Wenn das Paket aufgebraucht ist, wird über einen Filter oder ein Folge‑Produkt nachgeladen
  </Step>
</Steps>

Das Verbrauchs‑Tracking erzeugt also keine eigene Rechnung (Preis ist 0 €), dient aber der Transparenz im Kundenportal („du hast 32.000 von 50.000 Tokens verbraucht"). Ist das Paket aufgebraucht, sendet dein System das nächste „Paket‑gekauft"‑Event und der Zyklus startet neu.

### Geschätzte Abrechnung mit True‑Up

**Anforderung:** „Der Kunde zahlt monatlich 500 € im Voraus auf Basis einer Schätzung. Am Quartalsende wird die tatsächliche Nutzung gegengerechnet."

**Modellierung:** Diese Variante ist in der Praxis im DACH‑B2B‑SaaS selten und wird in Fynn nicht durch ein Spezial‑Feature unterstützt. Die saubere Abbildung ist:

<Steps>
  <Step title="Position 1 – Abschlagszahlung (Vorausabrechnung, monatlich)">
    * Produkt: „Service Abschlag"
    * PricePlan: `flat_fee`, **Vorausabrechnung**, 500 €/Monat
  </Step>

  <Step title="Position 2 – Tatsächliche Nutzung (Nachgelagert, quartalsweise)">
    * Produkt: „Service Nutzung" mit Nutzungsmetrik
    * PricePlan: `per_unit`, **Nachgelagert**, quartalsweise
  </Step>

  <Step title="Periodenend‑Korrektur über Rechnungskorrektur">
    Am Quartalsende erzeugst du eine Rechnungskorrektur, die die drei Abschlagsrechnungen (Position 1) mit der Nutzungsrechnung (Position 2) gegenrechnet. Saldo positiv → Nachberechnung, Saldo negativ → Gutschrift.
  </Step>
</Steps>

<Tip>
  Wenn du diese Variante häufig brauchst, sprich mit uns. Wir haben in der Roadmap einen „Estimated Billing"‑Workflow, der die True‑Up‑Korrektur am Periodenende automatisiert.
</Tip>

***

## Was im Hintergrund passiert

Wenn ein Abonnement aktiviert wird, gibt es zwei mögliche Verläufe:

**Vorausabrechnung (`payInAdvance = true`):**

1. Subscription‑Start am 1. Mai
2. Sofort wird eine Rechnung für `[1. Mai, 1. Juni)` erzeugt
3. Nächste Abrechnung: 1. Juni für `[1. Juni, 1. Juli)`, etc.

**Nachgelagert (`payInAdvance = false`):**

1. Subscription‑Start am 1. Mai
2. **Keine** Rechnung am 1. Mai
3. Während Mai werden Nutzungsereignisse erfasst
4. Am 1. Juni: Rechnung für `[1. Mai, 1. Juni)` mit der aggregierten Mai‑Nutzung
5. Nächste Abrechnung: 1. Juli für `[1. Juni, 1. Juli)`, etc.

Beide Modelle laufen über denselben Cron‑Lauf — der Unterschied liegt nur darin, wann der erste Rechnungslauf zündet.

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich einen einzelnen Kunden auf Vorausabrechnung umstellen, auch wenn das Produkt nutzungsbasiert ist?">
    Nein. Die Regel gilt produktseitig, nicht kundenseitig. Wenn du für einen Kunden ein anderes Abrechnungsmodell brauchst, modellierst du das über eine separate Abonnementposition mit anderem Produkt.
  </Accordion>

  <Accordion title="Was passiert, wenn ein Kunde mitten in einer Periode kündigt?">
    Bei Vorausabrechnung gibt es typischerweise eine anteilige Gutschrift für den ungenutzten Rest. Bei nachgelagerter Abrechnung wird die bis zur Kündigung erfasste Nutzung wie üblich am nächsten Abrechnungstermin in Rechnung gestellt — ohne Sonderbehandlung.
  </Accordion>

  <Accordion title="Können in einem Abonnement beide Abrechnungszeitpunkte gleichzeitig vorkommen?">
    Ja. Jede Abonnementposition entscheidet selbst. Eine Position mit Grundgebühr kann im Voraus laufen, während eine zweite Position mit Nutzungsabrechnung nachgelagert läuft. Die Rechnungen erscheinen einfach zu verschiedenen Zeitpunkten.
  </Accordion>
</AccordionGroup>

***

## Verwandte Themen

<CardGroup>
  <Card title="Nutzungsmetriken" icon="chart-line" href="/guide/catalogue/measurements/billable-metrics">
    Wie du Events erfasst und aggregierst.
  </Card>

  <Card title="Verständnis nutzungsbasierter Abrechnung" icon="calculator" href="/guide/catalogue/measurements/usage-based-billing">
    Wie die Aggregation in der Abrechnung sichtbar wird.
  </Card>
</CardGroup>


# Nutzungsereignisse senden
Source: https://docs.fynn.eu/guide/catalogue/usage-events-import

Sende Nutzungsereignisse über CSV oder die API für nutzungsbasierte Abrechnung

Nutzungsereignisse sind die Grundlage für nutzungsbasierte Abrechnung. Es gibt zwei Möglichkeiten, Ereignisse zu senden: über CSV-Dateien oder direkt über die REST API.

## Übersicht

| Methode        | Verwendung                     | Limit                          |
| -------------- | ------------------------------ | ------------------------------ |
| **CSV Import** | Bulk-Import historischer Daten | Bis zu 10 MB pro Datei         |
| **API Import** | Echtzeit-Event-Erfassung       | Bis zu 1000 Events pro Request |

<Tip>
  Für einmalige Imports historischer Daten oder Backfill-Szenarien verwende CSV Import. Für kontinuierliche, Echtzeit-Event-Erfassung aus Anwendungen verwende die API.
</Tip>

## CSV Import

### CSV Format

Die CSV-Datei muss folgende Spalten enthalten:

| Spalte           | Typ      | Erforderlich | Beschreibung                                        |
| ---------------- | -------- | ------------ | --------------------------------------------------- |
| `transaction_id` | string   | Ja           | Eindeutige Transaktions-ID für Idempotenz           |
| `event_name`     | string   | Ja           | Name des Events (z.B. "api\_call", "storage\_used") |
| `timestamp`      | ISO 8601 | Ja           | Event-Zeitstempel (z.B. "2026-01-13T10:30:00Z")     |
| `customer_id`    | string   | Ja           | Kunden-Identifier (Fynn-UUID oder `externalId`)     |
| `properties`     | JSON     | Ja           | Event-Eigenschaften als JSON-Objekt                 |

<Warning>
  Die Datei muss im UTF-8 Format vorliegen. Die `properties`-Spalte muss ein gültiges JSON-Objekt enthalten. Maximale Dateigröße: 10 MB.
</Warning>

### Import über die Benutzeroberfläche

1. Navigiere zur Seite **Verbrauchsdaten**
2. Klicke auf das **Aktionen**-Dropdown im Header
3. Wähle **CSV Import**
4. Im Dialog:
   * Klicke auf den Upload-Bereich oder ziehe eine CSV-Datei hinein
   * Wähle die CSV-Datei aus
   * Klicke auf **Importieren**

<Frame>
  <img alt="CSV Import Dialog" />
</Frame>

**Nach dem Import:**

* Die Events werden asynchron verarbeitet
* Die Tabelle wird automatisch aktualisiert
* Bei Fehlern wird eine Fehlermeldung angezeigt

### Beispiel CSV

```csv theme={null}
transaction_id,event_name,timestamp,customer_id,properties
tx-12345,api_call,2026-01-13T10:30:00Z,550e8400-e29b-41d4-a716-446655440000,"{""endpoint"":""/api/v1/users"",""method"":""GET"",""response_time_ms"":145,""status_code"":200}"
tx-12346,storage_used,2026-01-13T10:31:00Z,550e8400-e29b-41d4-a716-446655440000,"{""bytes"":1048576,""storage_type"":""database""}"
tx-12347,api_call,2026-01-13T10:32:00Z,550e8400-e29b-41d4-a716-446655440000,"{""endpoint"":""/api/v1/products"",""method"":""POST"",""response_time_ms"":234,""status_code"":201}"
```

<Info>
  JSON-Objekte in der `properties`-Spalte müssen mit doppelten Anführungszeichen escaped werden (`""`).
</Info>

## API Import

Nutzungsereignisse können programmatisch über die REST API gesendet werden. Unterstützt einzelne Events oder Batch-Import (bis zu 1000 Events pro Anfrage).

### Authentifizierung

Der API-Schlüssel muss im Request-Header übergeben werden:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Einzelnes Event senden

**Endpoint:** `POST /api/usage-events`

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "events": [
      {
        "transactionId": "tx-12345",
        "eventName": "api_call",
        "timestamp": "2026-01-13T10:30:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "endpoint": "/api/v1/users",
          "method": "GET",
          "response_time_ms": 145,
          "status_code": 200
        }
      }
    ]
  }'
```

### Batch Import

Bis zu 1000 Events können in einem Request gesendet werden:

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "events": [
      {
        "transactionId": "tx-12345",
        "eventName": "api_call",
        "timestamp": "2026-01-13T10:30:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "endpoint": "/api/v1/users",
          "method": "GET",
          "response_time_ms": 145,
          "status_code": 200
        }
      },
      {
        "transactionId": "tx-12346",
        "eventName": "storage_used",
        "timestamp": "2026-01-13T10:31:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "bytes": 1048576,
          "storage_type": "database"
        }
      }
    ]
  }'
```

### Antwortformat

**Erfolgreiche Antwort (202 Accepted):**

```json theme={null}
{
  "ingested": 2,
  "failed": 0,
  "errors": []
}
```

**Antwort mit Fehlern:**

```json theme={null}
{
  "ingested": 1,
  "failed": 1,
  "errors": [
    {
      "index": 1,
      "transactionId": "tx-12346",
      "error": "Invalid customer ID"
    }
  ]
}
```

**HTTP Status Codes:**

| Code  | Bedeutung                                                  |
| ----- | ---------------------------------------------------------- |
| `202` | Events wurden akzeptiert (kann teilweise Fehler enthalten) |
| `400` | Ungültige Anfrage - Validierungsfehler                     |
| `401` | Nicht autorisiert - Ungültiger API-Schlüssel               |

## Event-Struktur

### Erforderliche Felder

Jedes Nutzungsereignis muss folgende Felder enthalten:

```typescript theme={null}
{
  transactionId: string;    // Eindeutige ID für Idempotenz
  eventName: string;         // Name des Events
  timestamp: string;         // ISO 8601 Zeitstempel
  customerId: string;        // Fynn-UUID oder externalId des Kunden
  properties: object;        // Beliebige Event-Eigenschaften
}
```

### Idempotenz

Events mit derselben `transactionId` werden nur einmal verarbeitet. Bei wiederholtem Senden wird das bereits existierende Event zurückgegeben (HTTP 200 statt 201).

<Tip>
  Verwende eindeutige, deterministische Transaction IDs. Beispiel: UUID oder `${customerId}-${timestamp}-${eventName}`
</Tip>

### Properties

Die `properties` können beliebige JSON-Objekte enthalten. Typische Beispiele:

**API Call Event:**

```json theme={null}
{
  "endpoint": "/api/v1/users",
  "method": "GET",
  "response_time_ms": 145,
  "status_code": 200
}
```

**Storage Event:**

```json theme={null}
{
  "bytes": 1048576,
  "storage_type": "database",
  "region": "eu-central-1"
}
```

**Transaction Event:**

```json theme={null}
{
  "amount": 99.99,
  "currency": "EUR",
  "transaction_type": "purchase"
}
```

## Best Practices

### Timestamps

Verwende immer UTC-Zeitstempel im ISO 8601 Format.

### Batch-Größe

Für optimale Performance:

* **Kleine Batches**: 10-100 Events für Echtzeit-Erfassung
* **Große Batches**: 500-1000 Events für Bulk-Import
* **Vermeide**: Sehr kleine Batches (\< 10) bei hohem Volumen

### Rate Limiting

Respektiere Rate Limits:

* **Empfohlen**: Maximal 10 Requests pro Sekunde
* **Burst**: Kurzzeitig bis zu 50 Requests pro Sekunde
* **Vermeide**: Längerfristige Überschreitung der Limits

## Fehlerbehebung

### CSV Import schlägt fehl

**Problem:** "Ungültiges CSV-Format"

**Lösung:**

1. Prüfe, ob alle erforderlichen Spalten vorhanden sind
2. Stelle sicher, dass die Datei UTF-8 kodiert ist
3. Validiere JSON in der `properties`-Spalte
4. Prüfe, ob Anführungszeichen korrekt escaped sind

**Problem:** "Datei zu groß"

**Lösung:**

* Teile die CSV-Datei in kleinere Dateien auf (max. 10 MB)
* Importiere die Dateien nacheinander

### API Import Fehler

**Problem:** `401 Unauthorized`

**Lösung:**

* Prüfe, ob der API-Schlüssel korrekt im Header übergeben wird
* Stelle sicher, dass der API-Schlüssel aktiv ist
* Prüfe die Berechtigungen des API-Schlüssels

**Problem:** `400 Bad Request`

**Lösung:**

* Validiere die Event-Struktur
* Prüfe, ob alle erforderlichen Felder vorhanden sind
* Stelle sicher, dass `customerId` eine gültige UUID oder `externalId` ist
* Prüfe das `timestamp`-Format (ISO 8601)

**Problem:** Events werden nicht angezeigt

**Lösung:**

1. Prüfe die Antwort auf Fehler (`errors` Array)
2. Validiere `transactionId` (möglicherweise Duplikat)
3. Prüfe Filter in der Events-Tabelle
4. Warte kurz, da Events asynchron verarbeitet werden

## Verwandte Dokumentation

* [Abrechenbare Einheiten verwalten](/guide/catalogue/measurements/introduction)
* [Nutzungsbasierte Abrechnung](/guide/subscriptions/introduction)
* [API Referenz - Nutzungsereignisse](/api-reference/usage-events)


# Abonnement-Übergänge
Source: https://docs.fynn.eu/guide/subscriptions/transitions

Wechsle Produkte und Preispläne in einem Abonnement mit automatischer Proration und Gutschriften.

Mit Abonnement-Übergängen kannst du die Produkte und Preispläne eines bestehenden Abonnements ändern - z.B. für Upgrades, Downgrades oder Produktwechsel. Die Änderungen werden sauber verarbeitet mit automatischer Berechnung von Gutschriften und anteiliger Abrechnung.

<Warning>
  Gekündigte Abonnements können nicht mehr transitioniert werden. Der Übergangszeitpunkt muss in der Zukunft oder jetzt sein.
</Warning>

## Anwendungsfälle

| Szenario           | Beschreibung                                                |
| ------------------ | ----------------------------------------------------------- |
| **Upgrade**        | Kunde wechselt von Basic auf Pro Plan                       |
| **Downgrade**      | Kunde wechselt auf einen günstigeren Plan                   |
| **Produktwechsel** | Wechsel von einem Produkt zu einem anderen                  |
| **Planänderung**   | Gleiche Produkte, aber andere Preispläne                    |
| **Migration**      | Umstellung von nutzungsbasiert auf Festpreis oder umgekehrt |

***

## So funktioniert es

Ein Übergang führt folgende Schritte aus:

1. **Alte Items beenden** - Bestehende Abonnement-Items werden zum Übergangszeitpunkt beendet
2. **Gutschriften erstellen** - Optional werden Gutschriften für nicht genutzte Zeit erstellt
3. **Neue Items anlegen** - Die gewünschten Produkte werden als neue Items hinzugefügt
4. **Phase wechseln** - Eine neue Abonnement-Phase beginnt

***

## Proration (Gutschriften)

Bei der Beendigung von Festpreis-Produkten kannst du wählen, wie Gutschriften berechnet werden:

| Option                          | Beschreibung                                 |
| ------------------------------- | -------------------------------------------- |
| **Anteilig** (`creditProrated`) | Gutschrift basierend auf verbleibenden Tagen |
| **Keine** (`none`)              | Keine Gutschrift                             |

<Tip>
  Die Gutschrift wird sofort finalisiert und an den Kunden gesendet. Der Guthabenbetrag wird automatisch mit der nächsten Rechnung verrechnet.
</Tip>

<Note>
  Bei nutzungsbasierten Produkten werden **keine Gutschriften** erstellt, da diese im Nachhinein abgerechnet werden. Stattdessen wird die Nutzung bis zum Übergangszeitpunkt mit dem alten Preisplan abgerechnet.
</Note>

***

## Abrechnungszeitpunkt

Du kannst festlegen, wann die neuen Items abgerechnet werden:

| Option                         | Beschreibung                                                                                                                              |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Phasenstart** (`phaseStart`) | Rechnung wird zum Übergangszeitpunkt erstellt. Teilperioden von nutzungsbasierten Items werden ebenfalls zu diesem Zeitpunkt abgerechnet. |
| **Sofort** (`immediately`)     | Rechnung wird sofort erstellt. Teilperioden von nutzungsbasierten Items werden ebenfalls sofort abgerechnet.                              |

***

## Nutzungsbasierte Produkte

Bei nutzungsbasierten Produkten gibt es besondere Regeln:

### Keine Gutschriften

Nutzungsbasierte Produkte werden **nie** gutgeschrieben, da sie im Nachhinein abgerechnet werden. Die Proration-Einstellung wird ignoriert.

### Teilperioden-Abrechnung

Wenn ein nutzungsbasiertes Item beendet wird, erstellt das System automatisch Abrechnungsposten für die Teilperiode:

* **Zeitraum**: Letzte Abrechnung → Übergangszeitpunkt
* **Preis**: Alter Preisplan
* **Inklusiveinheiten**: Werden anteilig berechnet

**Beispiel:**

* Letzter Abrechnungszeitpunkt: 1. Februar
* Übergangszeitpunkt: 15. Februar
* Die Nutzung vom 1.-15. Februar wird mit dem alten Preisplan abgerechnet
* Ab 15. Februar gilt der neue Preisplan

### Wechsel zwischen Produkttypen

| Von             | Nach            | Gutschrift    | Teilperiode |
| --------------- | --------------- | ------------- | ----------- |
| Festpreis       | Festpreis       | Ja (optional) | Nein        |
| Festpreis       | Nutzungsbasiert | Ja (optional) | Nein        |
| Nutzungsbasiert | Festpreis       | Nein          | Ja          |
| Nutzungsbasiert | Nutzungsbasiert | Nein          | Ja          |

***

## API

Für Übergänge steht folgender API-Endpoint zur Verfügung:

| Method | Endpoint                             | Beschreibung         |
| ------ | ------------------------------------ | -------------------- |
| POST   | `/api/subscriptions/[id]/transition` | Übergang durchführen |

<Card title="API Referenz" icon="code" href="/api-reference/subscription/transition">
  Vollständige API-Dokumentation mit Request/Response-Strukturen und Beispielen
</Card>

***

## Verwandte Dokumentation

<CardGroup>
  <Card title="Abonnements verwalten" icon="repeat" href="/guide/subscriptions/introduction">
    Grundlagen zu Abonnements
  </Card>

  <Card title="Nutzungsmetriken" icon="chart-line" href="/guide/catalogue/measurements/billable-metrics">
    Nutzungsbasierte Abrechnung konfigurieren
  </Card>
</CardGroup>


# Go-Live
Source: https://docs.fynn.eu/guide/tenant/go-live-checklist

Best Practices und wichtige Schritte für einen erfolgreichen Produktivstart mit Fynn.

Du planst den Go-Live mit Fynn? Diese Checkliste hilft dir, alle wichtigen Vorbereitungen zu treffen und nichts zu vergessen.

<Note>
  Für die Produktivumgebung ist ein Vertrag mit unserem Sales-Team erforderlich. [Kontaktiere uns](mailto:sales@fynn.eu) oder [buche einen Termin](https://cal.com/team/fynn/fynn-documentation).
</Note>

<Tip>
  Die meisten Einstellungen sind bereits in der [Ersten Konfiguration](/guide/tenant/first-configuration) beschrieben. Diese Checkliste dient als Übersicht für den finalen Go-Live.
</Tip>

***

## Produkte aus der Testumgebung übernehmen

Du hast Produkte in der Sandbox-Umgebung konfiguriert? Diese kannst du einfach in die Produktivumgebung importieren:

<Steps>
  <Step title="API-Token in der Testumgebung erstellen">
    Erstelle in der [Sandbox-Umgebung](https://preview.fynn.eu) unter Einstellungen > API einen API-Token.
  </Step>

  <Step title="Import starten">
    Gehe in der Produktivumgebung zu [Katalog > Produkte](https://app.fynn.eu/catalogue/products) und wähle im Aktionen-Menü (oben rechts) **Testumgebung Import**.
  </Step>

  <Step title="Produkte auswählen">
    * Gib den API-Token aus der Testumgebung ein
    * Wähle die Produkte aus, die importiert werden sollen
    * Ordne benutzerdefinierte Felder zu (neu erstellen oder vorhandene verwenden)
    * Ordne Kostenstellen zu
    * Produkte, Preise und Konfigurationen werden kopiert
  </Step>
</Steps>

***

## Zahlungsanbieter (PSP) einrichten

### SEPA-Lastschrift

Für den Einzug per SEPA-Lastschrift benötigst du:

<Steps>
  <Step title="Gläubiger-ID beantragen">
    Beantrage deine Gläubiger-Identifikationsnummer bei der [Deutschen Bundesbank](https://extranet.bundesbank.de/scp/beantragungCI/lizenz.xhtml).

    Die Beantragung ist online möglich und dauert nur wenige Minuten.
  </Step>

  <Step title="SEPA-Verfügungsrahmen bei deiner Bank">
    Kläre mit deiner Hausbank den SEPA-Verfügungsrahmen (Limits) für Lastschrifteinzüge.
  </Step>

  <Step title="SEPA in Fynn verbinden">
    Hinterlege deine Bankdaten und Gläubiger-ID unter [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods).

    [Zur SEPA-Anleitung](/integrations/payment-providers/sepa)
  </Step>
</Steps>

### Kreditkarte (Stripe)

<Steps>
  <Step title="Stripe-Konto erstellen">
    Du kannst dein Stripe-Konto direkt während der Verbindung in Fynn erstellen.
  </Step>

  <Step title="Unternehmensverifizierung abschließen">
    Stripe benötigt Unternehmensdokumente zur Verifizierung (Handelsregisterauszug, Ausweisdokument).

    **Dauer:** 1-5 Werktage
  </Step>

  <Step title="Stripe in Fynn verbinden">
    [Zur Stripe-Anleitung](/integrations/payment-providers/stripe)
  </Step>
</Steps>

### PayPal

<Steps>
  <Step title="PayPal Business-Konto">
    Erstelle ein [PayPal Business-Konto](https://www.paypal.com/de/business) falls noch nicht vorhanden.
  </Step>

  <Step title="PayPal in Fynn verbinden">
    [Zur PayPal-Anleitung](/integrations/payment-providers/paypal)
  </Step>
</Steps>

***

## Fynn konfigurieren

### Unternehmensdaten

Unter [Einstellungen > Organisation](https://app.fynn.eu/settings) hinterlegst du:

* Vollständiger Firmenname
* Adresse (Straße, PLZ, Ort, Land)
* Steuernummer und USt-IdNr.
* Kontakt-E-Mail und Telefon
* Firmenlogo
* Bankverbindung (für Rechnungen)

### Nummernkreise

Lege unter [Einstellungen > Nummernkreise](https://app.fynn.eu/settings/number-ranges) fest:

* Rechnungsnummern (z.B. `RE-2024-00001`)
* Gutschriftennummern
* Kundennummern

[Mehr zu Nummernkreisen](/guide/tenant/number-ranges)

### E-Mail-Vorlagen

Passe unter [Einstellungen > Benachrichtigungen](https://app.fynn.eu/settings/notifications) die E-Mail-Vorlagen an:

* Rechnungsversand
* Zahlungsbestätigung
* Zahlungserinnerung / Mahnung
* Willkommens-E-Mail

[Mehr zu Benachrichtigungen](/guide/notifications/introduction)

### Dokumentvorlagen

Falls du das Layout deiner Dokumente anpassen möchtest, konfiguriere unter [Einstellungen > Aussehen & Design](https://app.fynn.eu/settings/design) die Vorlagen für:

* Rechnung
* Stornierung
* Gutschrift

### Mahnwesen

Konfiguriere unter [Einstellungen > Mahnwesen](https://app.fynn.eu/settings/payment-failures) deine Mahnstufen und Fristen.

[Mehr zum Mahnwesen](/guide/dunning/introduction)

***

## Zahlungsmethoden aktivieren

Nach dem Verbinden der Zahlungsanbieter müssen die gewünschten Zahlungsmethoden unter [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods) aktiviert werden.

***

## Kontoabgleich einrichten

Für die automatische Zahlungszuordnung verbinde dein Bankkonto unter [Einstellungen > Zahlungsmethoden](https://app.fynn.eu/settings/payment-methods) > **Bankkonto** > **Kontoabgleich**. Eingehende Zahlungen werden automatisch den offenen Rechnungen zugeordnet.

***

## Buchhaltung

Falls du eine Buchhaltungssoftware nutzt:

* DATEV-Export einrichten
* Kontenrahmen prüfen
* Erlöskonten zuordnen

[Mehr zur Buchhaltung](/guide/accounting/introduction)

***

## Kundenbereich

Unter [Einstellungen > Kundenbereich](https://app.fynn.eu/settings/hosted-services) kannst du das Self-Service-Portal für deine Kunden konfigurieren - z.B. welche Funktionen verfügbar sind, Branding und eigene Domain.

***

## Team einladen

Lade dein Team unter [Einstellungen > Benutzer](https://app.fynn.eu/settings/users) ein und vergib passende Rollen.

Falls du granulare Berechtigungen benötigst, erstelle unter [Einstellungen > Gruppen](https://app.fynn.eu/settings/groups) Benutzergruppen mit spezifischen Rechten.

[Mehr zu Benutzerrollen](/guide/tenant/users)

***

## Abrechnungseinstellungen

Unter [Einstellungen > Abrechnung](https://app.fynn.eu/settings/billing) kannst du festlegen:

* **Manuelle Rechnungsfreigabe**: Rechnungen müssen vor dem Versand manuell freigegeben werden
* Automatische Rechnungserstellung und -versand konfigurieren

<Tip>
  Die manuelle Freigabe ist besonders nützlich, wenn du beim Go-Live volle Kontrolle über die ersten Rechnungen behalten möchtest - zum Beispiel um deine Konfiguration zu verifizieren oder um interne Freigabeprozesse abzubilden.
</Tip>

***

## Vor dem Go-Live testen

<Check>
  Teste alle Prozesse in der [Sandbox-Umgebung](https://preview.fynn.eu) bevor du live gehst.
</Check>

Teste mindestens:

* Kunde anlegen mit Zahlungsmethode
* Abonnement erstellen und aktivieren
* Rechnung generieren und versenden
* Zahlung einziehen
* E-Mail-Vorlagen auf Inhalt und Design prüfen

***

## Checkliste

* Produkte aus Testumgebung importiert
* Gläubiger-ID beantragt (für SEPA)
* SEPA-Verfügungsrahmen mit Bank geklärt (für SEPA)
* Zahlungsanbieter verbunden (SEPA, Stripe, PayPal, etc.)
* Zahlungsmethoden aktiviert
* Kontoabgleich für automatische Zahlungszuordnung eingerichtet
* Unternehmensdaten vollständig hinterlegt
* Logo hochgeladen
* Nummernkreise konfiguriert
* E-Mail-Vorlagen angepasst
* Dokumentvorlagen angepasst (falls erforderlich)
* Abrechnungseinstellungen geprüft (manuelle Freigabe?)
* Mahnwesen eingerichtet
* Kundenbereich konfiguriert
* Buchhaltungsintegration konfiguriert
* Team eingeladen und Benutzergruppen erstellt
* Testdurchlauf in Sandbox erfolgreich

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich Produkte aus der Testumgebung übernehmen?">
    Ja! Unter **Katalog > Produkte > Aktionen > Testumgebung Import** kannst du Produkte, Preise und Konfigurationen aus der Sandbox importieren. Du benötigst dafür einen API-Token aus der Testumgebung.
  </Accordion>

  <Accordion title="Wie lange dauert die Stripe-Verifizierung?">
    Die Unternehmensverifizierung bei Stripe dauert in der Regel 1-5 Werktage. Stripe benötigt Unternehmensdokumente (Handelsregisterauszug, Ausweisdokument). Starte die Verifizierung rechtzeitig vor dem geplanten Go-Live.
  </Accordion>

  <Accordion title="Kann ein Kunde mehrere Zahlungsmethoden haben?">
    Ja, Kunden können mehrere Zahlungsmethoden hinterlegen (z.B. SEPA und Kreditkarte). **Ausnahme:** Pro Kunde kann nur ein PayPal-Konto hinterlegt werden.
  </Accordion>

  <Accordion title="Was passiert bei SEPA-Fehlern?">
    * **Mandatsprobleme** (MD01, MD02): Zahlungsmethode wird deaktiviert
    * **Kontoprobleme** (AC01, AC04): Zahlungsmethode wird deaktiviert
    * **Temporäre Probleme** (AM04, AM05): Automatischer Retry wird geplant
    * **Regulatorische Probleme** (AG01, RR01): Manuelle Prüfung erforderlich
  </Accordion>

  <Accordion title="Kann ich Rechnungen ohne Zahlungsmethode finalisieren?">
    Nein, für die Finalisierung einer Rechnung muss eine gültige Zahlungsmethode hinterlegt sein. Falls die Zahlungsmethode ungültig ist, erscheint ein Dialog zur Auswahl einer neuen. **Überweisung** ist immer als Fallback verfügbar.
  </Accordion>

  <Accordion title="Was kostet SMS-Versand für Mahnungen?">
    SMS-Versand ist ein kostenpflichtiges Feature: **0,10€ pro SMS** (max. 160 Zeichen).
  </Accordion>

  <Accordion title="Kann ich Kunden löschen?">
    Ein Kunde kann nur gelöscht werden, wenn er keine aktiven Abonnements, Rechnungen, Bestellungen oder Zahlungen hat. Alternativ kannst du Kunden **archivieren** - diese können später wiederhergestellt werden.
  </Accordion>

  <Accordion title="Werden Mahngebühren in den Buchhaltungsexport übernommen?">
    Mahngebühren werden aktuell noch nicht in den Buchhaltungsexport (z.B. DATEV) übernommen. Diese müssen manuell verbucht werden.
  </Accordion>
</AccordionGroup>

***

## Weitere Hilfe

Bei Fragen zum Go-Live: [Termin buchen](https://cal.com/team/fynn/fynn-documentation) oder [Support kontaktieren](mailto:hi@fynn.eu)


# Kernkonzepte
Source: https://docs.fynn.eu/v2-commission-api/concepts

Die Felder eines Provisionsplans und die beiden monatlichen Auszahlungsschwellen je Vertriebsmitarbeiter.

Ein Provisionsplan legt den Provisionssatz fest und steuert, ab wann ausgezahlt wird. Diese Seite erklärt die Felder, die du beim Anlegen setzt, und die beiden monatlichen Schwellen.

## Felder eines Plans

| Feld                      | Bedeutung                                                                              |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `name`                    | Interner Name des Plans.                                                               |
| `type`                    | Berechnungsart. Aktuell `ongoing_percentage`.                                          |
| `percentage`              | Basissatz als Dezimalbruch, `0.10` entspricht 10 %.                                    |
| `basisType`               | Berechnung auf `net` oder `gross` des Rechnungsbetrags.                                |
| `triggerEvent`            | `invoice_finalized` (bei Rechnungsstellung) oder `invoice_paid` (bei Zahlungseingang). |
| `commissionScope`         | `all_invoices` oder `first_contract_period`.                                           |
| `requireDeal`             | Wenn `true`, generieren nur Rechnungen mit verknüpftem Deal Provisionen.               |
| `payoutThresholdAmount`   | Mindestauszahlung je Vertriebsmitarbeiter und Monat. Siehe unten.                      |
| `monthlyRevenueThreshold` | Mindestumsatz je Vertriebsmitarbeiter und Monat. Siehe unten.                          |
| `rules`                   | Produktregeln, die den Basissatz je Produkt überschreiben.                             |

Beträge gibst du als Objekt in kleinster Einheit an:

```json theme={null}
{ "amount": 5000, "currency": "EUR", "precision": 2 }
```

Das entspricht 50,00 EUR. Lässt du eine Schwelle weg oder setzt sie auf `null`, gilt keine Grenze.

## Die beiden monatlichen Schwellen

Beide Schwellen wirken **je Vertriebsmitarbeiter, je Plan, je Kalendermonat**, immer über alle Kunden eines Vertriebsmitarbeiters zusammen. Sie entscheiden, ob die Provisionen eines Monats ausgezahlt werden.

**Mindestauszahlung (`payoutThresholdAmount`)**

Erreicht die Provisionssumme eines Vertriebsmitarbeiters im Monat diese Grenze nicht, wird der ganze Monat zurückgehalten. Erreicht sie die Grenze, wird der komplette Monat ausgezahlt.

**Mindestumsatz (`monthlyRevenueThreshold`)**

Erreicht der Umsatz eines Vertriebsmitarbeiters im Monat diese Grenze nicht, gibt es für den gesamten Monat keine Provision. Wird die Grenze erreicht, wird der komplette Umsatz provisioniert. So belohnst du das Erreichen von Monatszielen.

Sind beide gesetzt, muss ein Monat **beide** erreichen, damit er ausgezahlt wird.

```mermaid theme={null}
flowchart TD
  Start[Monat je Vertriebsmitarbeiter und Plan] --> Rev{Mindestumsatz erreicht?}
  Rev -- Nein --> Hold[Keine Provision für den Monat]
  Rev -- Ja --> Pay{Mindestauszahlung erreicht?}
  Pay -- Nein --> Hold
  Pay -- Ja --> Ok[Provisionen des Monats werden ausgezahlt]
```

<Tip>
  Zurückgehaltene Provisionen gehen nicht verloren. Sie bleiben genehmigt und werden aufgenommen, sobald die Grenze in einem zukünftigen Monat erreicht wird.
</Tip>

### Beispiel

Ein Plan mit Mindestauszahlung 50 EUR und Mindestumsatz 1.000 EUR:

| Vertriebsmitarbeiter | Umsatz im Monat | Provision im Monat | Ergebnis                                          |
| -------------------- | --------------- | ------------------ | ------------------------------------------------- |
| A                    | 1.500 EUR       | 75 EUR             | wird ausgezahlt (beide Grenzen erreicht)          |
| B                    | 600 EUR         | 75 EUR             | zurückgehalten (Mindestumsatz nicht erreicht)     |
| C                    | 1.500 EUR       | 25 EUR             | zurückgehalten (Mindestauszahlung nicht erreicht) |

## Einen Plan anlegen

```bash theme={null}
curl https://coreapi.io/api/commissions/plans \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neukundenvertrieb 10 %",
    "percentage": "0.10",
    "basisType": "net",
    "triggerEvent": "invoice_finalized",
    "commissionScope": "all_invoices",
    "requireDeal": false,
    "payoutThresholdAmount": { "amount": 5000, "currency": "EUR", "precision": 2 },
    "monthlyRevenueThreshold": { "amount": 100000, "currency": "EUR", "precision": 2 }
  }'
```

Die vollständige Referenz aller Felder und Antworten findest du unter [Provisionspläne](/v2-commission-api/plans/create-plan).


# Provisionen API
Source: https://docs.fynn.eu/v2-commission-api/introduction

Provisionspläne über die Fynn API V2 anlegen und verwalten: Provisionssatz, Produktregeln und zwei monatliche Auszahlungsschwellen je Vertriebsmitarbeiter.

Mit der Provisionen API modellierst du, wie deine Vertriebsmitarbeiter an Rechnungen verdienen. Ein **Provisionsplan** legt den Provisionssatz fest, auf welche Rechnungen er wirkt und ab wann ausgezahlt wird.

<Info>
  Provisionspläne verwaltest du auch in der App unter **Provisionen**. Die vollständige Anleitung für den Alltag findest du im Benutzer-Guide unter [Provisionspläne](/guide/commissions/plans) und [Auszahlungen](/guide/commissions/payouts).
</Info>

## Was ein Plan steuert

<CardGroup>
  <Card title="Provisionssatz" icon="percent">
    Ein Basissatz in Prozent, optional pro Produkt überschrieben.
  </Card>

  <Card title="Auslöser und Geltungsbereich" icon="receipt">
    Ob bei Rechnungsstellung oder Zahlungseingang provisioniert wird, und für welche Rechnungen.
  </Card>

  <Card title="Mindestauszahlung" icon="coins">
    Eine Provisionssumme, ab der ein Vertriebsmitarbeiter im Monat ausgezahlt wird.
  </Card>

  <Card title="Mindestumsatz" icon="chart-line">
    Ein Monatsumsatz, ab dem die Provisionen des Monats überhaupt laufen.
  </Card>
</CardGroup>

## Authentifizierung

Alle Endpunkte erwarten einen Bearer-Token deiner Organisation, der die Berechtigung für Provisionspläne trägt: Lesen für `GET`, Schreiben für `POST`, `PUT` und `DELETE`. Sende ihn im `Authorization`-Header:

```bash theme={null}
Authorization: Bearer <token>
```

<Note>
  Die Provisionen API ist als Beta gekennzeichnet und kann sich noch ändern. Verankere deine Integration gegen die datierte Version und beobachte das Changelog.
</Note>

Weiter geht es mit den [Kernkonzepten](/v2-commission-api/concepts): die Felder eines Plans und die beiden monatlichen Auszahlungsschwellen.


# Create a commission plan
Source: https://docs.fynn.eu/v2-commission-api/plans/create-plan

assets/openapi-v2-commission.json post /api/commissions/plans
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Create a commission plan. Both monthly thresholds are optional and are evaluated per sales rep, per plan, per calendar month.



# Delete a commission plan
Source: https://docs.fynn.eu/v2-commission-api/plans/delete-plan

assets/openapi-v2-commission.json delete /api/commissions/plans/{id}
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Delete a commission plan.



# Get a commission plan
Source: https://docs.fynn.eu/v2-commission-api/plans/get-plan

assets/openapi-v2-commission.json get /api/commissions/plans/{id}
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Fetch a single commission plan by id.



# List commission plans
Source: https://docs.fynn.eu/v2-commission-api/plans/list-plans

assets/openapi-v2-commission.json get /api/commissions/plans
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

List the commission plans of your Organisation. Supports cursor-based pagination by default and page-based pagination when you pass page or offset.



# Update a commission plan
Source: https://docs.fynn.eu/v2-commission-api/plans/update-plan

assets/openapi-v2-commission.json put /api/commissions/plans/{id}
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Update a commission plan. Only the fields you send are changed.



# Approve a pending request
Source: https://docs.fynn.eu/v2-offers-api/approval/approve

assets/openapi-v2-offers.json post /api/offers/{id}/approval/approve
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Records the caller's approval. On full quorum the version goes live and the offer auto-releases for signing. Only a named approver may decide.



# Cancel a pending request
Source: https://docs.fynn.eu/v2-offers-api/approval/cancel-approval

assets/openapi-v2-offers.json post /api/offers/{id}/approval/cancel
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Withdraws the pending approval request (requester or a holder of the offer-write permission). The version is superseded and the offer stays open for a re-publish.



# Get the approval state
Source: https://docs.fynn.eu/v2-offers-api/approval/get-approval

assets/openapi-v2-offers.json get /api/offers/{id}/approval
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Returns the approval status of the version under review, the running request (approvers and decisions) and whether the caller may decide. Internal staff only; never exposed to the recipient.



# Reject a pending request
Source: https://docs.fynn.eu/v2-offers-api/approval/reject

assets/openapi-v2-offers.json post /api/offers/{id}/approval/reject
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Records the caller's rejection with a required comment. The version is marked rejected and the offer stays open for a re-publish. Only a named approver may decide.



# Authentifizierung
Source: https://docs.fynn.eu/v2-offers-api/authentication

API-Token für die Angebots-Endpunkte und der persönliche Link für die öffentliche Ansicht.

Die Angebote-API kennt zwei Kontexte. Die Verwaltung (Angebote anlegen, veröffentlichen, Unterschriften anfordern) läuft serverseitig mit einem API-Token deiner Organisation. Die öffentliche Empfängeransicht erreichst du über den persönlichen Link, ohne Token.

## Basis-URLs

| Umgebung   | Basis-URL                    |
| ---------- | ---------------------------- |
| Produktion | `https://coreapi.io`         |
| Sandbox    | `https://preview.coreapi.io` |

## Verwaltung: API-Token

Die Verwaltungs-Endpunkte authentifizierst du mit einem API-Token deiner Organisation. Das Token ist fest an genau eine Organisation gebunden, du brauchst also keinen zusätzlichen Header.

```bash theme={null}
curl https://coreapi.io/offers \
  -H "Authorization: Bearer api_DEIN_TOKEN"
```

Ein API-Token legst du in den Entwickler-Einstellungen an. Eine ausführliche Anleitung findest du unter [Authentication](/api-reference/authentication).

<Warning>
  Behandle API-Token wie ein Passwort. Sie haben vollen Zugriff im Rahmen ihrer Berechtigungen. Gib sie niemals im Browser oder in einer mobilen App preis.
</Warning>

## Öffentliche Ansicht: der persönliche Link

Die öffentlichen Endpunkte unter `/public/offers` versorgen die Empfängeransicht. Der Zugriff erfolgt über den persönlichen Link, den jeder Empfänger per Einladung erhält. Dieser Link ist an die Person gebunden und nicht zum Teilen gedacht, eine zusätzliche Anmeldung gibt es nicht.

```bash theme={null}
curl https://coreapi.io/public/offers/OFFER_ID
```

<Note>
  Leitet ein Empfänger das Angebot weiter, erhält die neue Person ihren eigenen Link, statt den bestehenden zu teilen. So bleibt jeder Zugang nachvollziehbar.
</Note>


# Accept an offer manually
Source: https://docs.fynn.eu/v2-offers-api/offers/accept-offer

assets/openapi-v2-offers.json post /api/offers/{id}/accept
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Records a manual acceptance on behalf of the recipient, with an optional signed PDF upload. Use this for offers accepted outside the recipient view.



# Add a recipient
Source: https://docs.fynn.eu/v2-offers-api/offers/add-recipient

assets/openapi-v2-offers.json post /offers/{id}/recipients
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Adds another recipient to the offer, optionally with its own invitation email. The role controls whether the recipient may only read, sign, or counter-sign.



# Archive an offer
Source: https://docs.fynn.eu/v2-offers-api/offers/archive-offer

assets/openapi-v2-offers.json delete /offers/{id}
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Archives an offer. Archived offers are read-only and disappear from the active list.



# Cancel a signing process
Source: https://docs.fynn.eu/v2-offers-api/offers/cancel-signing

assets/openapi-v2-offers.json post /offers/{id}/cancel-signing
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Cancels a running e-signature process and returns the offer to the open state, so it can be edited and re-published.



# Download an offer as PDF
Source: https://docs.fynn.eu/v2-offers-api/offers/download-offer

assets/openapi-v2-offers.json get /offers/{id}/document
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Renders the current draft state of an offer as a PDF and returns it as a file download, e.g. to upload the offer into an external procurement portal. Unlike the public buyer document link this endpoint is authenticated and needs no recipient credential.



# Get an offer
Source: https://docs.fynn.eu/v2-offers-api/offers/get-offer

assets/openapi-v2-offers.json get /api/offers/{id}
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Returns the canonical v2 offer resource: structured contract value, grouped documents, recipients and links. The approval state is never embedded; fetch it via GET /api/offers/{id}/approval. This replaces the deprecated GET /offers/{id}.



# List offer activity
Source: https://docs.fynn.eu/v2-offers-api/offers/list-activities

assets/openapi-v2-offers.json get /api/offers/{id}/activities
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Returns the offer activity feed. Never empty: it always contains at least the creation entry.



# List offers
Source: https://docs.fynn.eu/v2-offers-api/offers/list-offers

assets/openapi-v2-offers.json get /offers
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Returns the offers of the organisation as a paginated list.



# Publish an offer
Source: https://docs.fynn.eu/v2-offers-api/offers/publish-offer

assets/openapi-v2-offers.json post /api/offers/{id}/publish
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Freezes the current draft as a version and either publishes it directly or, when an approval workflow matches, opens an approval request. The outcome tells you which happened. Optionally notifies recipients.



# Update an offer
Source: https://docs.fynn.eu/v2-offers-api/offers/update-offer

assets/openapi-v2-offers.json put /offers/{id}
**Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Updates the editable fields of a draft offer (title, document blocks, custom variables, acceptance mode, validity, auto-activation). Most fields freeze once the offer is accepted.



# Webhooks
Source: https://docs.fynn.eu/v2-offers-api/webhooks

Lass dein System in Echtzeit benachrichtigen, wenn ein Angebot abläuft. Aufbau des Envelopes, verfügbare Events und Beispiel-Payloads.

Webhooks für Angebote benachrichtigen dein System automatisch über Ereignisse im Lebenszyklus eines Angebots. Sobald ein Ereignis eintritt, sendet Fynn einen `POST`-Request mit strukturierten JSON-Daten an deine hinterlegte URL.

<Info>
  Die Einrichtung, die Zustellung und die Signaturprüfung sind für alle Webhooks gleich. Wie du Webhooks anlegst und absicherst, liest du unter [Webhooks einrichten](/guide/webhooks/introduction). Auf dieser Seite findest du nur, was für Angebote gilt: die verfügbaren Events und ihre Payloads.
</Info>

## Der Envelope

Jeder Angebots-Webhook hat denselben Aufbau. Das eigentliche Objekt steckt unter `data`, daneben liegen Metadaten zum Ereignis und der Vertriebskanal als Kontext.

<ResponseField name="event" type="object">
  Metadaten zum Ereignis.

  <Expandable title="event">
    <ResponseField name="id" type="string">
      Eindeutige Kennung dieser Zustellung (ULID), identisch mit dem Header `X-Webhook-Id`. Nutze sie, um Wiederholungen idempotent zu verarbeiten.
    </ResponseField>

    <ResponseField name="type" type="string">
      Der Ereignistyp, zum Beispiel `offer.expired`.
    </ResponseField>

    <ResponseField name="version" type="string">
      Schema-Version des Ereignisses, aktuell `v1`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Zeitpunkt der Auslösung im ISO-8601-Format.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="salesChannel" type="object | null">
  Der Vertriebskanal, in dessen Kontext das Ereignis entstand. `null`, wenn sich kein Kanal auflösen ließ.

  <Expandable title="salesChannel">
    <ResponseField name="id" type="string">
      Kennung des Vertriebskanals.
    </ResponseField>

    <ResponseField name="name" type="string">
      Technischer Name des Kanals, zum Beispiel `default`.
    </ResponseField>

    <ResponseField name="brandName" type="string">
      Anzeigename der Marke.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object">
  Die Nutzdaten des Ereignisses. Der Schlüssel darin benennt das betroffene Objekt, bei Angebots-Events also `offer`.
</ResponseField>

## HTTP-Header

Jede Zustellung bringt diese Header mit:

| Header                    | Inhalt                                                       |
| ------------------------- | ------------------------------------------------------------ |
| `X-Webhook-Event`         | Der Ereignistyp, zum Beispiel `offer.expired`.               |
| `X-Webhook-Event-Version` | Schema-Version, aktuell `v1`.                                |
| `X-Webhook-Id`            | Eindeutige Kennung der Zustellung, identisch mit `event.id`. |
| `X-Webhook-Signature`     | Signatur des Bodys zur Echtheitsprüfung.                     |
| `X-Sales-Channel`         | Technischer Name des Vertriebskanals, oder `default`.        |
| `X-Tenant-Id`             | Kennung deiner Organisation.                                 |

<Warning>
  Prüfe immer die Signatur aus `X-Webhook-Signature`, bevor du eine Zustellung verarbeitest. So stellst du sicher, dass die Anfrage wirklich von Fynn stammt. Den Ablauf und Beispielcode findest du unter [Webhooks einrichten](/guide/webhooks/introduction#sicherheit-x-webhook-signature).
</Warning>

## Verfügbare Events

| Event           | Wird ausgelöst, wenn                                                             |
| --------------- | -------------------------------------------------------------------------------- |
| `offer.expired` | Ein Angebot seinen Gültigkeitszeitraum überschreitet, bevor es angenommen wurde. |

<Note>
  Aktuell ist `offer.expired` das einzige Angebots-Event mit Webhook. Diese Liste wächst, wenn weitere Ereignisse hinzukommen.
</Note>

## `offer.expired`

Das Ereignis feuert, sobald die Gültigkeit eines Angebots verstreicht, solange es noch offen ist. Ein bereits angenommenes oder archiviertes Angebot läuft nie ab.

```mermaid theme={null}
flowchart LR
  Offen -->|Gültigkeit überschritten| Ablauf{Ablauf erkannt}
  Ablauf -->|regelmäßige Prüfung| Webhook[offer.expired]
  Ablauf -->|erster Aufruf des Links| Webhook
```

Fynn erkennt den Ablauf auf zwei Wegen: über eine regelmäßige Prüfung im Hintergrund und beim ersten Aufruf des abgelaufenen Links durch einen Empfänger. Egal welcher Weg zuerst greift, das Ereignis wird je Ablauf genau einmal gesendet. Verlängerst du ein abgelaufenes Angebot und es läuft erneut ab, gilt das als neues Ereignis.

### Das `offer`-Objekt

Unter `data.offer` erhältst du das Angebot in seiner Lese-Darstellung. Die wichtigsten Felder:

<ResponseField name="id" type="string">
  Eindeutige Kennung des Angebots. Nutze sie, um über die [Angebote-API](/v2-offers-api/offers/get-offer) den vollständigen Stand inklusive Kunde, Abonnement und Empfänger zu laden.
</ResponseField>

<ResponseField name="number" type="string">
  Fortlaufende Angebotsnummer, zum Beispiel `AN-2026-000042`.
</ResponseField>

<ResponseField name="name" type="string | null">
  Anzeigename des Angebots.
</ResponseField>

<ResponseField name="status" type="string">
  Der zuletzt gespeicherte Status: `open`, `signing`, `awaiting_invoice_details`, `signed` oder `archived`. Ein abgelaufenes Angebot behält seinen Status (meist `open`), der Ablauf selbst ergibt sich aus `validUntil`.
</ResponseField>

<ResponseField name="dealType" type="string">
  Art des Geschäfts: `new_business`, `expansion`, `renewal` oder `one_off`.
</ResponseField>

<ResponseField name="acceptanceMode" type="string">
  Wie der Empfänger zusagt: `click`, `esignature` oder `print`.
</ResponseField>

<ResponseField name="locale" type="string | null">
  Sprache des Angebots, zum Beispiel `de`.
</ResponseField>

<ResponseField name="validUntil" type="string | null">
  Datum, bis zu dem das Angebot angenommen werden konnte (ISO 8601). Bei `offer.expired` liegt dieser Zeitpunkt in der Vergangenheit.
</ResponseField>

<ResponseField name="issuedAt" type="string">
  Zeitpunkt der ersten Veröffentlichung (ISO 8601).
</ResponseField>

<ResponseField name="signed" type="boolean">
  Ob das Angebot vollständig unterschrieben ist.
</ResponseField>

<ResponseField name="signedAt" type="string | null">
  Zeitpunkt der vollständigen Unterschrift (ISO 8601), sonst `null`.
</ResponseField>

<ResponseField name="autoActivateSubscription" type="boolean">
  Ob aus dem angenommenen Angebot automatisch ein aktives Abonnement entsteht.
</ResponseField>

<ResponseField name="crmDealId" type="string | null">
  Verknüpfter Deal im CRM, sofern vorhanden.
</ResponseField>

<ResponseField name="customVariables" type="object | null">
  Eigene Variablen aus dem Editor als flaches Name-zu-Wert-Mapping.
</ResponseField>

<ResponseField name="capturedInvoiceDetails" type="object | null">
  Die vom Empfänger erfassten Rechnungsdaten, sofern bereits hinterlegt.
</ResponseField>

<ResponseField name="sections" type="array">
  Die Dokument-Blöcke des Angebots (Briefkopf, Parteien, Abonnement, Texte und mehr). Den Aufbau der Blöcke findest du unter [Kernkonzepte](/v2-offers-api/concepts).
</ResponseField>

<ResponseField name="publishedVersionHash" type="string | null">
  Prüfsumme der veröffentlichten Dokumentversion.
</ResponseField>

<ResponseField name="currentVersionHash" type="string | null">
  Prüfsumme der aktuellen Dokumentversion.
</ResponseField>

<ResponseField name="hasUnpublishedChanges" type="boolean">
  Ob seit der letzten Veröffentlichung Änderungen im Entwurf liegen.
</ResponseField>

<Note>
  Die Payload ist bewusst schlank. Verschachtelte Objekte wie `customer`, `subscription`, `recipients` und die Dokument-Referenzen sind im Webhook nicht ausgefüllt und kommen als leeres Objekt, leere Liste oder `null`. Brauchst du diese Details, lade das Angebot mit der `id` aus der Payload über [`GET /offers/{id}`](/v2-offers-api/offers/get-offer) nach.
</Note>

### Beispiel-Payload

```json theme={null}
{
  "event": {
    "id": "01JZ8F3KQ9X7N2VYB4C6D8E0FG",
    "type": "offer.expired",
    "version": "v1",
    "createdAt": "2026-06-29T08:00:01+00:00"
  },
  "salesChannel": {
    "id": "01JH2K8M4P6R8T0V2X4Z6B8D0F",
    "name": "default",
    "brandName": "Deine Marke"
  },
  "data": {
    "offer": {
      "id": "01JZ7A2B3C4D5E6F7G8H9J0K1L",
      "number": "AN-2026-000042",
      "name": "Angebot Enterprise-Plan 2026",
      "status": "open",
      "dealType": "new_business",
      "acceptanceMode": "esignature",
      "locale": "de",
      "validUntil": "2026-06-28T23:59:59+00:00",
      "issuedAt": "2026-06-01T10:00:00+00:00",
      "signed": false,
      "signedAt": null,
      "autoActivateSubscription": true,
      "crmDealId": null,
      "customVariables": null,
      "capturedInvoiceDetails": null,
      "publishedVersionHash": "8f14e45fceea167a5a36dedd4bea2543",
      "currentVersionHash": "8f14e45fceea167a5a36dedd4bea2543",
      "hasUnpublishedChanges": false,
      "sections": [
        { "type": "letterhead", "...": "..." },
        { "type": "parties", "...": "..." },
        { "type": "subscription", "...": "..." }
      ],
      "customer": {},
      "subscription": null,
      "recipients": [
        {}
      ],
      "purchaseOrderDocument": null,
      "auditLogDocument": null,
      "signedDocument": null,
      "contactPerson": {}
    }
  }
}
```

<Tip>
  Antworte mit einem `2xx`-Statuscode, sobald du die Zustellung angenommen hast. Schlägt die Zustellung fehl, wiederholt Fynn sie bis zu dreimal.
</Tip>


# Kernkonzepte
Source: https://docs.fynn.eu/v2-payment-plans-api/concepts

Plan und Rate im Detail, dazu Status, Einzug, Beträge und die wichtigsten Felder.

Ein Zahlungsplan hängt an genau einer offenen Rechnung und besteht aus einer geordneten Liste von Raten. Diese Seite erklärt die Felder, die du beim Anlegen setzt, und die Regeln dahinter.

## Plan

| Feld              | Typ            | Beschreibung                                                                                                                |
| ----------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id`              | string         | Kennung des Plans (UUID).                                                                                                   |
| `invoiceId`       | string         | Die Rechnung, die aufgeteilt wird.                                                                                          |
| `status`          | string         | Lebenszyklus: `active`, `completed`, `broken` oder `canceled`.                                                              |
| `totalAmount`     | integer        | Summe aller Raten in Cent. Entspricht bei der Anlage dem offenen Betrag der Rechnung.                                       |
| `currencyCode`    | string         | Währung, zum Beispiel `EUR`.                                                                                                |
| `paymentMethodId` | string \| null | Zahlungsmethode für den Einzug. Standard ist die Zahlungsmethode der Rechnung, ersatzweise die Standard-Methode des Kunden. |
| `createdAt`       | string         | Zeitpunkt der Anlage (ISO 8601).                                                                                            |
| `completedAt`     | string \| null | Zeitpunkt, an dem alle Raten bezahlt waren, sonst `null`.                                                                   |
| `brokenAt`        | string \| null | Zeitpunkt eines Planbruchs, sonst `null`.                                                                                   |
| `canceledAt`      | string \| null | Zeitpunkt der Kündigung, sonst `null`.                                                                                      |
| `brokenReason`    | string \| null | Grund des Planbruchs, sonst `null`.                                                                                         |
| `installments`    | array          | Die Raten, sortiert nach ihrer Position.                                                                                    |

### Status-Lebenszyklus

| Status      | Bedeutung                                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `active`    | Läuft. Das Mahnwesen für die Rechnung ruht, fällige Lastschrift-Raten werden eingezogen.                                      |
| `completed` | Abgeschlossen. Alle Raten sind bezahlt, die Rechnung ist beglichen.                                                           |
| `broken`    | Gebrochen. Eine Rate ist ausgefallen oder überfällig geblieben. Der Restbetrag ist sofort fällig, das Mahnwesen läuft wieder. |
| `canceled`  | Gekündigt. Der Plan wurde manuell beendet, das Mahnwesen läuft wieder.                                                        |

```mermaid theme={null}
flowchart LR
  Anlegen --> active
  active -->|alle Raten bezahlt| completed
  active -->|Rate ausgefallen oder überfällig| broken
  active -->|manuell gekündigt| canceled
  broken -->|verlängern| active
```

<Note>
  Solange der Plan `active` ist, wird die Rechnung im Mahnlauf übersprungen. In jedem anderen Status wird sie wieder wie üblich gemahnt. Ein gebrochener Plan lässt sich [verlängern](/v2-payment-plans-api/payment-plans/extend-payment-plan) und kehrt damit nach `active` zurück.
</Note>

## Rate

Eine Rate (`installment`) ist ein Teilbetrag mit einem Fälligkeitsdatum.

| Feld       | Typ            | Beschreibung                                                      |
| ---------- | -------------- | ----------------------------------------------------------------- |
| `id`       | string         | Kennung der Rate (UUID).                                          |
| `position` | integer        | Rang innerhalb des Plans, beginnend bei 1.                        |
| `dueAt`    | string         | Fälligkeitsdatum im Format `Y-m-d`.                               |
| `amount`   | integer        | Betrag der Rate in Cent.                                          |
| `status`   | string         | `open`, `collecting`, `paid` oder `failed`.                       |
| `paidAt`   | string \| null | Zeitpunkt, an dem die Rate vollständig gedeckt war, sonst `null`. |

### Raten-Status

| Status       | Bedeutung                                                             |
| ------------ | --------------------------------------------------------------------- |
| `open`       | Offen. Noch nicht eingezogen und noch nicht gedeckt.                  |
| `collecting` | Im Einzug. Für diese Rate wurde eine Lastschrift ausgelöst und läuft. |
| `paid`       | Bezahlt. Der Betrag ist eingegangen.                                  |
| `failed`     | Fehlgeschlagen. Der Einzug ist gescheitert, der Plan bricht.          |

## Beträge und Rundung

Alle Beträge sind ganze Zahlen in der kleinsten Währungseinheit (Cent). `1190` bedeutet 11,90 Euro.

Die Summe der Raten muss dem offenen Betrag der Rechnung zum Zeitpunkt der Anlage entsprechen. Stimmt sie nicht, antwortet die API mit `422` und dem Schlüssel `PAYMENT_PLAN__SUM_MISMATCH`.

Im Split-Modus teilt Fynn den offenen Betrag gleichmäßig auf. Geht die Division nicht glatt auf, landet der Rundungsrest auf der **letzten** Rate. Beispiel: 100,00 Euro in drei Raten ergibt 33,33 / 33,33 / 33,34.

## Anlegen: manuell oder splitten

Beim Anlegen wählst du genau einen der beiden Wege. Sendest du beide oder keinen, antwortet die API mit `422`.

<CodeGroup>
  ```json Manuell (installments) theme={null}
  {
    "invoiceId": "10000000-0000-0000-0003-000000000001",
    "installments": [
      { "dueAt": "2026-08-05", "amount": 595 },
      { "dueAt": "2026-09-05", "amount": 595 }
    ]
  }
  ```

  ```json Gleichmäßig (split) theme={null}
  {
    "invoiceId": "10000000-0000-0000-0003-000000000001",
    "split": { "count": 3, "interval": "1M", "firstDueAt": "2026-08-05" }
  }
  ```
</CodeGroup>

* **Manuell (`installments`):** Du gibst jede Rate mit Datum und Betrag vor. Die Termine müssen aufsteigend und in der Zukunft liegen, jeder Betrag positiv sein.
* **Gleichmäßig (`split`):** Du gibst `count` (2 bis 36), `interval` (Abstand als `{n}{D|W|M|Y}`, Standard `1M`) und `firstDueAt` an. Fynn berechnet Beträge und Termine.

<Info>
  Eine Rechnung kann nur einen aktiven Plan haben. Ein neuer Plan ist erst möglich, wenn ein bestehender abgeschlossen, gebrochen oder gekündigt ist. Um einem Kunden mehr Zeit zu geben, [verlängere](/v2-payment-plans-api/payment-plans/extend-payment-plan) den bestehenden Plan, statt einen neuen anzulegen.
</Info>

## Einzug und Erinnerung

Die Zahlungsmethode des Plans bestimmt, wie eine Rate beglichen wird.

* **Lastschrift (SEPA):** Fynn löst den Einzug automatisch sieben Tage vor Fälligkeit aus. Die Rate wechselt dabei auf `collecting`.
* **Überweisung:** Der Kunde überweist selbst. Fynn ordnet den Zahlungseingang der offenen Rechnung zu.

In beiden Fällen erhält der Kunde sieben Tage vor Fälligkeit eine E-Mail, entweder als Ankündigung des Einzugs oder als Zahlungsaufforderung.

## Voraussetzungen an die Rechnung

Ein Plan lässt sich nur für eine Rechnung anlegen, die

* finalisiert und offen ist (nicht Entwurf, bezahlt, storniert oder erstattet), und
* noch keinen aktiven Plan hat.

Ist die Rechnung nicht geeignet, antwortet die API mit `422` und dem Schlüssel `PAYMENT_PLAN__INVOICE_NOT_ELIGIBLE`.


# Zahlungsplan API
Source: https://docs.fynn.eu/v2-payment-plans-api/introduction

Splitte eine offene Rechnung in zinsfreie Raten, halte das Mahnwesen an und lass Fynn Lastschrift-Raten automatisch einziehen.

Mit einem **Zahlungsplan** teilst du eine offene Rechnung in mehrere Raten auf. Solange der Plan läuft, ruht das Mahnwesen für diese Rechnung, und Fynn zieht fällige Lastschrift-Raten automatisch ein. Bricht der Kunde den Plan, wird der Restbetrag sofort fällig und das Mahnwesen läuft weiter.

<Info>
  Zahlungspläne bildest du über die V2-Endpunkte unter `/api/payment-plans` ab. Für alles rund um die Rechnung selbst nutzt du weiterhin die [API-Referenz](/api-reference/introduction).
</Info>

## So funktioniert es

<CardGroup>
  <Card title="Aufteilen" icon="scissors">
    Eine offene Rechnung in gleich große Raten splitten oder Beträge und Termine manuell festlegen.
  </Card>

  <Card title="Einziehen" icon="building-columns">
    Bei Lastschrift zieht Fynn jede Rate automatisch ein, sieben Tage vor Fälligkeit angekündigt.
  </Card>

  <Card title="Nachhalten" icon="bell">
    Webhooks melden bezahlte Raten, den Abschluss, einen Planbruch, Verlängerungen und Kündigungen.
  </Card>
</CardGroup>

## Ein Betrag, eine Rechnung

Ein Zahlungsplan zerlegt nicht die Rechnung, sondern verteilt ihren offenen Betrag über die Zeit. Die Rechnung bleibt eine Rechnung: Sobald alle Raten bezahlt sind, ist sie beglichen. Jede eingezogene oder überwiesene Rate zählt auf denselben offenen Betrag, egal ob sie per Lastschrift kam oder als Überweisung eingegangen ist.

<CardGroup>
  <Card title="Schnellstart" icon="rocket" href="/v2-payment-plans-api/quickstart">
    Von der offenen Rechnung bis zum laufenden Plan in wenigen Aufrufen.
  </Card>

  <Card title="Kernkonzepte" icon="book" href="/v2-payment-plans-api/concepts">
    Plan, Rate, Status, Einzug und die wichtigsten Felder.
  </Card>

  <Card title="Webhooks" icon="bell" href="/v2-payment-plans-api/webhooks">
    Die sechs Events im Lebenszyklus eines Plans mit Beispiel-Payloads.
  </Card>

  <Card title="API-Referenz" icon="code" href="/v2-payment-plans-api/payment-plans/create-payment-plan">
    Alle Endpunkte mit Parametern, Antworten und Beispielen.
  </Card>
</CardGroup>


# Cancel a payment plan
Source: https://docs.fynn.eu/v2-payment-plans-api/payment-plans/cancel-payment-plan

assets/openapi-v2-payment-plans.json post /api/payment-plans/{id}/cancel
Cancel an active or broken payment plan. No request body. The plan moves to `canceled` and dunning for the invoice resumes on the next run, because the open amount is due again. A completed or already canceled plan cannot be canceled (422).



# Create a payment plan
Source: https://docs.fynn.eu/v2-payment-plans-api/payment-plans/create-payment-plan

assets/openapi-v2-payment-plans.json post /api/payment-plans
Split an open, finalized invoice into installments. Send EITHER an explicit `installments` array OR a `split` object, never both and never neither. The installment amounts (or the computed split) must sum to the current open amount of the invoice in cents. In split mode the rounding remainder is added to the last installment. The invoice must be finalized and open (not draft, paid, canceled or refunded) and must not already have an active plan. While the plan is active, dunning for the invoice is paused.



# Extend a payment plan
Source: https://docs.fynn.eu/v2-payment-plans-api/payment-plans/extend-payment-plan

assets/openapi-v2-payment-plans.json post /api/payment-plans/{id}/extend
Replace every not-yet-paid installment with a new schedule. Already paid installments stay untouched. Send EITHER `installments` OR `split`, exactly like create but without `invoiceId`. The new schedule must sum to the current open amount of the invoice in cents (in split mode the server computes it). A broken plan returns to `active`, and `brokenAt` and `brokenReason` are cleared. Use this instead of creating a new plan when a customer misses an installment or needs more time.



# Get the payment plan of an invoice
Source: https://docs.fynn.eu/v2-payment-plans-api/payment-plans/get-invoice-payment-plan

assets/openapi-v2-payment-plans.json get /api/invoices/{id}/payment-plan
Return the payment plan attached to an invoice. If an active plan exists it is returned, otherwise the most recent plan of any status. Responds with 404 if the invoice never had a plan.



# Get a payment plan
Source: https://docs.fynn.eu/v2-payment-plans-api/payment-plans/get-payment-plan

assets/openapi-v2-payment-plans.json get /api/payment-plans/{id}
Return a single payment plan with its installments.



# Schnellstart
Source: https://docs.fynn.eu/v2-payment-plans-api/quickstart

Von der offenen Rechnung bis zum laufenden Zahlungsplan in wenigen Aufrufen.

Dieser Schnellstart führt dich einmal durch den Ablauf: für eine offene Rechnung einen Zahlungsplan anlegen, ihn abrufen und bei Bedarf verlängern oder kündigen. Alle Beispiele nutzen die Sandbox unter `https://preview.coreapi.io`. Die vollständigen Parameter und Antwortfelder findest du jeweils auf der verlinkten Referenzseite.

<Steps>
  <Step title="Zahlungsplan anlegen">
    Splitte den offenen Betrag einer finalisierten, unbezahlten Rechnung. Hier gleichmäßig in drei Monatsraten ab dem 5. August.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/payment-plans \
      -H "Authorization: Bearer api_DEIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "invoiceId": "INVOICE_ID",
        "split": { "count": 3, "interval": "1M", "firstDueAt": "2026-08-05" }
      }'
    ```

    Alternativ legst du die Raten manuell fest:

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/payment-plans \
      -H "Authorization: Bearer api_DEIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "invoiceId": "INVOICE_ID",
        "installments": [
          { "dueAt": "2026-08-05", "amount": 595 },
          { "dueAt": "2026-09-05", "amount": 595 }
        ]
      }'
    ```

    Die Antwort enthält den Plan mit `"status": "active"` und den generierten Raten. Notiere dir die `id` des Plans.

    Alle Felder und Antworten: [Zahlungsplan anlegen](/v2-payment-plans-api/payment-plans/create-payment-plan).
  </Step>

  <Step title="Plan abrufen">
    Frage den Plan mit seinen Raten und deren Status jederzeit ab.

    ```bash theme={null}
    curl https://preview.coreapi.io/api/payment-plans/PLAN_ID \
      -H "Authorization: Bearer api_DEIN_TOKEN"
    ```

    Kennst du nur die Rechnung, nutzt du den rechnungsbezogenen Endpunkt. Er liefert den aktiven Plan, sonst den zuletzt angelegten.

    ```bash theme={null}
    curl https://preview.coreapi.io/api/invoices/INVOICE_ID/payment-plan \
      -H "Authorization: Bearer api_DEIN_TOKEN"
    ```

    Referenz: [Plan abrufen](/v2-payment-plans-api/payment-plans/get-payment-plan) und [Plan einer Rechnung abrufen](/v2-payment-plans-api/payment-plans/get-invoice-payment-plan).
  </Step>

  <Step title="Auf Ereignisse reagieren">
    Statt den Plan abzufragen, lässt du dich benachrichtigen. Bei jeder bezahlten Rate feuert `payment_plan.rate_paid`, beim Abschluss `payment_plan.completed`, bei einem Planbruch `payment_plan.broken`. Den Aufbau der Payloads findest du unter [Webhooks](/v2-payment-plans-api/webhooks).
  </Step>

  <Step title="Verlängern statt neu anlegen">
    Braucht der Kunde mehr Zeit oder ist eine Rate ausgefallen, verlängere den Plan. Das ersetzt alle noch nicht bezahlten Raten durch einen neuen Zeitplan. Ein gebrochener Plan kehrt damit nach `active` zurück.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/payment-plans/PLAN_ID/extend \
      -H "Authorization: Bearer api_DEIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "split": { "count": 4, "interval": "1M", "firstDueAt": "2026-10-05" } }'
    ```

    Referenz: [Plan verlängern](/v2-payment-plans-api/payment-plans/extend-payment-plan).
  </Step>

  <Step title="Kündigen">
    Soll der Plan enden, kündige ihn. Der Restbetrag ist danach sofort fällig, das Mahnwesen läuft wieder.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/payment-plans/PLAN_ID/cancel \
      -H "Authorization: Bearer api_DEIN_TOKEN"
    ```

    Referenz: [Plan kündigen](/v2-payment-plans-api/payment-plans/cancel-payment-plan).
  </Step>
</Steps>

## Nächste Schritte

<CardGroup>
  <Card title="Kernkonzepte" icon="book" href="/v2-payment-plans-api/concepts">
    Plan, Rate, Status, Einzug und die Rundungsregel im Detail.
  </Card>

  <Card title="Webhooks" icon="bell" href="/v2-payment-plans-api/webhooks">
    Die sechs Events im Lebenszyklus eines Plans mit Beispiel-Payloads.
  </Card>
</CardGroup>


# Webhooks
Source: https://docs.fynn.eu/v2-payment-plans-api/webhooks

Lass dein System in Echtzeit über den Lebenszyklus eines Zahlungsplans benachrichtigen. Aufbau des Envelopes, verfügbare Events und Beispiel-Payloads.

Webhooks für Zahlungspläne benachrichtigen dein System automatisch über Ereignisse im Lebenszyklus eines Plans. Sobald ein Ereignis eintritt, sendet Fynn einen `POST`-Request mit strukturierten JSON-Daten an deine hinterlegte URL.

<Info>
  Die Einrichtung, die Zustellung und die Signaturprüfung sind für alle Webhooks gleich. Wie du Webhooks anlegst und absicherst, liest du unter [Webhooks einrichten](/guide/webhooks/introduction). Auf dieser Seite findest du nur, was für Zahlungspläne gilt: die verfügbaren Events und ihre Payloads.
</Info>

## Der Envelope

Jeder Zahlungsplan-Webhook hat denselben Aufbau. Das eigentliche Objekt steckt unter `data`, daneben liegen Metadaten zum Ereignis.

<ResponseField name="event" type="object">
  Metadaten zum Ereignis.

  <Expandable title="event">
    <ResponseField name="id" type="string">
      Eindeutige Kennung dieser Zustellung (ULID), identisch mit dem Header `X-Webhook-Id`. Nutze sie, um Wiederholungen idempotent zu verarbeiten.
    </ResponseField>

    <ResponseField name="type" type="string">
      Der Ereignistyp, zum Beispiel `payment_plan.rate_paid`.
    </ResponseField>

    <ResponseField name="version" type="string">
      Schema-Version des Ereignisses, aktuell `v1`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Zeitpunkt der Auslösung im ISO-8601-Format.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object">
  Die Nutzdaten des Ereignisses. Der Schlüssel `paymentPlan` enthält den Plan. Bei `payment_plan.rate_paid` liegt zusätzlich unter `installment` die soeben bezahlte Rate.
</ResponseField>

## HTTP-Header

Jede Zustellung bringt diese Header mit:

| Header                    | Inhalt                                                       |
| ------------------------- | ------------------------------------------------------------ |
| `X-Webhook-Event`         | Der Ereignistyp, zum Beispiel `payment_plan.broken`.         |
| `X-Webhook-Event-Version` | Schema-Version, aktuell `v1`.                                |
| `X-Webhook-Id`            | Eindeutige Kennung der Zustellung, identisch mit `event.id`. |
| `X-Webhook-Signature`     | Signatur des Bodys zur Echtheitsprüfung.                     |
| `X-Tenant-Id`             | Kennung deiner Organisation.                                 |

<Warning>
  Prüfe immer die Signatur aus `X-Webhook-Signature`, bevor du eine Zustellung verarbeitest. So stellst du sicher, dass die Anfrage wirklich von Fynn stammt. Den Ablauf und Beispielcode findest du unter [Webhooks einrichten](/guide/webhooks/introduction#sicherheit-x-webhook-signature).
</Warning>

## Verfügbare Events

| Event                    | Wird ausgelöst, wenn                                          |
| ------------------------ | ------------------------------------------------------------- |
| `payment_plan.created`   | Ein Zahlungsplan für eine offene Rechnung angelegt wird.      |
| `payment_plan.rate_paid` | Eine Rate vollständig gedeckt ist.                            |
| `payment_plan.completed` | Alle Raten bezahlt sind und die Rechnung damit beglichen ist. |
| `payment_plan.broken`    | Ein Einzug ausfällt oder eine Rate überfällig bleibt.         |
| `payment_plan.canceled`  | Ein Plan manuell gekündigt wird.                              |
| `payment_plan.extended`  | Ein Plan mit einem neuen Zeitplan verlängert wird.            |

```mermaid theme={null}
flowchart LR
  A[payment_plan.created] --> B[payment_plan.rate_paid]
  B --> B
  B --> C[payment_plan.completed]
  A --> D[payment_plan.broken]
  D -->|extend| E[payment_plan.extended]
  A --> F[payment_plan.canceled]
```

## Das `paymentPlan`-Objekt

Unter `data.paymentPlan` erhältst du den Plan in seiner Lese-Darstellung, identisch zur Antwort der [Plan-Endpunkte](/v2-payment-plans-api/payment-plans/get-payment-plan). Die wichtigsten Felder:

<ResponseField name="id" type="string">
  Eindeutige Kennung des Plans. Nutze sie, um über [`GET /payment-plans/{id}`](/v2-payment-plans-api/payment-plans/get-payment-plan) den vollständigen Stand nachzuladen.
</ResponseField>

<ResponseField name="invoiceId" type="string">
  Die Rechnung, die aufgeteilt wird.
</ResponseField>

<ResponseField name="status" type="string">
  Der Status des Plans: `active`, `completed`, `broken` oder `canceled`.
</ResponseField>

<ResponseField name="totalAmount" type="integer">
  Summe aller Raten in Cent.
</ResponseField>

<ResponseField name="currencyCode" type="string">
  Währung, zum Beispiel `EUR`.
</ResponseField>

<ResponseField name="brokenReason" type="string | null">
  Grund des Planbruchs, sonst `null`.
</ResponseField>

<ResponseField name="installments" type="array">
  Die Raten des Plans mit `position`, `dueAt`, `amount`, `status` und `paidAt`.
</ResponseField>

## `payment_plan.created`

Feuert, sobald ein Plan angelegt ist. Ab jetzt ruht das Mahnwesen für die Rechnung.

```json theme={null}
{
  "event": {
    "id": "01JZ8F3KQ9X7N2VYB4C6D8E0FG",
    "type": "payment_plan.created",
    "version": "v1",
    "createdAt": "2026-07-05T16:20:00+00:00"
  },
  "data": {
    "paymentPlan": {
      "id": "10000000-0000-0000-00e0-000000000001",
      "invoiceId": "10000000-0000-0000-0003-000000000001",
      "status": "active",
      "totalAmount": 1190,
      "currencyCode": "EUR",
      "paymentMethodId": "10000000-0000-0000-004f-000000000001",
      "createdAt": "2026-07-05T16:20:00+00:00",
      "completedAt": null,
      "brokenAt": null,
      "canceledAt": null,
      "brokenReason": null,
      "installments": [
        { "id": "…", "position": 1, "dueAt": "2026-08-05", "amount": 595, "status": "open", "paidAt": null },
        { "id": "…", "position": 2, "dueAt": "2026-09-05", "amount": 595, "status": "open", "paidAt": null }
      ]
    }
  }
}
```

## `payment_plan.rate_paid`

Feuert, sobald eine Rate vollständig gedeckt ist. Nur bei diesem Event liegt neben `paymentPlan` auch die betroffene Rate unter `installment`.

```json theme={null}
{
  "event": {
    "id": "01JZ8G4M0RY8P3WZC5D7E9F1GH",
    "type": "payment_plan.rate_paid",
    "version": "v1",
    "createdAt": "2026-08-05T04:00:03+00:00"
  },
  "data": {
    "paymentPlan": {
      "id": "10000000-0000-0000-00e0-000000000001",
      "invoiceId": "10000000-0000-0000-0003-000000000001",
      "status": "active",
      "totalAmount": 1190,
      "currencyCode": "EUR",
      "paymentMethodId": "10000000-0000-0000-004f-000000000001",
      "createdAt": "2026-07-05T16:20:00+00:00",
      "completedAt": null,
      "brokenAt": null,
      "canceledAt": null,
      "brokenReason": null,
      "installments": [
        { "id": "…", "position": 1, "dueAt": "2026-08-05", "amount": 595, "status": "paid", "paidAt": "2026-08-05T04:00:02+00:00" },
        { "id": "…", "position": 2, "dueAt": "2026-09-05", "amount": 595, "status": "open", "paidAt": null }
      ]
    },
    "installment": {
      "id": "…",
      "position": 1,
      "dueAt": "2026-08-05",
      "amount": 595,
      "status": "paid",
      "paidAt": "2026-08-05T04:00:02+00:00"
    }
  }
}
```

## `payment_plan.completed`

Feuert, sobald die letzte offene Rate gedeckt ist. Die Rechnung ist damit beglichen.

```json theme={null}
{
  "event": {
    "id": "01JZ9A5N1SZ9Q4XAD6E8F0G2HJ",
    "type": "payment_plan.completed",
    "version": "v1",
    "createdAt": "2026-09-05T04:00:04+00:00"
  },
  "data": {
    "paymentPlan": {
      "id": "10000000-0000-0000-00e0-000000000001",
      "invoiceId": "10000000-0000-0000-0003-000000000001",
      "status": "completed",
      "totalAmount": 1190,
      "currencyCode": "EUR",
      "paymentMethodId": "10000000-0000-0000-004f-000000000001",
      "createdAt": "2026-07-05T16:20:00+00:00",
      "completedAt": "2026-09-05T04:00:03+00:00",
      "brokenAt": null,
      "canceledAt": null,
      "brokenReason": null,
      "installments": [
        { "id": "…", "position": 1, "dueAt": "2026-08-05", "amount": 595, "status": "paid", "paidAt": "2026-08-05T04:00:02+00:00" },
        { "id": "…", "position": 2, "dueAt": "2026-09-05", "amount": 595, "status": "paid", "paidAt": "2026-09-05T04:00:03+00:00" }
      ]
    }
  }
}
```

## `payment_plan.broken`

Feuert, sobald der Plan bricht: ein Lastschrift-Einzug ist fehlgeschlagen, oder eine Rate ist über ihre Frist hinaus unbeglichen geblieben. Der Restbetrag ist ab jetzt sofort fällig, und das Mahnwesen für die Rechnung läuft wieder. `brokenReason` nennt den Auslöser.

```json theme={null}
{
  "event": {
    "id": "01JZ9B6P2T0R5YBE7F9G1H3J4K",
    "type": "payment_plan.broken",
    "version": "v1",
    "createdAt": "2026-08-06T05:00:01+00:00"
  },
  "data": {
    "paymentPlan": {
      "id": "10000000-0000-0000-00e0-000000000001",
      "invoiceId": "10000000-0000-0000-0003-000000000001",
      "status": "broken",
      "totalAmount": 1190,
      "currencyCode": "EUR",
      "paymentMethodId": "10000000-0000-0000-004f-000000000001",
      "createdAt": "2026-07-05T16:20:00+00:00",
      "completedAt": null,
      "brokenAt": "2026-08-06T05:00:00+00:00",
      "canceledAt": null,
      "brokenReason": "installment collection failed",
      "installments": [
        { "id": "…", "position": 1, "dueAt": "2026-08-05", "amount": 595, "status": "failed", "paidAt": null },
        { "id": "…", "position": 2, "dueAt": "2026-09-05", "amount": 595, "status": "open", "paidAt": null }
      ]
    }
  }
}
```

## `payment_plan.canceled`

Feuert, sobald ein Plan manuell gekündigt wird. Der offene Betrag wird wieder normal gemahnt.

```json theme={null}
{
  "event": {
    "id": "01JZ9C7Q3U1S6ZCF8G0H2J4K5L",
    "type": "payment_plan.canceled",
    "version": "v1",
    "createdAt": "2026-08-10T09:15:00+00:00"
  },
  "data": {
    "paymentPlan": {
      "id": "10000000-0000-0000-00e0-000000000001",
      "invoiceId": "10000000-0000-0000-0003-000000000001",
      "status": "canceled",
      "totalAmount": 1190,
      "currencyCode": "EUR",
      "paymentMethodId": "10000000-0000-0000-004f-000000000001",
      "createdAt": "2026-07-05T16:20:00+00:00",
      "completedAt": null,
      "brokenAt": null,
      "canceledAt": "2026-08-10T09:15:00+00:00",
      "brokenReason": null,
      "installments": [
        { "id": "…", "position": 1, "dueAt": "2026-08-05", "amount": 595, "status": "paid", "paidAt": "2026-08-05T04:00:02+00:00" },
        { "id": "…", "position": 2, "dueAt": "2026-09-05", "amount": 595, "status": "open", "paidAt": null }
      ]
    }
  }
}
```

## `payment_plan.extended`

Feuert, sobald ein Plan mit einem neuen Zeitplan verlängert wird. Ein zuvor gebrochener Plan steht danach wieder auf `active`, `brokenAt` und `brokenReason` sind geleert.

```json theme={null}
{
  "event": {
    "id": "01JZ9D8R4V2T7ADG9H1J3K5L6M",
    "type": "payment_plan.extended",
    "version": "v1",
    "createdAt": "2026-08-07T11:00:00+00:00"
  },
  "data": {
    "paymentPlan": {
      "id": "10000000-0000-0000-00e0-000000000001",
      "invoiceId": "10000000-0000-0000-0003-000000000001",
      "status": "active",
      "totalAmount": 1190,
      "currencyCode": "EUR",
      "paymentMethodId": "10000000-0000-0000-004f-000000000001",
      "createdAt": "2026-07-05T16:20:00+00:00",
      "completedAt": null,
      "brokenAt": null,
      "canceledAt": null,
      "brokenReason": null,
      "installments": [
        { "id": "…", "position": 1, "dueAt": "2026-08-05", "amount": 595, "status": "failed", "paidAt": null },
        { "id": "…", "position": 2, "dueAt": "2026-10-05", "amount": 297, "status": "open", "paidAt": null },
        { "id": "…", "position": 3, "dueAt": "2026-11-05", "amount": 298, "status": "open", "paidAt": null }
      ]
    }
  }
}
```

<Tip>
  Antworte mit einem `2xx`-Statuscode, sobald du die Zustellung angenommen hast. Schlägt die Zustellung fehl, wiederholt Fynn sie bis zu dreimal.
</Tip>


# Authentication
Source: https://docs.fynn.eu/api-reference/authentication

All API endpoints are authenticated using Bearer tokens and picked up from the specification file.

Authentication is a crucial aspect of interacting with the Fynn API. This guide will walk you through the process of setting up and managing API keys for authentication, as well as authenticating requests both as a platform and as a customer.

## Setting Up API Keys

To interact with the Fynn API, you need to generate an API key. Follow these steps to create an API key:

1. Log in to your Fynn account (or sign up for a new account if you don't have one) at [https://app.fynn.eu](https://app.fynn.eu).
2. Navigate to the Developer Settings page by clicking on the settings icon on the top-right side and selecting "Settings" > "Developer" or visit [https://app.fynn.eu/settings/developer](https://app.fynn.eu/settings/developer).
3. Click on the "Add API Key" button.
4. Provide a name for your API key to help you identify its purpose.
5. \[optional] Define the expiration date for the API key. If you don't set an expiration date, the API key will never expire.
6. Click "Generate" to create the API key.
7. Your API key will be displayed. Make sure to copy and securely store it, as it will not be shown again.

## Deleting API Keys

To delete an API key, follow these steps:

1. Go to the Developer Settings page.
2. Locate the API key you wish to delete.
3. Click on the "Delete" button next to the API key.
4. Confirm the deletion when prompted.

<Warning>
  <p>Deleting an API key will immediately revoke access to the API for any application or service using it. Make sure to update your applications and services with a new API key before deleting the old one.</p>
</Warning>

## Authenticating Requests

To authenticate your requests to the Fynn API, include your API key in the request headers as follows:

```plaintext theme={null}
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

<Note>
  The same Bearer token connects AI Tools to Fynn through the [MCP server](/guide/developers/mcp-server).
</Note>

## Authenticating as a Customer

Customers can authenticate themselves with the API to access their own data, such as payment methods and subscription details.
This is done by making a POST request to our api:

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
  --url https://[preview.]coreapi.io/customers/{id}/authenticate \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```json Response theme={null}
  {
      "data": {
      "accessToken": "xxx",
      "refreshToken": "xxx"
      }
  }
  ```
</CodeGroup>

Replace `YOUR_API_KEY` with your actual API key.

### Limitations

When authenticated as a customer, access is restricted to the customer's own data. This means that only operations related to the authenticated customer, such as managing payment methods, subscriptions, or viewing account details, are permitted.

Have a look on following permissions on the API routes:

* `ROLE_CUSTOMER`
* `customer:self:read`
* `customer:payment-method:add`
* `customer:payment-method:read`


# Manage payment methods on your own payment page
Source: https://docs.fynn.eu/api-reference/guides/add-payment-method

Learn how to manage payment methods on your own payment page.

## Fynn elements

We are currently working on a new feature that allows you to manage payment methods on your own payment page without any business-code. This feature is called Fynn elements and will be available in Q2.24.

## Add new payment method

The following steps show you how to add a new payment method using the Fynn API on your own payment page.

<Tabs>
  <Tab title="Stripe Credit card">
    <Steps>
      <Step title="Create stripe setup intent">
        To add a new payment method, you need to create a Stripe SetupIntent first in order to securely collect card details in Fynn.

        ```bash theme={null}
        curl -X POST \
        /payment-methods \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer <token>" \
        --data '{
            "gateway": "stripe",
            "type": "card",
            "customerId": "<customerId>",
            "isDefault": true,
            "futureUsageAllowed": true,
            "stripe": {
                "paymentMethodId": null,
                "customerId": null
            }
        }'
        ```

        **Example response**

        ```json theme={null}
        {
            "status": "action_required",
            "action_required": {
                "action": "client_site_action",
                "details": {
                    "clientSecret": "test_1234567890",
                    "publishableKey": "pk_test_1234567890"
                    "accountId": "acct_1234567890",
                }
            }
        }
        ```
      </Step>

      <Step title="Collect card details">
        After creating the SetupIntent, you can show the Stripe.js card element in your form to collect the card details.
        Then confirm the SetupIntent with the card details.

        ```html theme={null}
        <html>
        <head>
            <script src="https://js.stripe.com/v3/"></script>
            <script>
                var stripe = Stripe('pk_test_1234567890:<publishableKey>', { // previously received from the response
                    stripeAccount: 'acct_1234567890:<accountId>' // previously received from the response
                });

                // see: https://docs.stripe.com/js/element/other_element?type=card
                var elements = stripe.elements();
                var card = elements.create('card');
                card.mount('#card-element');

                var paymentIntentClientSecret = '<clientSecret>'; // previously received from the response

                var form = document.getElementById('payment-form');
                form.addEventListener('submit', function(event) {
                    event.preventDefault();
                    stripe.confirmCardSetup(paymentIntentClientSecret, {
                        payment_method: {
                            card: card,
                            billing_details: {
                                name: 'Jenny Rosen'
                            }
                        }
                    }).then(function(result) {
                        if (result.error) {
                            console.log(result.error.message);
                        } else {
                            console.log(result.setupIntent.payment_method);

                            // send payment method id to fynn
                            // see: https://docs.fynn.app/api-reference/paymentmethod/create-payment-method
                        }
                    });
                });
            </script>
        </head>
        <body>
            <form id="payment-form">
                <div id="card-element"></div>
                <button id="submit">Submit</button>
            </form>
        </body>
        </html>
        ```
      </Step>

      <Step title="Assign payment method">
        Assign the payment method created in stripe with Fynn. Use the payment method id received from the confirmation `result.setupIntent.payment_method`.

        ```bash theme={null}
        curl -X POST \
        /payment-methods \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer <token>" \
        --data '{
            "gateway": "stripe",
            "type": "card",
            "customerId": "<customerId>",
            "isDefault": true,
            "futureUsageAllowed": true,
            "stripe": {
                "paymentMethodId": "pm_1J4X2n2eZvKYlo2C2Q2Q2Q2Q2", // result.setupIntent.payment_method
            }
        }'
        ```
      </Step>

      <Step title="Done 🎉">
        That's it! You have successfully added a new card payment method to the customer.
      </Step>
    </Steps>
  </Tab>

  <Tab title="SEPA debit (via Fynn)">
    Collect the customer's SEPA details in your own form and create a new payment method:

    ```bash theme={null}
    curl -X POST \
    /payment-methods \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer <token>" \
    --data '{
        "gateway": "sepa_debit",
        "type": "sepa_debit",
        "customerId": "<customerId>",
        "isDefault": true,
        "futureUsageAllowed": true,
        "sepaMandate": {
            "iban": "DE89370400440532013000",
            "bic": "COBADEFFXXX",
            "accountHolder": "Max Mustermann",
            "signingDate": "2021-01-01",
            "type": "CORE",
            "sequence": "FRST"
        }
    }'
    ```

    For more details see: [Create payment method](/api-reference/paymentmethod/create-payment-method).
  </Tab>

  <Tab title="Bank transfer">
    <Check>
      Bank transfer is created by default when a customer is created.
    </Check>
  </Tab>
</Tabs>


# Collect Usage Data
Source: https://docs.fynn.eu/api-reference/guides/collect-usage-data

Send usage events to Fynn for usage-based billing.

Usage events are the foundation of usage-based billing. Send them from your application to track customer consumption.

## Quick Start

Send a usage event:

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "events": [{
      "transactionId": "req-abc-123",
      "eventName": "ai_request",
      "timestamp": "2026-01-15T14:30:00Z",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "properties": {
        "tokens_used": 350,
        "model": "gpt-4"
      }
    }]
  }'
```

***

## Event Structure

Each event requires these fields:

| Field           | Type     | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `transactionId` | string   | Unique ID for idempotency                                  |
| `eventName`     | string   | Matches your Nutzungsmetrik's event name                   |
| `timestamp`     | ISO 8601 | When the event occurred                                    |
| `customerId`    | string   | The customer's Fynn UUID **or** external ID (`externalId`) |
| `properties`    | object   | Event data (tokens, bytes, etc.)                           |

<Tip>
  The `customerId` field accepts both the Fynn UUID and the customer's `externalId`. Fynn automatically detects which format is being used.
</Tip>

### Example: AI Token Usage

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

### Example: API Call Tracking

```json theme={null}
{
  "transactionId": "call-xyz-456",
  "eventName": "api_call",
  "timestamp": "2026-01-15T14:31:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "properties": {
    "endpoint": "/api/users",
    "method": "GET",
    "response_time_ms": 145,
    "status_code": 200
  }
}
```

***

## Batch Import

Send up to 1000 events in one request:

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "events": [
      {
        "transactionId": "req-001",
        "eventName": "ai_request",
        "timestamp": "2026-01-15T10:00:00Z",
        "customerId": "cust-123",
        "properties": { "tokens_used": 150, "model": "gpt-4" }
      },
      {
        "transactionId": "req-002",
        "eventName": "ai_request",
        "timestamp": "2026-01-15T10:01:00Z",
        "customerId": "cust-123",
        "properties": { "tokens_used": 300, "model": "gpt-4-turbo" }
      }
    ]
  }'
```

***

## Response

**Success (202 Accepted):**

```json theme={null}
{
  "ingested": 2,
  "failed": 0,
  "errors": []
}
```

**Partial Success:**

```json theme={null}
{
  "ingested": 1,
  "failed": 1,
  "errors": [
    {
      "index": 1,
      "transactionId": "req-002",
      "error": "Invalid customer ID"
    }
  ]
}
```

***

## Idempotency

Events with the same `transactionId` are only processed once. If you send the same event twice, Fynn returns the existing event instead of creating a duplicate.

<Tip>
  Use deterministic transaction IDs, e.g.: `${customerId}-${timestamp}-${eventName}` or UUIDs.
</Tip>

***

## Properties for Nutzungsmetriks

The `properties` object should contain all fields your Nutzungsmetriks need:

| Nutzungsmetrik | Aggregation  | Required Property |
| -------------- | ------------ | ----------------- |
| Token Usage    | Sum          | `tokens_used`     |
| API Calls      | Count        | - (counts events) |
| Storage        | Latest       | `storage_gb`      |
| Active Users   | Unique Count | `user_id`         |

### Grouping Properties

If your Nutzungsmetrik uses `groupBy`, include those fields:

```json theme={null}
{
  "properties": {
    "tokens_used": 350,
    "model": "gpt-4",       // groupBy field
    "region": "eu-west-1"   // another groupBy field
  }
}
```

### Filter Properties

If your Nutzungsmetrik has filters, include the filtered fields:

```json theme={null}
{
  "properties": {
    "tokens_used": 350,
    "status_code": 200  // filter: status_code in [200, 201, 204]
  }
}
```

***

## Legacy: Subscription Measurements

For existing integrations using subscription-based measurements:

```bash theme={null}
curl -X POST https://coreapi.io/subscription-measurements/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "values": [
      {
        "subscription": "SUBSCRIPTION_ID",
        "subscriptionItem": "SUBSCRIPTION_ITEM_ID",
        "measurementCode": "used_traffic",
        "quantity": "1",
        "measuredAt": "2026-01-15T00:00:00Z"
      }
    ]
  }'
```

See: [API Reference](/api-reference/subscription-measurement/add-a-batch-of-subscription-measurement)

***

## Best Practices

### Timestamps

Always use UTC in ISO 8601 format:

```
✅ 2026-01-15T14:30:00Z
✅ 2026-01-15T14:30:00+00:00
❌ 2026-01-15 14:30:00
❌ 1705329000 (Unix timestamp)
```

### Batch Sizes

| Scenario           | Recommended Batch Size            |
| ------------------ | --------------------------------- |
| Real-time tracking | 10-100 events                     |
| Bulk import        | 500-1000 events                   |
| High volume        | Buffer and send every 1-5 seconds |

### Error Handling

```javascript theme={null}
async function sendEvents(events) {
  const response = await fetch('https://coreapi.io/api/usage-events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ events })
  });

  const result = await response.json();

  if (result.failed > 0) {
    // Retry failed events or log for manual review
    console.error('Failed events:', result.errors);
  }

  return result;
}
```

***

## Related Documentation

* [Nutzungsmetriken](/guide/catalogue/measurements/billable-metrics) - Konfiguriere was und wie gemessen wird
* [Nutzungsereignisse](/guide/catalogue/usage-events-import) - CSV Import und UI Optionen
* [Aggregationstypen](/guide/catalogue/measurements/aggregation-types/overview) - Summe, Anzahl, Maximum, etc.


# Enable manual invoice checks
Source: https://docs.fynn.eu/api-reference/guides/enable-manual-invoice-check

Learn how to enable manual invoice checks for all customers.

# Enable for all customers

Enable it for all existing customers and disable it for upcoming customers without changing settings.

<Tip>
  This is useful if you are migrating your subscriptions from another system and are not sure if those send invoices are correct.
</Tip>

## Set global tenant settings

To set global tenant settings, execute the following api request:

```bash theme={null}
curl --request PATCH \
    --url https://coreapi.io/settings \
    --header 'Authorization : Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/merge-patch+json' \
    --data '{
        "settings": [
            {
                "key": "requiresManualInvoiceApproval",
                "value": false
            }
        ]
    }'
```

## Enable for all existing customers

To enable manual invoice checks for all existing customers, execute the following api request:

1. Get all customers

```bash theme={null}
curl --request GET \
    --url https://coreapi.io/customers?limit=100 \
    --header 'Authorization : Bearer YOUR_API_KEY'
```

2. Update each customer

```bash theme={null}
curl --request PATCH \
    --url https://coreapi.io/customers/{customerId}/settings/billing \
    --header 'Authorization : Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/merge-patch+json' \
    --data '{
        "requiresManualInvoiceApproval": true
    }'
```

### Example script

A javascript example to enable manual invoice checks for all customers:

```js theme={null}
const apiKey = 'YOUR_API_KEY';

const getCustomers = async (page: number = 1) => {
    const customers = await fetch('https://coreapi.io/customers?limit=100&page=' + page, {
        headers: {
            Authorization: `Bearer ${apiKey}`
        }
    }).then(res => res.json());

    return customers;
};

const updateCustomer = async (customerId: string): void => {
    await fetch(`https://coreapi.io/customers/${customerId}/settings/billing`, {
        method: 'PATCH',
        headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/merge-patch+json'
        },
        body: JSON.stringify({
            requiresManualInvoiceApproval: true
        })
    });
};

const enableManualInvoiceChecks = async () => {
    let page = 1;
    let customers = await getCustomers(page);

    while (customers.length > 0) {
        for (const customer of customers) {
            await updateCustomer(customer.id);
        }

        page++;
        customers = await getCustomers(page);
    }
};

enableManualInvoiceChecks();
```


# Implement Self-Service Upgrades
Source: https://docs.fynn.eu/api-reference/guides/implement-upgrades

Integrate product group-based upgrades and downgrades into your application

This guide shows you how to implement self-service upgrades and downgrades using product groups in your application.

## Overview

The upgrade/downgrade flow consists of three main steps:

1. **Check eligibility** - Get available change options for a subscription item
2. **Display options** - Show the customer available upgrades/downgrades
3. **Apply change** - Execute the selected package change

***

## Prerequisites

Before implementing upgrades:

1. Create a **Product Group** with a tier for each package level
2. Assign the product group to the subscription item via `PUT /subscription-items/{id}/product-group`

***

## Step 1: Get Change Options

Fetch available upgrade/downgrade options for a subscription item:

```bash theme={null}
curl -X GET "https://coreapi.io/subscription-items/{itemId}/change-options" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "current": {
    "id": "tier-starter-uuid",
    "name": "Starter Plan",
    "pricePlan": {
      "id": "price-starter-uuid",
      "name": "Starter Monthly",
      "price": 2900,
      "billingInterval": "monthly"
    },
    "product": {
      "id": "product-starter-uuid",
      "name": "Starter"
    }
  },
  "options": [
    {
      "id": "tier-pro-uuid",
      "label": "Pro",
      "product": {
        "id": "product-pro-uuid",
        "name": "Pro Plan"
      },
      "pricePlans": [
        {
          "id": "price-pro-monthly-uuid",
          "name": "Pro Monthly",
          "price": 4900,
          "billingInterval": "monthly"
        }
      ],
      "changeTiming": "immediately",
      "creditType": "pro_rata",
      "isUpgrade": true,
      "isDowngrade": false,
      "quantitySetting": null
    }
  ],
  "hasPendingChange": false
}
```

### Response Fields

| Field                    | Description                             |
| ------------------------ | --------------------------------------- |
| `current`                | Currently active tier and price plan    |
| `options`                | Available upgrade/downgrade options     |
| `options[].isUpgrade`    | `true` if this is an upgrade            |
| `options[].isDowngrade`  | `true` if this is a downgrade           |
| `options[].changeTiming` | When the change takes effect            |
| `options[].creditType`   | How unused time is credited             |
| `hasPendingChange`       | `true` if a change is already scheduled |

<Warning>
  If `hasPendingChange` is `true`, no further changes can be made until the pending change is applied.
</Warning>

***

## Step 2: Display Options to Customer

Use the response to build a selection UI:

```javascript theme={null}
async function getUpgradeOptions(subscriptionItemId) {
  const response = await fetch(
    `/subscription-items/${subscriptionItemId}/change-options`,
    { headers: { Authorization: `Bearer ${token}` } }
  );

  const data = await response.json();

  // Check if changes are possible
  if (data.hasPendingChange) {
    return { error: 'A change is already pending' };
  }

  if (data.options.length === 0) {
    return { error: 'No upgrade options available' };
  }

  // Separate upgrades and downgrades
  const upgrades = data.options.filter(o => o.isUpgrade);
  const downgrades = data.options.filter(o => o.isDowngrade);

  return { current: data.current, upgrades, downgrades };
}
```

***

## Step 3: Apply the Change

When the customer selects an option, apply the change:

```bash theme={null}
curl -X POST "https://coreapi.io/product-group-memberships/{tierId}/apply" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subscriptionItem": "subscription-item-uuid",
    "quantity": 1
  }'
```

### Request Parameters

| Parameter           | Type    | Required | Description                                                                                                     |
| ------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `subscriptionItem`  | string  | Yes      | UUID of the subscription item to change                                                                         |
| `selectedPricePlan` | string  | No       | UUID of the price plan. Only required if the tier has multiple price plans. In most cases, this can be omitted. |
| `quantity`          | integer | No       | New quantity. Only applied if the tier allows quantity changes.                                                 |
| `sendInvoiceEmail`  | boolean | No       | Send credit note via email (default: `true`)                                                                    |

### Response

```json theme={null}
{
  "subscriptionItem": {
    "id": "item-uuid",
    "product": { "id": "...", "name": "Pro Plan" },
    "pricePlan": { "id": "...", "name": "Pro Monthly" },
    "status": "active"
  },
  "creditNote": {
    "id": "credit-note-uuid",
    "number": "CN-2026-0001",
    "amount": 1450
  }
}
```

***

## Change Timing Behavior

### Immediately

The change takes effect right away:

1. Current subscription item is ended
2. Credit note is created (based on `creditType`)
3. New subscription item is created and starts immediately
4. New invoice is generated

### End of Period

The change is scheduled for the next billing cycle:

1. Current subscription item continues until period end
2. At period end, item switches to new product/plan
3. No credit note is created
4. Next invoice uses new pricing

***

## Credit Types

When `changeTiming` is `immediately`, a credit is issued based on `creditType`:

| Type            | Formula                                   | Example                |
| --------------- | ----------------------------------------- | ---------------------- |
| `pro_rata`      | Price × (Days remaining / Days in period) | €29 × (15/30) = €14.50 |
| `full`          | Full period price                         | €29.00                 |
| `last_invoiced` | Amount from last invoice                  | Varies                 |
| `none`          | No credit                                 | €0.00                  |

***

## Complete Example

```javascript theme={null}
async function upgradeSubscription(subscriptionItemId, targetTierId) {
  // 1. Get current options to validate
  const options = await fetch(
    `/subscription-items/${subscriptionItemId}/change-options`,
    { headers: { Authorization: `Bearer ${token}` } }
  ).then(r => r.json());

  if (options.hasPendingChange) {
    throw new Error('Cannot change: pending change exists');
  }

  // 2. Find the selected option
  const selectedOption = options.options.find(o => o.id === targetTierId);
  if (!selectedOption) {
    throw new Error('Invalid tier selected');
  }

  // 3. Apply the change
  const result = await fetch(
    `/product-group-memberships/${targetTierId}/apply`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`
      },
      body: JSON.stringify({
        subscriptionItem: subscriptionItemId,
        quantity: 1
      })
    }
  ).then(r => r.json());

  return {
    newItem: result.subscriptionItem,
    creditNote: result.creditNote
  };
}
```

***

## Error Handling

| HTTP Status | Cause                       | Solution                            |
| ----------- | --------------------------- | ----------------------------------- |
| 400         | Invalid request             | Check required fields               |
| 404         | Subscription item not found | Verify item UUID                    |
| 422         | Pending change exists       | Wait for pending change to complete |
| 422         | Not eligible for change     | Check tier eligibility settings     |

***

## Webhooks

Listen for these events to track changes:

| Event                  | Description                           |
| ---------------------- | ------------------------------------- |
| `subscription.updated` | Subscription items changed            |
| `invoice.created`      | New invoice for upgraded subscription |
| `credit_note.created`  | Credit note for prorated amount       |

***

## Related Documentation

<CardGroup>
  <Card title="Product Groups" icon="layer-group" href="/guide/catalogue/product-groups">
    Set up product groups
  </Card>

  <Card title="Subscription Transitions" icon="arrow-right-arrow-left" href="/guide/subscriptions/transitions">
    Manual transitions
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guide/webhooks/introduction">
    Listen for events
  </Card>
</CardGroup>


# Wallet Payout
Source: https://docs.fynn.eu/api-reference/guides/wallet-payout

Pay out a customer wallet balance to their bank account via SEPA credit transfer over the API.

The Wallet Payout API pays out a customer's wallet balance to a bank account. Fynn debits the balance immediately and generates a SEPA credit transfer. How the transfer reaches your bank depends on the configured submission mode: in **manual mode** (default) you download the generated SEPA file and submit it to your bank yourself, then confirm the upload so the payout moves to `submitted`; in **automatic mode** Fynn submits it over EBICS. The payout is only finalized once the bank confirms the transfer via the account statement.

<Info>
  Bank payouts are subject to origin-based routing rules. A wallet balance can only be paid out to a bank account if it originated from a bank transfer or an in-house SEPA direct debit. Balance funded by card, PayPal, or GoCardless must be refunded through the original channel. See [Origin routing](#origin-routing) below.
</Info>

## Create a Payout

```bash theme={null}
curl -X POST https://coreapi.io/api/customers/CUSTOMER_ID/wallet/payouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "amount": 5000,
    "currencyCode": "EUR",
    "reference": "Wallet payout March 2026"
  }'
```

**Response (201 Created):**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "amount": 5000,
  "currencyCode": "EUR",
  "endingBalance": 0,
  "recipientIban": "DE89 **** **** **** **89",
  "endToEndId": "WP2026030812345678",
  "createdAt": "2026-03-08T10:00:00Z"
}
```

### Request Fields

| Field           | Type    | Required | Description                                                                      |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `amount`        | integer | Yes      | Payout amount in the smallest currency unit (cents). Must be greater than `0`    |
| `currencyCode`  | string  | Yes      | ISO 4217 currency code (e.g. `EUR`)                                              |
| `iban`          | string  | No       | Recipient IBAN. Defaults to the customer's stored bank connection (SEPA mandate) |
| `bic`           | string  | No       | Recipient BIC, when an explicit `iban` is provided                               |
| `accountHolder` | string  | No       | Recipient account holder name. Defaults to the customer's display name           |
| `reference`     | string  | No       | Remittance reference shown on the bank statement (max 140 characters)            |
| `description`   | string  | No       | Internal description of the payout (max 140 characters)                          |

<Note>
  Amounts are integers in cents, not decimals. `5000` means `50,00 EUR`.
</Note>

### Response Fields

| Field           | Type    | Description                                                        |
| --------------- | ------- | ------------------------------------------------------------------ |
| `id`            | string  | Payout UUID                                                        |
| `status`        | string  | Payout status (`created` on success)                               |
| `amount`        | integer | Payout amount in cents                                             |
| `currencyCode`  | string  | ISO 4217 currency code                                             |
| `endingBalance` | integer | Remaining wallet balance in cents after the payout was booked      |
| `recipientIban` | string  | Masked recipient IBAN                                              |
| `endToEndId`    | string  | Unique end-to-end reference used to match the bank statement entry |
| `createdAt`     | string  | ISO 8601 timestamp                                                 |

<Tip>
  Without an `iban`, the payout uses the customer's stored bank connection (the active SEPA mandate's bank account). Pass an explicit `iban` to pay out to a different account; it is recorded on the payout for audit.
</Tip>

## Payout Status

A payout moves through a fixed lifecycle:

| Status      | Description                                                                                                                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created`   | Payout booked, wallet balance debited. The credit transfer is waiting to be submitted: in manual mode until you download the SEPA file and confirm the upload, in automatic mode until Fynn submits it over EBICS |
| `submitted` | The credit transfer was submitted to the bank, either after you confirmed the upload (manual mode) or over EBICS (automatic mode)                                                                                 |
| `executed`  | The bank executed the transfer, confirmed via the account statement. Terminal state                                                                                                                               |
| `failed`    | Submission failed. The wallet booking was automatically reversed and the balance restored. Terminal state                                                                                                         |

<Warning>
  `created` does not mean the money has left the bank account yet. The payout is only complete once it reaches `executed`. Subscribe to the [webhooks](#webhooks) to react to the terminal states.
</Warning>

## Origin Routing

Fynn records the origin of every wallet inflow and enforces where the balance may flow back. A bank payout is only allowed when every funding portion of the payout comes from an allowed origin.

| Origin of the balance        | Bank payout | Correct alternative                  |
| ---------------------------- | ----------- | ------------------------------------ |
| Bank transfer                | Allowed     | Payout via SEPA credit transfer      |
| SEPA direct debit (in-house) | Allowed     | Payout via SEPA credit transfer      |
| Card (Stripe, Unzer)         | Blocked     | Refund via the original card         |
| PayPal                       | Blocked     | Refund via PayPal                    |
| GoCardless                   | Blocked     | Refund via GoCardless                |
| Missing / unknown origin     | Blocked     | Manual review, then original channel |

A blocked payout is **not** booked. The request returns `422` with an error code identifying the reason. Mixed funding follows an all-or-nothing rule: a single blocked portion blocks the entire payout.

## Error Handling

| Status Code | Error Code                               | Scenario                                                                                                                                                                              |
| ----------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `422`       | `CUSTOMER_BALANCE__NEGATIVE_NOT_ALLOWED` | Insufficient wallet balance for the requested amount                                                                                                                                  |
| `422`       | `WALLET_PAYOUT__ROUTE_NOT_ALLOWED`       | Balance origin does not permit a bank payout (e.g. card-funded)                                                                                                                       |
| `422`       | `WALLET_PAYOUT__ROUTE_UNKNOWN_ORIGIN`    | Origin of the balance is unknown and requires manual review                                                                                                                           |
| `422`       | `WALLET_PAYOUT__MISSING_BANK_DATA`       | No recipient bank connection available and no `iban` provided                                                                                                                         |
| `422`       | `WALLET_PAYOUT__NOT_CONFIGURED`          | Required configuration is missing. In manual mode this means the SEPA credit transfer settings (sender bank account); in automatic mode it additionally requires the EBICS connection |
| `404`       | (none)                                   | Unknown customer                                                                                                                                                                      |

<Note>
  When a payout is blocked or rejected, nothing is booked. The wallet balance stays exactly as it was before the request.
</Note>

## Webhooks

Subscribe to these events to react to the terminal states of a payout. Both carry the same payload shape.

| Event                    | When                                                                          |
| ------------------------ | ----------------------------------------------------------------------------- |
| `wallet.payout.executed` | The bank executed the transfer and it was confirmed via the account statement |
| `wallet.payout.failed`   | Submission failed; the wallet balance was automatically restored              |

**Payload:**

```json theme={null}
{
  "payoutId": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "amount": 5000,
  "currencyCode": "EUR",
  "status": "executed",
  "endToEndId": "WP2026030812345678",
  "reference": "Wallet payout March 2026",
  "failReason": null,
  "executedAt": "2026-03-10T08:15:00Z",
  "failedAt": null
}
```

| Field          | Type           | Description                                                 |
| -------------- | -------------- | ----------------------------------------------------------- |
| `payoutId`     | string         | Payout UUID                                                 |
| `customerId`   | string         | Customer UUID                                               |
| `amount`       | integer        | Payout amount in cents                                      |
| `currencyCode` | string         | ISO 4217 currency code                                      |
| `status`       | string         | `executed` or `failed`                                      |
| `endToEndId`   | string         | End-to-end reference matching the bank statement entry      |
| `reference`    | string         | Remittance reference of the payout                          |
| `failReason`   | string \| null | Reason for failure; `null` for executed payouts             |
| `executedAt`   | string \| null | ISO 8601 timestamp when executed; `null` for failed payouts |
| `failedAt`     | string \| null | ISO 8601 timestamp when failed; `null` for executed payouts |

See [Webhooks](/guide/webhooks/introduction) for signature verification and setup.

## Related Documentation

* [Guthaben auszahlen (Benutzerhandbuch)](/guide/invoices/wallet-payout) - Step-by-step guide and origin rules
* [Kundenguthaben](/guide/invoices/wallet-balance) - How the wallet balance works
* [Wallet Top-Up](/api-reference/guides/wallet-top-up) - Adding funds to a wallet balance


# Wallet Top-Up
Source: https://docs.fynn.eu/api-reference/guides/wallet-top-up

Initiate manual wallet top-ups and manage auto top-up rules via the API.

The Wallet Top-Up API lets you programmatically add funds to a customer's wallet balance by initiating payment collection, and configure automatic top-up rules that trigger when the balance drops below a threshold.

## Manual Top-Up

### Initiate a Top-Up

```bash theme={null}
curl -X POST https://coreapi.io/api/wallet/top-up \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100.00,
    "currencyCode": "EUR"
  }'
```

**Response (201 Created):**

```json theme={null}
{
  "id": "top_abc123",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "requestedAmount": { "amount": 10000, "currencyCode": "EUR" },
  "creditedAmount": null,
  "status": "pending",
  "paymentMethodId": null,
  "createdAt": "2026-03-08T10:00:00Z",
  "completedAt": null
}
```

| Field             | Type   | Required | Description                                                                 |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `customerId`      | string | Yes      | Customer UUID                                                               |
| `amount`          | number | Yes      | Top-up amount (e.g. `100.00`)                                               |
| `currencyCode`    | string | Yes      | ISO 4217 currency code (e.g. `EUR`)                                         |
| `paymentMethodId` | string | No       | Specific payment method UUID. Defaults to customer's default payment method |

<Tip>
  The top-up creates a PaymentIntent that collects the funds. Once the payment succeeds, the amount is credited to the customer's wallet.
</Tip>

### List Top-Ups

```bash theme={null}
curl https://coreapi.io/api/wallet/top-ups?customerId=CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response (200 OK):**

```json theme={null}
{
  "items": [
    {
      "id": "top_abc123",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "requestedAmount": { "amount": 10000, "currencyCode": "EUR" },
      "creditedAmount": { "amount": 10000, "currencyCode": "EUR" },
      "status": "completed",
      "paymentMethodId": null,
      "failureReason": null,
      "createdAt": "2026-03-08T10:00:00Z",
      "completedAt": "2026-03-08T10:01:00Z"
    }
  ],
  "count": 1
}
```

### Top-Up Status

| Status      | Description                            |
| ----------- | -------------------------------------- |
| `pending`   | Payment initiated, awaiting completion |
| `completed` | Payment succeeded, balance credited    |
| `failed`    | Payment failed, no balance change      |

### Get a Single Top-Up

```bash theme={null}
curl https://coreapi.io/api/wallet/top-ups/TOP_UP_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Auto Top-Up Rules

Auto top-up rules automatically initiate a top-up when a customer's wallet balance drops below a configured threshold.

### Create a Rule

```bash theme={null}
curl -X POST https://coreapi.io/api/wallet/auto-top-up \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "currencyCode": "EUR",
    "thresholdAmount": 10.00,
    "topUpAmount": 100.00
  }'
```

**Response (201 Created):**

```json theme={null}
{
  "id": "atr_xyz789",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "currencyCode": "EUR",
  "thresholdAmount": 10.00,
  "topUpAmount": 100.00,
  "paymentMethodId": null,
  "enabled": true,
  "consecutiveFailures": 0,
  "createdAt": "2026-03-08T10:00:00Z",
  "updatedAt": "2026-03-08T10:00:00Z"
}
```

| Field             | Type   | Required | Description                                               |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| `customerId`      | string | Yes      | Customer UUID                                             |
| `currencyCode`    | string | Yes      | ISO 4217 currency code                                    |
| `thresholdAmount` | number | Yes      | Balance threshold that triggers auto top-up (must be > 0) |
| `topUpAmount`     | number | Yes      | Amount to top up (must be > 0)                            |
| `paymentMethodId` | string | No       | Specific payment method. Defaults to customer's default   |

<Note>
  Only one rule per customer per currency is allowed. Attempting to create a duplicate returns `400 Bad Request`.
</Note>

### List Rules

```bash theme={null}
curl https://coreapi.io/api/wallet/auto-top-up?customerId=CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Update a Rule

```bash theme={null}
curl -X PUT https://coreapi.io/api/wallet/auto-top-up/RULE_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "thresholdAmount": 20.00,
    "topUpAmount": 200.00,
    "enabled": false
  }'
```

All fields are optional — only include the fields you want to change.

| Field             | Type    | Description                     |
| ----------------- | ------- | ------------------------------- |
| `thresholdAmount` | number  | New threshold (must be > 0)     |
| `topUpAmount`     | number  | New top-up amount (must be > 0) |
| `paymentMethodId` | string  | New payment method UUID         |
| `enabled`         | boolean | Enable or disable the rule      |

### Delete a Rule

```bash theme={null}
curl -X DELETE https://coreapi.io/api/wallet/auto-top-up/RULE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns `204 No Content` on success.

***

## How Auto Top-Up Works

1. A balance-reducing transaction occurs (e.g., wallet balance applied to an invoice)
2. Fynn checks if an enabled auto top-up rule exists for the customer and currency
3. If the ending balance is below the threshold, a top-up is initiated automatically
4. The top-up follows the same flow as a manual top-up (PaymentIntent → payment → credit)

**Safety mechanisms:**

* Top-up transactions themselves do **not** trigger auto top-up (prevents loops)
* The `consecutiveFailures` counter tracks sequential failures — monitor this to detect broken payment methods
* The feature must be enabled via the `WalletTopUp` feature flag

***

## Customer-Authenticated Requests

Customers authenticated via the customer portal can manage their own wallet:

* **Top-up**: `customerId` is inferred from the authenticated session (do not include it)
* **Auto top-up rules**: Customers can only view/manage their own rules
* Attempting to access another customer's data returns `403 Forbidden`

```bash theme={null}
# Customer-authenticated top-up (no customerId needed)
curl -X POST https://coreapi.io/api/wallet/top-up \
  -H "Authorization: Bearer CUSTOMER_TOKEN" \
  -d '{
    "amount": 50.00,
    "currencyCode": "EUR"
  }'
```

***

## Error Handling

| Status Code                | Scenario                                                           |
| -------------------------- | ------------------------------------------------------------------ |
| `400 Bad Request`          | Missing required field, duplicate rule for same currency           |
| `403 Forbidden`            | Feature not enabled, or customer accessing another customer's data |
| `404 Not Found`            | Rule or top-up not found                                           |
| `422 Unprocessable Entity` | Invalid amounts (zero, negative), invalid currency code            |

***

## Integration Example

```javascript theme={null}
const FYNN_API = 'https://coreapi.io';
const API_KEY = process.env.FYNN_API_KEY;

async function ensureWalletFunded(customerId, minBalance = 10, topUpAmount = 100) {
  // Check if auto top-up rule exists
  const rules = await fetch(
    `${FYNN_API}/api/wallet/auto-top-up?customerId=${customerId}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  ).then(r => r.json());

  if (rules.items.length === 0) {
    // Create auto top-up rule
    await fetch(`${FYNN_API}/api/wallet/auto-top-up`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`,
      },
      body: JSON.stringify({
        customerId,
        currencyCode: 'EUR',
        thresholdAmount: minBalance,
        topUpAmount: topUpAmount,
      }),
    });
  }
}
```

***

## Related Documentation

* [Kundenguthaben](/guide/invoices/wallet-balance) - Wie das Wallet-Guthaben funktioniert
* [Wallet aufladen (Benutzerhandbuch)](/guide/invoices/wallet-top-up) - Schritt-für-Schritt-Anleitung
* [Zahlungsmethoden hinzufügen](/api-reference/guides/add-payment-method) - Payment method setup


# Getting started
Source: https://docs.fynn.eu/api-reference/introduction

Welcome to the API reference documentation for the Fynn API.

Welcome to Fynn API documentation! This guide is designed to streamline the integration process
and provide you with all the necessary resources to seamlessly incorporate Fynn into your systems.
Whether you're managing subscriptions for a SaaS platform, digital content, or any other recurring billing needs,
our API aims to simplify complex billing operations, empowering you to focus on your core business.

<Tip>
  <b>Sandbox environment</b>

  <br />

  Before you start integrating with the Fynn API, you can test your application in a sandbox environment,
  where you can create and manage subscriptions without any financial implications.

  Contact our support team to get access to the sandbox environment.
</Tip>

The Fynn API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

## Endpoints

We provide the following endpoints:

* **Production**:
  * API: `https://coreapi.io`
  * Frontend: `https://app.fynn.eu`
  * Customerfront: `https://customerfront.app`
* **Playground**:
  * API: `https://preview.coreapi.io`
  * Frontend: `https://preview.fynn.eu`
  * Customerfront: `https://preview.customerfront.app`

<Note>
  <b>Customerfront</b>

  <br />

  The customerfront.app serves any customer-facing pages, such as the customer portal, checkout, and offer pages.
</Note>


# Migration: Measurements → Nutzungsmetriken
Source: https://docs.fynn.eu/api-reference/migrations/measurements-deprecation

Deprecation der Measurement-Endpunkte und Properties zugunsten der neuen Nutzungsmetriken

<Note>
  **Geplante Änderung** - Die Measurement-API und das `measurement` Property werden schrittweise durch das neue Nutzungsmetriken-System ersetzt.
</Note>

## Übersicht

Mit der Einführung der neuen **Nutzungsmetriken** wird das bisherige Measurement-System schrittweise abgelöst. Diese Seite beschreibt die Änderungen und wie du deine Integration anpassen kannst.

### Migrationspfad

| Phase       | Zeitraum | Änderung                                                                    |
| ----------- | -------- | --------------------------------------------------------------------------- |
| **Phase 1** | Aktuell  | Neues Nutzungsmetriken-System verfügbar, Measurements weiterhin unterstützt |
| **Phase 2** | Q1 2026  | `unit` Property wird neben `measurement` hinzugefügt                        |
| **Phase 3** | Q2 2026  | `measurement` Property wird deprecated (Warnung in Response)                |
| **Phase 4** | Q3 2026  | `measurement` Property wird entfernt, nur noch `unit`                       |

***

## Betroffene API Responses

Das `measurement` Property wird aktuell in folgenden API Responses zurückgegeben:

### Product Responses

**Endpunkte:**

* `GET /catalogue/products`
* `GET /catalogue/products/{id}`
* `POST /catalogue/products`
* `PUT /catalogue/products/{id}`

**Aktuelle Struktur:**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "measurement": {
    "id": "meas_xyz789",
    "code": "api_calls",
    "description": "Anzahl der API-Aufrufe",
    "aggregationType": "count",
    "type": "metered",
    "fairBilling": true,
    "unit": {
      "id": "unit_123",
      "name": "Stück"
    }
  }
}
```

**Zukünftige Struktur (Phase 2):**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "measurement": { ... },  // Bleibt zunächst erhalten
  "unit": {                // NEU: Zusätzlich auf Top-Level
    "id": "unit_123",
    "name": "Stück"
  }
}
```

**Finale Struktur (Phase 4):**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "unit": {
    "id": "unit_123",
    "name": "Stück"
  }
}
```

### Plan Responses (PlanResource)

**Endpunkte:**

* `GET /catalogue/plans`
* `GET /catalogue/plans/{id}`
* `POST /catalogue/plans`
* `PUT /catalogue/plans/{id}`

**Betroffen:** `measurement` Property im Plan-Objekt

### SubscriptionItem Responses

**Endpunkte:**

* `GET /subscription-items/{id}`
* `PATCH /subscription-items/{id}`

**Betroffen:** Nested `measurement` in Detail-Responses

### MeasurementValue Responses (Subscription Measurements)

**Endpunkte:**

* `GET /subscription-measurements/{id}`
* `POST /subscription-measurements`
* `POST /subscription-measurements/batch`

**Aktuelle Struktur:**

```json theme={null}
{
  "id": "mv_abc123",
  "measurement": {
    "id": "meas_xyz789",
    "code": "api_calls",
    "unit": {
      "id": "unit_123",
      "name": "Stück"
    }
  },
  "quantity": "150",
  "measuredAt": "2026-01-15T10:00:00Z"
}
```

***

## Deprecated Endpoints

<Warning>
  Die folgenden Endpunkte werden **Q3 2026** entfernt.
</Warning>

### Measurement CRUD Endpoints

| Endpoint                       | Method | Status         |
| ------------------------------ | ------ | -------------- |
| `/catalogue/measurements`      | GET    | **Deprecated** |
| `/catalogue/measurements`      | POST   | **Deprecated** |
| `/catalogue/measurements/{id}` | GET    | **Deprecated** |
| `/catalogue/measurements/{id}` | PUT    | **Deprecated** |
| `/catalogue/measurements/{id}` | DELETE | **Deprecated** |

**Ersatz:** Nutzungsmetrik direkt am Produkt konfigurieren.

### Subscription Measurement Endpoints

| Endpoint                           | Method | Status         | Ersatz                          |
| ---------------------------------- | ------ | -------------- | ------------------------------- |
| `/subscription-measurements`       | POST   | **Deprecated** | `POST /api/usage-events`        |
| `/subscription-measurements/batch` | POST   | **Deprecated** | `POST /api/usage-events`        |
| `/subscription-measurements/{id}`  | GET    | **Deprecated** | Usage über Subscription abrufen |

***

## SubscriptionItem Response Änderungen

### `currentMeasurementValue` wird ersetzt

<Warning>
  Das Property `currentMeasurementValue` wird deprecated und **Q3 2026** durch neue Properties ersetzt.
</Warning>

**Aktuelle Response:**

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "currentMeasurementValue": {
    "id": "mv_xyz",
    "quantity": "150",
    "measuredAt": "2026-01-15T10:00:00Z"
  }
}
```

**Zukünftige Response:**

Für **Produkte mit fester Menge** (nicht nutzungsbasiert):

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "quantity": "5",
  "unit": {
    "id": "unit_123",
    "name": "Benutzer"
  }
}
```

Für **nutzungsbasierte Produkte**:

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "quantity": null,
  "unit": {
    "id": "unit_123",
    "name": "API Calls"
  },
  "currentUsage": {
    "aggregatedValue": "1.523",
    "eventsCount": 47,
    "periodStart": "2026-01-01T00:00:00Z",
    "periodEnd": "2026-02-01T00:00:00Z"
  }
}
```

### Neue Properties

| Property       | Typ            | Beschreibung                                       |
| -------------- | -------------- | -------------------------------------------------- |
| `quantity`     | string \| null | Feste Menge (null für usage-based Produkte)        |
| `unit`         | object         | Einheit mit `id` und `name`                        |
| `currentUsage` | object \| null | Aggregierte Nutzung (nur für usage-based Produkte) |

### `currentUsage` Struktur

| Property          | Typ      | Beschreibung                                       |
| ----------------- | -------- | -------------------------------------------------- |
| `aggregatedValue` | string   | Der aggregierte Wert (z.B. Summe, Anzahl, Maximum) |
| `eventsCount`     | integer  | Anzahl der Ereignisse im Zeitraum                  |
| `periodStart`     | datetime | Beginn des aktuellen Abrechnungszeitraums          |
| `periodEnd`       | datetime | Ende des aktuellen Abrechnungszeitraums            |

<Tip>
  Für detaillierte Nutzungsdaten mit einzelnen Events verwende `GET /subscriptions/{id}/usage`.
</Tip>

### Manuelle Mengenänderungen werden ignoriert

<Warning>
  **Wichtig für Entwickler:** Produkte mit konfigurierter Nutzungsmetrik ignorieren manuelle Mengenänderungen.
</Warning>

### Aktuelles Verhalten

Bei Produkten mit Nutzungsmetrik wird die manuelle Mengenänderung am Subscription Item **ignoriert** (Legacy-Kompatibilität):

```bash theme={null}
# Wird für usage-based Produkte ignoriert
PATCH /subscription-items/{id}
{
  "quantity": 100
}
```

### Zukünftiges Verhalten (ab Q3 2026)

Ab Q3 2026 wird ein Fehler zurückgegeben:

```json theme={null}
{
  "error": {
    "code": "PRODUCT__QUANTITY_CHANGE_NOT_AVAILABLE_FOR_USAGE_BASED_PRODUCTS",
    "message": "Quantity changes are not available for usage-based products. Use usage events instead."
  }
}
```

### Korrekte Vorgehensweise

Für nutzungsbasierte Produkte muss die Menge über **Nutzungsereignisse** gesteuert werden:

```bash theme={null}
POST /api/usage-events
{
  "events": [{
    "transactionId": "unique-id",
    "eventName": "api_call",
    "timestamp": "2026-02-01T10:00:00Z",
    "customerId": "cust_123",
    "properties": {
      "endpoint": "/api/users"
    }
  }]
}
```

***

## Empfohlene Migration

<Note>
  Aktuell haben **alle Produkte** ein `measurement` (Pflichtfeld). Mit dem neuen System wird `measurement` komplett entfernt und durch `unit` ersetzt. Die Konfiguration der Nutzungsmetrik (Event-Name, Aggregation, Filter) erfolgt dann direkt am Produkt über "Nutzungsbasierte Abrechnung aktivieren".
</Note>

### Für API-Konsumenten

**Schritt 1:** Bereite deinen Code vor, das `unit` Property zu verwenden

```javascript theme={null}
// ❌ Bisher
const unitName = product.measurement?.unit?.name;

// ✅ Zukünftig (abwärtskompatibel)
const unitName = product.unit?.name ?? product.measurement?.unit?.name;
```

**Schritt 2:** Stelle Event-Ingestion um

```javascript theme={null}
// ❌ Bisher (deprecated)
await api.post('/subscription-measurements/batch', {
  values: [{
    subscription: 'sub_123',
    subscriptionItem: 'item_456',
    measurementCode: 'api_calls',
    quantity: '1',
    measuredAt: '2026-02-01T10:00:00Z'
  }]
});

// ✅ Neu
await api.post('/api/usage-events', {
  events: [{
    transactionId: 'tx_unique_123',
    eventName: 'api_call',
    timestamp: '2026-02-01T10:00:00Z',
    customerId: 'cust_789',
    properties: {
      endpoint: '/api/users',
      status_code: 200
    }
  }]
});
```

**Schritt 3:** Entferne Quantity-Updates für usage-based Produkte

```javascript theme={null}
// ❌ Nicht mehr verwenden
await api.patch(`/subscription-items/${itemId}`, { quantity: 100 });

// ✅ Mengen werden automatisch aus Events berechnet
```

***

## Zusammenfassung der Änderungen

| Bereich              | Aktuell                         | Zukünftig                |
| -------------------- | ------------------------------- | ------------------------ |
| **Product Response** | `measurement` mit nested `unit` | Nur `unit` (id, name)    |
| **Plan Response**    | `measurement` Property          | `unit` Property          |
| **SubscriptionItem** | `measurement` in Details        | `unit` Property          |
| **Verbrauchsdaten**  | `/subscription-measurements`    | `/api/usage-events`      |
| **Quantity Updates** | Ignoriert (Legacy)              | Fehler für usage-based   |
| **Measurement CRUD** | Eigene Endpoints                | Konfiguration am Produkt |

***

## Fragen?

Bei Fragen zur Migration kontaktiere uns:

* **E-Mail:** [developer@fynn.eu](mailto:developer@fynn.eu)
* **Support:** [support@fynn.eu](mailto:support@fynn.eu)

Oder buche einen [Termin mit unserem Team](https://cal.com/team/fynn/fynn-documentation).


# Usage Events API
Source: https://docs.fynn.eu/api-reference/usage-events/overview

API endpoints for usage-based billing event ingestion and retrieval.

Die Usage Events API ermöglicht das Senden und Abrufen von Nutzungsereignissen für nutzungsbasierte Abrechnung.

## Base URL

```
https://coreapi.io
```

## Authentifizierung

Alle Endpoints erfordern einen API-Token im Header:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Endpoints

| Method | Endpoint                     | Beschreibung                         |
| ------ | ---------------------------- | ------------------------------------ |
| POST   | `/api/usage-events`          | Nutzungsereignisse senden (Batch)    |
| GET    | `/api/usage-events`          | Nutzungsereignisse abrufen           |
| GET    | `/api/usage-events/[id]`     | Einzelnes Ereignis abrufen           |
| GET    | `/api/usage-events/discover` | Event-Namen und Properties entdecken |

***

## POST /api/usage-events

Sende bis zu 1000 Nutzungsereignisse in einem Request.

### Request

```bash theme={null}
curl -X POST https://coreapi.io/api/usage-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "events": [
      {
        "transactionId": "tx-001",
        "eventName": "ai_request",
        "timestamp": "2026-02-01T10:00:00Z",
        "customerId": "550e8400-e29b-41d4-a716-446655440000",
        "properties": {
          "tokens_used": 350,
          "model": "gpt-4"
        }
      }
    ]
  }'
```

### Request Body

<ParamField type="array">
  Array von Nutzungsereignissen (1-1000 Events)

  <Expandable title="Event-Objekt">
    <ParamField type="string">
      Eindeutige ID für Idempotenz. Doppelte transactionIds werden ignoriert.
    </ParamField>

    <ParamField type="string">
      Name des Events. Muss mit dem konfigurierten Event-Namen der Nutzungsmetrik übereinstimmen.
    </ParamField>

    <ParamField type="string">
      Zeitstempel im ISO 8601 Format (z.B. `2026-02-01T10:00:00Z`)
    </ParamField>

    <ParamField type="string">
      Kunden-Identifier. Akzeptiert die Fynn-UUID **oder** die externe Kundennummer (`externalId`). Fynn erkennt automatisch, welches Format übergeben wird.
    </ParamField>

    <ParamField type="object">
      Beliebige Event-Eigenschaften für Aggregation, Filter und Gruppierung
    </ParamField>
  </Expandable>
</ParamField>

<Tip>
  Du kannst im Feld `customerId` auch die externe Kundennummer (`externalId`) übergeben. Fynn erkennt automatisch, ob es sich um eine UUID oder eine externe ID handelt. Die `externalId` wird am Kunden unter [Kundeneinstellungen](/guide/customers/settings) hinterlegt.
</Tip>

### Response (202 Accepted)

```json theme={null}
{
  "ingested": 1,
  "failed": 0,
  "errors": []
}
```

<ResponseField name="ingested" type="integer">
  Anzahl erfolgreich verarbeiteter Events
</ResponseField>

<ResponseField name="failed" type="integer">
  Anzahl fehlgeschlagener Events
</ResponseField>

<ResponseField name="errors" type="array">
  Details zu fehlgeschlagenen Events

  <Expandable title="Error-Objekt">
    <ResponseField name="index" type="integer">
      Index des fehlgeschlagenen Events im Request-Array
    </ResponseField>

    <ResponseField name="transactionId" type="string">
      TransactionId des fehlgeschlagenen Events
    </ResponseField>

    <ResponseField name="error" type="string">
      Fehlermeldung
    </ResponseField>
  </Expandable>
</ResponseField>

***

## GET /api/usage-events

Rufe Nutzungsereignisse mit Paginierung und Filtern ab.

### Request

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events?customerId=550e8400-e29b-41d4-a716-446655440000&eventName=ai_request&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Query Parameter

<ParamField type="string">
  Filtere nach Kunden-UUID
</ParamField>

<ParamField type="string">
  Filtere nach Event-Name
</ParamField>

<ParamField type="string">
  Filtere nach Zeitraum (ISO 8601)
</ParamField>

<ParamField type="string">
  Sortierfeld: `timestamp` oder `createdAt`
</ParamField>

<ParamField type="string">
  Sortierreihenfolge: `ASC` oder `DESC`
</ParamField>

<ParamField type="string">
  Paginierungs-Cursor für nächste Seite
</ParamField>

<ParamField type="integer">
  Anzahl Ergebnisse pro Seite (max. 100)
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "data": [
    {
      "id": "01HQXYZ123456789ABCDEFGH",
      "transactionId": "tx-001",
      "eventName": "ai_request",
      "timestamp": "2026-02-01T10:00:00Z",
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "properties": {
        "tokens_used": 350,
        "model": "gpt-4"
      },
      "createdAt": "2026-02-01T10:00:05Z"
    }
  ],
  "meta": {},
  "pagination": {
    "cursor": "eyJpZCI6IjAxSFFYWVoxMjM0NTY3ODlBQkNERUZHSCJ9"
  }
}
```

***

## GET /api/usage-events/\[id]

Rufe ein einzelnes Nutzungsereignis ab.

### Request

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events/01HQXYZ123456789ABCDEFGH" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameter

<ParamField type="string">
  UUID oder ULID des Nutzungsereignisses
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "id": "01HQXYZ123456789ABCDEFGH",
  "transactionId": "tx-001",
  "eventName": "ai_request",
  "timestamp": "2026-02-01T10:00:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "properties": {
    "tokens_used": 350,
    "model": "gpt-4"
  },
  "createdAt": "2026-02-01T10:00:05Z"
}
```

***

## GET /api/usage-events/discover

Entdecke automatisch Event-Namen und Properties aus bereits gesendeten Events. Nützlich für die Konfiguration von Nutzungsmetriken.

### Request

```bash theme={null}
curl -X GET "https://coreapi.io/api/usage-events/discover?limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Query Parameter

<ParamField type="string">
  Filtere nach spezifischem Event-Namen
</ParamField>

<ParamField type="integer">
  Anzahl Events zur Analyse (max. 10000)
</ParamField>

### Response (200 OK)

```json theme={null}
{
  "eventNames": [
    {
      "name": "ai_request",
      "sampleProperties": {
        "tokens_used": 350,
        "model": "gpt-4"
      }
    },
    {
      "name": "api_call",
      "sampleProperties": {
        "endpoint": "/api/users",
        "status_code": 200
      }
    }
  ],
  "allProperties": [
    {
      "path": "tokens_used",
      "type": "number",
      "eventName": "ai_request",
      "sampleValues": [150, 350, 500]
    },
    {
      "path": "model",
      "type": "string",
      "eventName": "ai_request",
      "sampleValues": ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"]
    }
  ],
  "exampleEvents": [
    {
      "eventName": "ai_request",
      "properties": {
        "tokens_used": 350,
        "model": "gpt-4"
      },
      "timestamp": "2026-02-01T10:00:00Z"
    }
  ]
}
```

<ResponseField name="eventNames" type="array">
  Liste aller gefundenen Event-Namen mit Beispiel-Properties
</ResponseField>

<ResponseField name="allProperties" type="array">
  Liste aller gefundenen Property-Pfade mit Typ-Information
</ResponseField>

<ResponseField name="exampleEvents" type="array">
  Beispiel-Events für jeden Event-Namen
</ResponseField>

***

## Fehler-Codes

| HTTP Status | Beschreibung                                        |
| ----------- | --------------------------------------------------- |
| 202         | Events akzeptiert (kann teilweise Fehler enthalten) |
| 400         | Ungültige Anfrage - Validierungsfehler              |
| 401         | Nicht autorisiert - Ungültiger API-Token            |
| 404         | Event nicht gefunden                                |
| 429         | Rate Limit überschritten                            |

***

## Verwandte Dokumentation

* [Nutzungsmetriken konfigurieren](/guide/catalogue/measurements/billable-metrics)
* [Nutzungsereignisse senden (Guide)](/guide/catalogue/usage-events-import)
* [Collect Usage Data](/api-reference/guides/collect-usage-data)


# Kundeneinstellungen
Source: https://docs.fynn.eu/guide/ai-assistant/customer-settings

Kundeneinstellungen per KI-Assistent abfragen und ändern – Mahnwesen, Abrechnung, Rechnungsfreigabe und Zahlungsziel.

Der KI-Assistent kann **Kundeneinstellungen anzeigen** und **per Bulk-Aktion ändern** – direkt im Chat, ohne die Einstellungsseite jedes Kunden einzeln aufrufen zu müssen. Unterstützt werden:

* **Mahnwesen** (Dunning) – deaktivieren / aktivieren
* **Abrechnung** (Billing) – deaktivieren / aktivieren
* **Manuelle Rechnungsfreigabe** – aktivieren / deaktivieren
* **Zahlungsziel** – auf einen neuen Wert setzen

***

## Einstellungen abfragen

Frage den Assistenten nach dem aktuellen Status der Kundeneinstellungen. Er ruft die Daten automatisch ab und fasst sie zusammen.

### Beispiel-Anfragen

| Anfrage                                                    | Was passiert                                                                                             |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| "Ist das Mahnwesen für Kunde Müller aktiv?"                | Ruft die Einstellungen von Kunde Müller ab und zeigt den Dunning-Status                                  |
| "Welche Einstellungen hat Kunde D26-00100043?"             | Zeigt alle Einstellungen des Kunden (Mahnwesen, Abrechnung, Rechnungsfreigabe, Zahlungsziel, E-Rechnung) |
| "Ist die Abrechnung für diesen Kunden aktiv?"              | Auf der Kundendetailseite – nutzt den Seitenkontext                                                      |
| "Hat Kunde ACME die manuelle Rechnungsfreigabe aktiviert?" | Prüft den Status der manuellen Freigabe                                                                  |

### Ablauf

<Steps>
  <Step title="Kunde ermitteln">
    Der Assistent sucht den Kunden per Name, Kundennummer oder nutzt den Seitenkontext. Bei mehreren Treffern wird eine **Auswahlkarte** angezeigt.
  </Step>

  <Step title="Einstellungen abrufen">
    Alle Kundeneinstellungen werden auf einen Blick abgerufen: Mahnwesen, Abrechnung, Rechnungsfreigabe, Zahlungsziel und E-Rechnungsformat.
  </Step>

  <Step title="Ergebnis und Vorschlag">
    Der Assistent beantwortet deine Frage und bietet proaktiv an, die Einstellung zu ändern – z.B. *"Das Mahnwesen ist aktiv. Soll ich es deaktivieren?"*
  </Step>
</Steps>

<Info>
  Die Einstellungsabfrage funktioniert auch im Seitenkontext. Auf einer **Kundendetailseite** reicht "Welche Einstellungen hat dieser Kunde?" – der Assistent weiß, welcher Kunde gemeint ist.
</Info>

***

## Einstellungen ändern

Alle Änderungen an Kundeneinstellungen folgen dem gleichen **Bestätigungs-Workflow**: Der Assistent zeigt eine Bestätigungskarte an, und du bestätigst oder brichst ab. Bei mehreren Kunden wird die Änderung **sequenziell** für jeden Kunden einzeln durchgeführt.

<Warning>
  Einstellungsänderungen werden **nur nach expliziter Bestätigung** über den Button ausgeführt. Ein einfaches "Ja" im Chat reicht nicht aus.
</Warning>

***

### Mahnwesen deaktivieren / aktivieren

Deaktiviere oder aktiviere das Mahnwesen (Dunning) für einen oder mehrere Kunden gleichzeitig. Wenn das Mahnwesen deaktiviert ist, werden keine automatischen Mahnungen mehr für den Kunden erstellt.

#### Beispiel-Anfragen

| Anfrage                                           | Was passiert                                              |
| ------------------------------------------------- | --------------------------------------------------------- |
| "Deaktiviere das Mahnwesen für Kunde Müller"      | Deaktiviert das Mahnwesen für einen Kunden                |
| "Pausiere die Mahnung für Kunden A und B"         | Deaktiviert das Mahnwesen für mehrere Kunden gleichzeitig |
| "Aktiviere das Mahnwesen für Kunde Müller wieder" | Reaktiviert das Mahnwesen                                 |

#### Ablauf

<Steps>
  <Step title="Kunden ermitteln">
    Der Assistent sucht die genannten Kunden. Bei mehreren Treffern pro Name wird eine Auswahlkarte angezeigt.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und die geplante Aktion (z.B. "Mahnwesen für 2 Kunden deaktivieren"). Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird die Einstellung für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

***

### Abrechnung deaktivieren / aktivieren

Deaktiviere oder aktiviere die automatische Abrechnung (Billing) für einen oder mehrere Kunden. Wenn die Abrechnung deaktiviert ist, werden keine neuen Rechnungen für den Kunden generiert.

#### Beispiel-Anfragen

| Anfrage                                             | Was passiert                                  |
| --------------------------------------------------- | --------------------------------------------- |
| "Deaktiviere die Abrechnung für Kunde ACME GmbH"    | Deaktiviert die Abrechnung für einen Kunden   |
| "Stoppe die Rechnungserstellung für Kunden A und B" | Deaktiviert die Abrechnung für mehrere Kunden |
| "Aktiviere die Abrechnung für Kunde ACME wieder"    | Reaktiviert die Abrechnung                    |

#### Ablauf

<Steps>
  <Step title="Kunden ermitteln">
    Der Assistent sucht die genannten Kunden. Bei mehreren Treffern pro Name wird eine Auswahlkarte angezeigt.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und die geplante Aktion (z.B. "Abrechnung für 1 Kunden deaktivieren"). Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird die Einstellung für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

***

### Manuelle Rechnungsfreigabe aktivieren / deaktivieren

Aktiviere oder deaktiviere die manuelle Rechnungsfreigabe für einen oder mehrere Kunden. Wenn die manuelle Freigabe aktiviert ist, müssen Rechnungen für diesen Kunden vor dem Versand manuell geprüft und freigegeben werden.

#### Beispiel-Anfragen

| Anfrage                                                     | Was passiert                              |
| ----------------------------------------------------------- | ----------------------------------------- |
| "Aktiviere die manuelle Rechnungsfreigabe für Kunde Müller" | Schaltet die manuelle Freigabe ein        |
| "Schalte die manuelle Freigabe für Kunden A und B ein"      | Aktiviert die Freigabe für mehrere Kunden |
| "Deaktiviere die Rechnungsfreigabe für Kunde Müller"        | Schaltet zurück auf automatische Freigabe |

#### Ablauf

<Steps>
  <Step title="Kunden ermitteln">
    Der Assistent sucht die genannten Kunden. Bei mehreren Treffern pro Name wird eine Auswahlkarte angezeigt.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und die geplante Aktion (z.B. "Manuelle Rechnungsfreigabe für 2 Kunden aktivieren"). Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird die Einstellung für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

***

### Zahlungsziel ändern

Ändere das Zahlungsziel (payableInDays) für einen oder mehrere Kunden gleichzeitig. Der Wert bestimmt, wie viele Tage nach Rechnungsstellung die Zahlung fällig ist.

#### Beispiel-Anfragen

| Anfrage                                                    | Was passiert                                            |
| ---------------------------------------------------------- | ------------------------------------------------------- |
| "Setze das Zahlungsziel für Kunde Müller auf 30 Tage"      | Ändert das Zahlungsziel auf 30 Tage                     |
| "Passe das Zahlungsziel von Kunden A und B auf 14 Tage an" | Ändert das Zahlungsziel für mehrere Kunden gleichzeitig |
| "Zahlungsfrist für alle Kunden auf 60 Tage"                | Der Assistent sucht die Kunden und ändert die Frist     |

#### Ablauf

<Steps>
  <Step title="Kunden und Wert ermitteln">
    Der Assistent sucht die genannten Kunden und ermittelt die gewünschte Zahlungsfrist. Falls der Wert nicht angegeben wurde, fragt er gezielt nach.
  </Step>

  <Step title="Bestätigung">
    Eine **Bestätigungskarte** zeigt die betroffenen Kunden und das neue Zahlungsziel. Du bestätigst oder brichst ab.
  </Step>

  <Step title="Ausführung">
    Nach der Bestätigung wird das Zahlungsziel für jeden Kunden einzeln aktualisiert. Der Assistent zeigt eine Zusammenfassung mit Erfolgs- oder Fehlerstatus pro Kunde.
  </Step>
</Steps>

<Tip>
  Gültiger Bereich für das Zahlungsziel: **1 bis 365 Tage**.
</Tip>

***

## Bestätigungskarte

Alle Einstellungsänderungen zeigen eine Bestätigungskarte im Chat an:

<AccordionGroup>
  <Accordion title="Bestätigen" icon="circle-check">
    Klicke auf **Bestätigen**, um die Änderung auszuführen. Die Buttons werden nach dem Klick deaktiviert. Bei mehreren Kunden siehst du einen Fortschritt, bis alle Änderungen abgeschlossen sind.
  </Accordion>

  <Accordion title="Abbrechen" icon="circle-xmark">
    Klicke auf **Abbrechen**, um den Vorgang abzubrechen. Der Assistent bestätigt die Stornierung und du kannst eine neue Anfrage stellen.
  </Accordion>

  <Accordion title="Zeitlimit" icon="clock">
    Die Bestätigung hat ein Zeitfenster von **5 Minuten**. Danach wird sie ungültig und der Assistent bittet dich, den Vorgang erneut zu starten.
  </Accordion>
</AccordionGroup>

<Info>
  Während die Bestätigungskarte angezeigt wird, ist das Chat-Eingabefeld deaktiviert. Du musst zuerst bestätigen oder abbrechen, bevor du eine neue Nachricht senden kannst.
</Info>

***

## Beispiel-Szenarien

### Einstellung abfragen und ändern

> **Du:** Ist das Mahnwesen für Kunde Müller aktiv?
>
> **Assistent:** Das Mahnwesen für Müller GmbH ist aktuell **aktiv**. Die Mahngebühren sind ebenfalls aktiviert und das Zahlungsziel beträgt 14 Tage. Soll ich das Mahnwesen deaktivieren?
>
> **Du:** Ja, deaktiviere es
>
> *(Bestätigungskarte: "Mahnwesen für 1 Kunden deaktivieren" – Müller GmbH)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Das Mahnwesen für Müller GmbH wurde deaktiviert.

### Bulk-Änderung für mehrere Kunden

> **Du:** Deaktiviere die Abrechnung für Kunden Müller und Schmidt
>
> **Assistent:** *(sucht Kunden, findet eindeutige Treffer)*
>
> *(Bestätigungskarte: "Abrechnung für 2 Kunden deaktivieren" – Müller GmbH, Schmidt AG)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** ✓ Abrechnung für Müller GmbH deaktiviert.
> ✓ Abrechnung für Schmidt AG deaktiviert.
> Beide Einstellungen wurden erfolgreich aktualisiert.

### Abbruch einer Änderung

> **Du:** Aktiviere die manuelle Rechnungsfreigabe für Kunde ACME
>
> *(Bestätigungskarte: "Manuelle Rechnungsfreigabe für 1 Kunden aktivieren" – ACME GmbH)*
>
> **Du:** *(klickt "Abbrechen")*
>
> **Assistent:** Der Vorgang wurde abgebrochen. Die Einstellungen wurden nicht geändert.

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Welche Einstellungen kann ich per Assistent ändern?">
    Aktuell: Mahnwesen (aktivieren/deaktivieren), Abrechnung (aktivieren/deaktivieren), manuelle Rechnungsfreigabe (aktivieren/deaktivieren) und Zahlungsziel (Anzahl Tage). Weitere Einstellungen werden nach und nach ergänzt.
  </Accordion>

  <Accordion title="Kann ich Einstellungen für viele Kunden gleichzeitig ändern?">
    Ja – nenne einfach mehrere Kundennamen oder -nummern in deiner Anfrage. Der Assistent verarbeitet sie sequenziell und zeigt eine Zusammenfassung.
  </Accordion>

  <Accordion title="Was passiert bei einem Fehler während der Bulk-Änderung?">
    Der Assistent verarbeitet jeden Kunden einzeln. Wenn bei einem Kunden ein Fehler auftritt, werden die anderen trotzdem aktualisiert. Am Ende siehst du eine Zusammenfassung mit Erfolgs- und Fehlerstatus pro Kunde.
  </Accordion>

  <Accordion title="Kann ich sehen, was die aktuelle Einstellung ist, bevor ich sie ändere?">
    Ja – frage einfach "Welche Einstellungen hat Kunde X?" oder "Ist das Mahnwesen für Kunde X aktiv?". Der Assistent zeigt dir den aktuellen Status an und bietet an, ihn zu ändern.
  </Accordion>
</AccordionGroup>


# Berichterstellung
Source: https://docs.fynn.eu/guide/ai-assistant/reports

So generierst du mit dem KI-Assistenten Berichte – inklusive automatischer Parametererfassung und Bestätigung.

Der KI-Assistent kann Berichte generieren und dir per E-Mail zusenden. Der gesamte Ablauf – vom Vorschlag über die Parametererfassung bis zur Bestätigung – läuft direkt im Chat ab.

***

## Verfügbare Berichte

| Bericht                              | Beschreibung                                                | Parameter                                        |
| ------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------ |
| **Umsatz-Bericht**                   | Monatliche Umsatzentwicklung nach Kunden                    | Jahr (z.B. 2025)                                 |
| **Umsatz-Bericht (periodengerecht)** | Umsätze nach Leistungszeitraum, Beleg und kundenbasiert     | Jahr (z.B. 2025)                                 |
| **Zahlungsbericht**                  | Übersicht aller Zahlungen inkl. Kunden und Belege           | Startdatum, Enddatum, Zahlungsstatus             |
| **Debitoren-Saldenliste**            | Aktuelles Saldo des Debitoren-Kontos                        | Keine                                            |
| **Offene Posten (OPOS)**             | Alle unbezahlten Rechnungen inkl. Fälligkeit und Mahnstatus | Keine                                            |
| **Belegbericht**                     | Übersicht aller Belege (filterbar nach Typ)                 | Belegart (optional), Nur finalisierte (optional) |
| **Accounted-MRR-Bericht**            | Entwicklung des monatlich wiederkehrenden Umsatzes          | Stichtag (optional)                              |
| **Rechnungsprognose**                | Zukünftige Rechnungen basierend auf bestehenden Abos        | Prognosejahr                                     |
| **PRAP-Bericht**                     | Periodengerechte Abgrenzung aller Umsätze auf Monatsbasis   | Stichtag (ISO-Datum)                             |
| **re:cap-Berichte**                  | Verträge und Rechnungen als CSV-Export für re:cap           | Keine                                            |

***

## Ablauf

Der Assistent führt dich in mehreren Schritten durch die Berichterstellung:

<Steps>
  <Step title="Bericht vorschlagen">
    Du stellst eine Frage oder bittest um einen Bericht. Der Assistent erkennt, welcher Bericht zu deiner Anfrage passt, und erklärt dir, was der Bericht enthält.

    **Beispiele:**

    * "Erstelle einen Umsatz-Bericht"
    * "Ich brauche eine Offene-Posten-Liste"
    * "Wie ist die Umsatzentwicklung unserer besten Kunden?"
  </Step>

  <Step title="Parameter erfassen">
    Wenn der Bericht Parameter benötigt (z.B. ein Jahr oder ein Datumsbereich), erfragt der Assistent diese gezielt. Die Parameter werden **automatisch aus deinen Antworten extrahiert** und **serverseitig validiert** – du musst kein bestimmtes Format einhalten.

    **Beispiel-Dialog:**

    > **Du:** Erstelle einen Umsatz-Bericht
    >
    > **Assistent:** Für welches Jahr soll der Umsatz-Bericht erstellt werden?
    >
    > **Du:** 2025
    >
    > **Assistent:** *(Parameter erkannt und validiert – weiter zur Bestätigung)*

    <Info>
      Berichte ohne Parameter (z.B. Debitoren-Saldenliste, OPOS) überspringen diesen Schritt und gehen direkt zur Bestätigung.
    </Info>
  </Step>

  <Step title="Bestätigung">
    Sobald alle Parameter vorliegen, zeigt der Assistent eine **Bestätigungskarte** im Chat an. Diese enthält:

    * Den Berichtsnamen
    * Die erfassten Parameter als Übersicht
    * Zwei Buttons: **Bestätigen** und **Abbrechen**

    Du kannst die Parameter prüfen, bevor du den Bericht tatsächlich auslöst.

    <Warning>
      Berichte werden **nur nach expliziter Bestätigung** über den Button generiert. Ein einfaches "Ja" im Chat löst keine Generierung aus.
    </Warning>
  </Step>

  <Step title="Bericht generieren">
    Nach dem Klick auf **Bestätigen** wird der Bericht im Hintergrund erstellt und dir per E-Mail zugestellt. Der Assistent bestätigt dies im Chat.
  </Step>
</Steps>

***

## Parametervalidierung

Die Parameter werden **automatisch** vom System geprüft – nicht vom KI-Modell. Das stellt sicher, dass:

* Alle Pflichtparameter vorhanden sind, bevor ein Bericht generiert wird
* Werte im richtigen Format vorliegen (z.B. 4-stelliges Jahr, gültiges ISO-Datum)
* Bei fehlenden oder ungültigen Parametern eine **gezielte Rückfrage** gestellt wird

| Parameter           | Validierung                                                 |
| ------------------- | ----------------------------------------------------------- |
| **Jahr**            | Muss 4-stellige Zahl sein (z.B. 2025), nicht in der Zukunft |
| **Datum**           | Muss gültiges ISO-8601-Format sein (YYYY-MM-DD)             |
| **Zahlungsstatus**  | Muss `paid`, `pending`, `failed` oder `all` sein            |
| **Prognosejahr**    | Muss 4-stellige Zahl sein, mindestens aktuelles Jahr        |
| **Stichtag (PRAP)** | Muss gültiges ISO-8601-Format sein (YYYY-MM-DD)             |

<Tip>
  Du kannst Parameter in natürlicher Sprache angeben. Sag einfach "letztes Jahr" oder "Januar 2026" – der Assistent rechnet das automatisch um.
</Tip>

***

## Bestätigungskarte

Die Bestätigungskarte erscheint direkt im Chat und verhindert versehentliche Berichterstellung:

<AccordionGroup>
  <Accordion title="Bestätigen" icon="circle-check">
    Klicke auf **Bestätigen**, um den Bericht zu generieren. Die Buttons werden nach dem Klick deaktiviert – ein doppeltes Absenden ist nicht möglich.

    Nach der Bestätigung zeigt der Assistent eine Ladeansicht mit dem Berichtsnamen. Der Bericht wird per E-Mail zugestellt.
  </Accordion>

  <Accordion title="Abbrechen" icon="circle-xmark">
    Klicke auf **Abbrechen**, um den Vorgang abzubrechen. Der Assistent bestätigt die Stornierung und du kannst eine neue Anfrage stellen oder Parameter ändern.
  </Accordion>

  <Accordion title="Zeitlimit" icon="clock">
    Die Bestätigung hat ein Zeitfenster von **5 Minuten**. Wenn du nicht innerhalb dieser Zeit reagierst, wird die Bestätigung ungültig und der Assistent bittet dich, den Vorgang erneut zu starten.
  </Accordion>
</AccordionGroup>

<Info>
  Während die Bestätigungskarte angezeigt wird, ist das Chat-Eingabefeld deaktiviert. Du musst zuerst bestätigen oder abbrechen, bevor du eine neue Nachricht senden kannst.
</Info>

***

## Beispiel-Szenarien

### Bericht ohne Parameter (OPOS)

> **Du:** Erstelle mir einen OPOS-Bericht
>
> **Assistent:** Ich kann dir einen OPOS-Bericht (Offene Posten) erstellen. Dieser enthält alle unbezahlten Rechnungen mit Fälligkeitsdaten und Mahnstatus.
>
> *(Bestätigungskarte mit "OPOS-Bericht (Offene Posten)" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der OPOS-Bericht wird erstellt und dir per E-Mail zugesendet.

### Bericht mit Parametern (Umsatz)

> **Du:** Wie ist die Umsatzentwicklung unserer besten Kunden?
>
> **Assistent:** Für eine detaillierte Auswertung kann ich dir einen Umsatz-Bericht generieren. Dieser zeigt die monatliche Umsatzentwicklung nach Kunden. Für welches Jahr soll der Bericht erstellt werden?
>
> **Du:** 2025
>
> *(Bestätigungskarte mit "Umsatz-Bericht", Parameter "Jahr: 2025" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der Umsatz-Bericht für 2025 wird erstellt und dir per E-Mail zugesendet.

### Bericht mit mehreren Parametern (Zahlungen)

> **Du:** Ich brauche einen Zahlungsbericht für Q1 2026
>
> **Assistent:** Für den Zahlungsbericht brauche ich noch den Zahlungsstatus. Soll der Bericht alle Zahlungen (paid, pending, failed) enthalten, oder nur einen bestimmten Status?
>
> **Du:** Alle
>
> *(Bestätigungskarte mit "Zahlungsbericht", Parameter "01.01.2026 – 31.03.2026, Status: all" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der Zahlungsbericht wird erstellt und dir per E-Mail zugesendet.

### PRAP-Bericht mit Stichtag

> **Du:** Erstelle einen PRAP-Bericht
>
> **Assistent:** Ich kann dir einen PRAP-Bericht erstellen. Dieser zeigt die periodengerechte Abgrenzung aller Umsätze auf Monatsbasis. Bis zu welchem Stichtag sollen die Belege berücksichtigt werden?
>
> **Du:** Bis Ende 2025
>
> *(Bestätigungskarte mit "PRAP-Bericht", Parameter "Stichtag: 2025-12-31" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Der PRAP-Bericht wird erstellt und dir per E-Mail zugesendet.

### re:cap-Berichte (ohne Parameter)

> **Du:** Exportiere die re:cap-Berichte
>
> **Assistent:** Ich erstelle dir die re:cap-Berichte. Diese enthalten Verträge und Rechnungen als CSV-Export.
>
> *(Bestätigungskarte mit "re:cap-Berichte" wird angezeigt)*
>
> **Du:** *(klickt "Bestätigen")*
>
> **Assistent:** Die re:cap-Berichte werden erstellt und dir per E-Mail zugesendet.

### Ungültige Parameter

> **Du:** Erstelle einen Umsatz-Bericht für 999
>
> **Assistent:** Das Jahr muss eine 4-stellige Zahl sein (z.B. 2025) und darf nicht in der Zukunft liegen. Für welches Jahr soll der Bericht erstellt werden?
>
> **Du:** 2025
>
> *(Bestätigungskarte wird angezeigt)*

***

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Wo finde ich den generierten Bericht?">
    Berichte werden per E-Mail an deine hinterlegte Adresse gesendet. Zusätzlich findest du sie unter **Reportings → Generierte Berichte** in der App.
  </Accordion>

  <Accordion title="Kann ich einen laufenden Bericht abbrechen?">
    Nein – sobald du bestätigt hast, wird der Bericht im Hintergrund erstellt. Du kannst aber jederzeit einen neuen Bericht mit anderen Parametern anfordern.
  </Accordion>

  <Accordion title="Warum fragt der Assistent nach Parametern, obwohl ich sie schon genannt habe?">
    Der Assistent extrahiert Parameter automatisch aus dem gesamten Gesprächsverlauf. Wenn ein Parameter nicht erkannt wurde, war er möglicherweise mehrdeutig. Formuliere ihn etwas spezifischer (z.B. "Jahr 2025" statt nur "letztes Jahr").
  </Accordion>

  <Accordion title="Warum kann ich nicht einfach 'Ja' schreiben, um zu bestätigen?">
    Berichte erfordern eine explizite Bestätigung über den **Bestätigen-Button** in der Karte. Das verhindert Missverständnisse und versehentliche Berichtserstellung. Ein einfaches "Ja" im Chat wird als neue Nachricht interpretiert.
  </Accordion>
</AccordionGroup>


# Workflows
Source: https://docs.fynn.eu/guide/ai-assistant/workflows

So verarbeitet der KI-Assistent komplexe Anfragen Schritt für Schritt – am Beispiel von Zahlungen, Transaktionen und Belegen.

Der KI-Assistent nutzt für bestimmte Fragestellungen fest definierte **Workflows** – mehrstufige Abläufe, die im Code verankert sind und automatisch die richtigen Daten in der richtigen Reihenfolge abrufen. Du stellst eine Frage, und der Assistent liefert ein vollständiges Ergebnis.

***

## Letzte Zahlung eines Kunden

Wenn du fragst, wann ein Kunde zuletzt bezahlt hat, nutzt der Assistent den **Letzte-Zahlung-Workflow**. Dieser sucht direkt nach der letzten Zahlungstransaktion – nicht nach Belegen.

<Info>
  Der Workflow sucht immer zuerst die **Transaktion** (die tatsächliche Zahlung), nicht den Beleg. Die Beleginformationen werden automatisch aus der Transaktion abgeleitet.
</Info>

### Beispiel-Anfragen

| Anfrage                                        | Kontext                                                |
| ---------------------------------------------- | ------------------------------------------------------ |
| "Was ist die letzte Zahlung von D26-00100030?" | Von jeder Seite aus                                    |
| "Wann hat der Kunde zuletzt bezahlt?"          | Auf der Kundendetailseite                              |
| "Letzte Zahlung?"                              | Auf der Kundendetailseite (Seitenkontext wird genutzt) |
| "Wann hat Kunde Müller zuletzt bezahlt?"       | Von jeder Seite aus (Kunde wird per Name gesucht)      |

### Ablauf

<Steps>
  <Step title="Kunde ermitteln">
    Der Assistent ermittelt den Kunden. Auf einer **Kundendetailseite** wird der Seitenkontext verwendet – keine zusätzliche Suche nötig. Von anderen Seiten aus sucht er per Kundennummer oder Name. Bei mehreren Treffern zeigt er eine **Auswahlkarte** an.
  </Step>

  <Step title="Letzte Transaktion abrufen">
    Der Assistent ruft die **letzte Zahlungstransaktion** des Kunden ab. Das Ergebnis enthält: Status, Zahlungsmethode, Gateway (z.B. Stripe, SEPA), Betrag, Datum und den verknüpften Beleg.
  </Step>

  <Step title="Ergebnis anzeigen">
    Das Ergebnis wird als Transaktionskarte angezeigt – mit direkten Links zum Beleg und zur Transaktionsübersicht.
  </Step>
</Steps>

### Szenarien

<AccordionGroup>
  <Accordion title="Erfolgreiche Zahlung" icon="circle-check">
    Die letzte Transaktion hat den Status **Erfasst** (captured) oder **Gebucht** (booked).

    Der Assistent zeigt:

    * Zahlungsdatum und Betrag
    * Zahlungsmethode und Gateway (z.B. "SEPA-Lastschrift via GoCardless")
    * Verknüpfter Beleg (z.B. "RE-2025-0042")

    **Beispiel-Antwort:**

    > "Die letzte Zahlung von Kevin Szymura war am 03.02.2026 über 149,90 € per SEPA-Lastschrift (GoCardless). Der verknüpfte Beleg ist RE-2026-0015."
  </Accordion>

  <Accordion title="Fehlgeschlagene oder ausstehende Zahlung" icon="triangle-exclamation">
    Die letzte Transaktion hat einen **nicht-erfolgreichen Status** (z.B. `failed`, `pending`, `cancelled`).

    Der Assistent zeigt dann **zwei Informationen**:

    1. **Die letzte Transaktion** mit ihrem Status (z.B. "Fehlgeschlagen"), Datum, Betrag und verknüpftem Beleg
    2. **Die letzte erfolgreiche Zahlung** als Zusatzinfo – damit du weißt, wann die letzte *tatsächliche* Zahlung stattfand

    **Beispiel-Antwort:**

    > "Der letzte Zahlungsversuch von Kevin Szymura am 10.02.2026 über 149,90 € ist fehlgeschlagen (Beleg RE-2026-0018). Die letzte erfolgreiche Zahlung war am 03.01.2026 über 149,90 € per SEPA-Lastschrift."

    <Warning>
      Wenn es **keine einzige erfolgreiche Zahlung** gibt, meldet der Assistent das ebenfalls – z.B. "Es gibt keine erfolgreichen Zahlungen für diesen Kunden."
    </Warning>
  </Accordion>

  <Accordion title="Keine Transaktionen vorhanden" icon="circle-xmark">
    Der Kunde hat **keine Zahlungstransaktionen** (z.B. ein neuer Kunde ohne Belege).

    **Beispiel-Antwort:**

    > "Für Kevin Szymura wurden keine Zahlungstransaktionen gefunden."
  </Accordion>
</AccordionGroup>

***

## Belegzahlungen

Wenn du wissen möchtest, wie ein bestimmter Beleg bezahlt wurde, nutzt der Assistent den **Belegzahlungen-Workflow**.

### Beispiel-Anfragen

| Anfrage                                     | Kontext                  |
| ------------------------------------------- | ------------------------ |
| "Wie wurde dieser Beleg bezahlt?"           | Auf der Belegdetailseite |
| "Welche Zahlungen gibt es zu diesem Beleg?" | Auf der Belegdetailseite |
| "Wie wurde Beleg RE-2025-0042 bezahlt?"     | Von jeder Seite aus      |

### Ablauf

<Steps>
  <Step title="Beleg ermitteln">
    Auf einer **Belegdetailseite** wird der Seitenkontext verwendet. Von anderen Seiten aus sucht der Assistent den Beleg per Nummer. Bei mehreren Treffern zeigt er eine **Auswahlkarte** an.
  </Step>

  <Step title="Transaktionen abrufen">
    Der Assistent sucht alle Zahlungstransaktionen, die mit diesem Beleg verknüpft sind.
  </Step>

  <Step title="Ergebnis anzeigen">
    Alle Transaktionen werden als Liste angezeigt – jeweils mit Zahlungsmethode, Gateway, Datum, Betrag und Status.
  </Step>
</Steps>

### Szenarien

<AccordionGroup>
  <Accordion title="Beleg mit Zahlungen" icon="circle-check">
    **Beispiel-Antwort:**

    > "Beleg RE-2025-0042 wurde am 15.01.2025 über 299,00 € per Kreditkarte (Stripe) bezahlt."

    Bei mehreren Teilzahlungen werden alle aufgelistet.
  </Accordion>

  <Accordion title="Beleg ohne Transaktionen" icon="circle-xmark">
    Der Beleg hat keine verknüpften Zahlungstransaktionen (z.B. ein noch unbezahlter Beleg).

    **Beispiel-Antwort:**

    > "Zu Beleg RE-2025-0042 wurden keine Zahlungstransaktionen gefunden."
  </Accordion>
</AccordionGroup>

***

## Unterschied: Letzte Zahlung vs. Zahlungen eines Belegs

|                               | Letzte Zahlung                                               | Belegzahlungen                                              |
| ----------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| **Frage**                     | "Wann hat der Kunde zuletzt bezahlt?"                        | "Wie wurde dieser Beleg bezahlt?"                           |
| **Ausgangspunkt**             | Kunde                                                        | Beleg                                                       |
| **Sucht nach**                | Letzter Transaktion des Kunden                               | Allen Transaktionen eines Belegs                            |
| **Fehlgeschlagene Zahlungen** | Werden mit Hinweis auf letzte erfolgreiche Zahlung angezeigt | Alle Transaktionen werden angezeigt (inkl. fehlgeschlagene) |


# Passkeys
Source: https://docs.fynn.eu/guide/tenant/passkeys

Melde dich mit Face ID, Touch ID oder einem Hardware-Sicherheitsschlüssel an — sicher und ohne Passwort.

## Übersicht

Passkeys sind eine sichere und bequeme Alternative zum klassischen Passwort-Login. Sie nutzen die biometrische Authentifizierung deines Geräts (Face ID, Touch ID, Windows Hello) oder einen Hardware-Sicherheitsschlüssel (z. B. YubiKey), um dich bei Fynn anzumelden.

**Vorteile von Passkeys:**

* **Sicherer als Passwörter** — Passkeys basieren auf Public-Key-Kryptografie und können nicht erraten oder gestohlen werden
* **Phishing-resistent** — Passkeys sind an die Domain gebunden und funktionieren nicht auf gefälschten Websites
* **Kein Passwort nötig** — Login mit einem Fingertipp oder Blick

<Info>
  Passkeys ergänzen den bestehenden Passwort-Login. Du kannst dich weiterhin mit deinem Passwort anmelden, auch wenn ein Passkey eingerichtet ist.
</Info>

## Passkey einrichten

<Steps>
  <Step title="Kontoeinstellungen öffnen">
    Klicke auf deinen Avatar oder Namen in der oberen Navigation und wähle **Mein Profil**. Navigiere dann zum Tab **Sicherheit**.
  </Step>

  <Step title="Passkey hinzufügen">
    Klicke im Bereich **Passkeys** auf **Passkey hinzufügen**. Dein Browser fordert dich auf, einen Passkey zu erstellen.
  </Step>

  <Step title="Authentifizierung bestätigen">
    Bestätige die Erstellung mit deinem Gerät:

    * **Mac**: Touch ID oder Systempasswort
    * **iPhone/iPad**: Face ID oder Touch ID
    * **Windows**: Windows Hello (Fingerabdruck, Gesichtserkennung oder PIN)
    * **Hardware-Schlüssel**: Berühre den Sicherheitsschlüssel
  </Step>

  <Step title="Passkey benennen">
    Vergib einen aussagekräftigen Namen für den Passkey (z. B. „MacBook Pro Büro" oder „YubiKey"). So erkennst du später, welches Gerät oder welcher Schlüssel hinterlegt ist.
  </Step>
</Steps>

<Tip>
  Du kannst mehrere Passkeys für verschiedene Geräte einrichten. So kannst du dich sowohl am Laptop als auch am Smartphone mit einem Passkey anmelden.
</Tip>

## Mit Passkey anmelden

<Steps>
  <Step title="Login-Seite öffnen">
    Öffne die Fynn Login-Seite unter [app.fynn.eu](https://app.fynn.eu).
  </Step>

  <Step title="Passkey-Login wählen">
    Klicke auf **Mit Passkey anmelden**. Dein Browser erkennt automatisch, welche Passkeys für diese Seite verfügbar sind.
  </Step>

  <Step title="Authentifizieren">
    Bestätige den Login mit deinem Gerät (Face ID, Touch ID, Sicherheitsschlüssel). Du wirst sofort angemeldet — ohne E-Mail oder Passwort.
  </Step>
</Steps>

## Passkeys verwalten

Im Bereich **Mein Profil > Sicherheit** siehst du alle eingerichteten Passkeys mit folgenden Informationen:

| Feld                  | Beschreibung                                   |
| --------------------- | ---------------------------------------------- |
| **Name**              | Der von dir vergebene Name des Passkeys        |
| **Erstellt am**       | Datum der Einrichtung                          |
| **Zuletzt verwendet** | Datum der letzten Anmeldung mit diesem Passkey |

### Passkey entfernen

Klicke neben dem Passkey auf das Löschen-Symbol, um ihn zu entfernen. Nach dem Entfernen kann dieser Passkey nicht mehr für die Anmeldung verwendet werden.

<Warning>
  Wenn du deinen letzten Passkey entfernst, stelle sicher, dass du dich noch mit deinem Passwort anmelden kannst.
</Warning>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Welche Geräte und Browser unterstützen Passkeys?">
    Passkeys werden von allen modernen Browsern und Betriebssystemen unterstützt:

    * **macOS / iOS**: Safari, Chrome, Firefox (ab macOS 13 / iOS 16)
    * **Windows**: Chrome, Edge, Firefox (ab Windows 10)
    * **Android**: Chrome (ab Android 9)

    Hardware-Sicherheitsschlüssel (FIDO2/WebAuthn) werden ebenfalls unterstützt.
  </Accordion>

  <Accordion title="Funktionieren Passkeys geräteübergreifend?">
    Das hängt von deinem Ökosystem ab. Apple synchronisiert Passkeys über iCloud Keychain auf alle Apple-Geräte. Google synchronisiert über den Google Password Manager. Für geräteübergreifende Nutzung (z. B. Mac und Windows) empfehlen wir, auf jedem Gerät einen eigenen Passkey einzurichten oder einen Hardware-Sicherheitsschlüssel zu verwenden.
  </Accordion>

  <Accordion title="Was passiert, wenn ich mein Gerät verliere?">
    Wenn du dein Gerät verlierst, kannst du dich weiterhin mit deinem Passwort anmelden. Entferne den Passkey des verlorenen Geräts anschließend in den Kontoeinstellungen.
  </Accordion>

  <Accordion title="Kann ich Passkey und Passwort gleichzeitig nutzen?">
    Ja. Passkeys ergänzen den Passwort-Login. Beide Methoden funktionieren parallel. Auf der Login-Seite kannst du wählen, ob du dich mit Passkey oder Passwort anmelden möchtest.
  </Accordion>

  <Accordion title="Sind Passkeys sicherer als Passwörter?">
    Ja. Passkeys basieren auf asymmetrischer Kryptografie (WebAuthn-Standard). Der private Schlüssel verlässt dein Gerät nie. Es gibt kein gemeinsames Geheimnis, das abgefangen werden kann — Phishing, Credential Stuffing und Brute-Force-Angriffe sind damit ausgeschlossen.
  </Accordion>
</AccordionGroup>


# Authentifizierung
Source: https://docs.fynn.eu/v2-plans-api/authentication

API-Token für die Einrichtung und Kunden-Token für den Tarifwechsel im Kundenbereich.

Die Plan-API kennt zwei Kontexte. Die Einrichtung (Pläne anlegen, Checkout-Links erstellen) läuft serverseitig mit einem API-Token deiner Organisation. Der Tarifwechsel im Kundenbereich läuft im Namen eines Kunden mit einem Kunden-Token.

## Basis-URLs

| Umgebung   | Basis-URL                    |
| ---------- | ---------------------------- |
| Produktion | `https://coreapi.io`         |
| Sandbox    | `https://preview.coreapi.io` |

Alle Pfade in dieser Dokumentation beginnen mit `/api`, zum Beispiel `https://coreapi.io/api/plans`.

## Einrichtung: API-Token

Setup-Endpunkte (alles unter `/api/plans`) authentifizierst du mit einem API-Token deiner Organisation. Das Token ist fest an genau eine Organisation gebunden, du brauchst also keinen zusätzlichen Organisations-Header.

<Steps>
  <Step title="Token erstellen">
    Lege ein API-Token in den Entwickler-Einstellungen an. Eine ausführliche Anleitung findest du unter [Authentication](/api-reference/authentication).
  </Step>

  <Step title="Token senden">
    Schicke das Token bei jeder Anfrage im Authorization-Header mit.
  </Step>
</Steps>

```bash theme={null}
curl https://coreapi.io/api/plans \
  -H "Authorization: Bearer api_DEIN_TOKEN"
```

Referenz: [Plans listen](/v2-plans-api/plans/list-plans).

<Warning>
  Behandle API-Token wie ein Passwort. Sie haben vollen Zugriff im Rahmen ihrer Berechtigungen. Gib sie niemals im Browser oder in einer mobilen App preis.
</Warning>

## Kundenbereich: Kunden-Token

Die drei Wechsel-Endpunkte unter `/api/customer/...` laufen im Kontext eines angemeldeten Kunden. Sie erwarten ein Kunden-Token (Bearer) mit der Berechtigung `customer:plan:switch`.

Serverseitig erzeugst du ein solches Token mit deinem API-Token (Berechtigung `customer:authenticate`):

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://coreapi.io/customers/CUSTOMER_ID/authenticate \
    -H "Authorization: Bearer api_DEIN_TOKEN"
  ```

  ```json Response theme={null}
  {
    "data": {
      "accessToken": "...",
      "refreshToken": "...",
      "customerAreaLink": "https://..."
    }
  }
  ```
</CodeGroup>

Den `accessToken` schickst du dann als Bearer-Token an die Kundenbereich-Endpunkte:

```bash theme={null}
curl https://coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
  -H "Authorization: Bearer CUSTOMER_TOKEN"
```

Referenz: [Tarifoptionen abrufen](/v2-plans-api/customer/plan-options).

Alternativ stammt das Token aus einer Kundenbereich-Sitzung (Portal). Wie du Kunden anmeldest und welche Flows es gibt, beschreiben der [OAuth2-Flow](/guide/oauth2/introduction) und der Abschnitt zur Kunden-Authentifizierung unter [Authentication](/api-reference/authentication).

### Im Namen eines Kunden handeln (X-On-Behalf-Of)

Für Server-zu-Server-Integrationen musst du nicht für jeden Kunden ein eigenes Token erzeugen. Du verwendest deinen API-Token und legst über den Header `X-On-Behalf-Of` fest, in wessen Namen die Anfrage läuft:

```bash theme={null}
curl https://coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
  -H "Authorization: Bearer api_DEIN_TOKEN" \
  -H "X-On-Behalf-Of: customer:CUSTOMER_ID"
```

Die Anfrage läuft dann vollständig als dieser Kunde, mit dessen Berechtigungen wie `customer:plan:switch`. Voraussetzungen:

* Dein API-Token braucht die Berechtigung `customer:authenticate`.
* Der Kunde muss zu deiner Organisation gehören, sonst antwortet die API mit `404`.
* Während der Impersonation gelten ausschließlich die Kunden-Berechtigungen, nicht die Admin-Rechte deines Tokens. Reine Admin-Endpunkte sind in einer solchen Anfrage also nicht erreichbar.

So sparst du dir den separaten Token-Abruf und nutzt einen einzigen API-Token für alle Kundenbereich-Aktionen.

<Note>
  Ein Tarifwechsel ist bewusst nur im Kundenbereich möglich, nicht in der Wallet. So entscheidet immer der Kunde selbst über seinen Auf- oder Abstieg.
</Note>

## Berechtigungen

| Berechtigung            | Wofür                                                                   |
| ----------------------- | ----------------------------------------------------------------------- |
| `plan:read`             | Pläne und Checkout-Links lesen                                          |
| `plan:write`            | Pläne anlegen, ändern, aktivieren, löschen und Checkout-Links erstellen |
| `customer:plan:switch`  | Tarifoptionen abrufen, Wechsel-Vorschau und Wechsel (mit Kunden-Token)  |
| `customer:authenticate` | Kunden-Token erzeugen über `POST /customers/{id}/authenticate` (Admin)  |

Fehlt die nötige Berechtigung, antwortet die API mit `401` (nicht authentifiziert) oder `403` (authentifiziert, aber nicht berechtigt).


# Asynchrone Abrechnung
Source: https://docs.fynn.eu/v2-plans-api/billing

Wann abgerechnet wird, wie Änderungen in die nächste Rechnung einfließen und Rechnungen asynchron entstehen.

Die V2-Abrechnung folgt einem einheitlichen Muster: Änderungen werden gesammelt, und Rechnungen entstehen asynchron. Das gilt plattformweit und ist hier am Beispiel der Pläne erklärt. Für die Integration sind vor allem zwei Dinge wichtig: wann eine Rechnung entsteht und wie sich eine Änderung wie ein Tarifwechsel auf die Abrechnung auswirkt.

## Wann abgerechnet wird

* **Erstrechnung:** Beim Checkout entsteht das Abonnement und die erste Abrechnung für die gewählte Tarifstufe.
* **Wiederkehrend:** Danach wird das Abonnement regelmäßig im Intervall des Preisplans abgerechnet.
* **Bei Änderungen:** Ein Tarifwechsel erzeugt keine eigene, sofortige Rechnung. Die anteilige Gutschrift oder Berechnung wird gesammelt und fließt in die nächste reguläre Rechnung ein.

## Sammeln bis zur nächsten Rechnung

Solange für die laufende Periode noch keine Rechnung erstellt wurde, werden Positionen gesammelt. Rechnungen werden anschließend asynchron erzeugt, also nicht im selben Moment wie der API-Aufruf.

Für dich als Entwickler heißt das:

<Steps>
  <Step title="Die Wechsel-Antwort enthält keine fertige Rechnung">
    `switch-plan-tier` bestätigt den Wechsel, liefert aber keine Rechnung. Die Rechnung folgt kurze Zeit später.
  </Step>

  <Step title="Mehrere Änderungen werden gebündelt">
    Führst du mehrere Änderungen kurz nacheinander aus, landen sie gemeinsam auf einer Rechnung, statt einzeln abgerechnet zu werden.
  </Step>

  <Step title="Den Effekt vorab zeigen">
    Wenn du dem Kunden die Kosten sofort zeigen möchtest, nutze die [Vorschau](/v2-plans-api/upgrades-downgrades#anteilige-berechnung). Sie liefert die erwartete Gutschrift und Berechnung, ohne etwas zu verändern.
  </Step>
</Steps>

<Note>
  Plane in deiner Oberfläche damit, dass eine Rechnung nach einem Wechsel mit kurzer Verzögerung erscheint. Verlasse dich für die sofortige Anzeige der Kosten auf die Vorschau, nicht auf eine direkte Rechnung.
</Note>

## Zusammenspiel mit Abonnements

Ein über einen Plan verkauftes Abonnement ist ein ganz normales Abonnement. Es trägt zusätzlich einen Verweis auf die aktuell aktive Tarifstufe (`activePlanTier`).

* Beim Checkout wird das Abonnement angelegt und an die gewählte Tarifstufe gebunden.
* Ein Tarifwechsel ersetzt die Positionen des Abonnements durch die der Zielstufe und aktualisiert die aktive Tarifstufe.
* Status, Laufzeit und Abrechnung folgen den Regeln regulärer Abonnements. Eine Übersicht dazu findest du unter [Abonnements](/guide/subscriptions/introduction).


# Checkout
Source: https://docs.fynn.eu/v2-plans-api/checkout-and-sales-channels

Checkout-Links für Tarifstufen und der Weg vom Link zum Abonnement.

Verkauft wird eine Tarifstufe über einen Checkout-Link. Der Link erzeugt einen Warenkorb mit den Positionen der Tarifstufe und führt den Käufer durch den Checkout.

## Checkout-Link erstellen

```bash theme={null}
curl -X POST https://coreapi.io/api/plans/PLAN_ID/checkout-links \
  -H "Authorization: Bearer api_DEIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "planTierId": "TIER_PRO_ID",
    "couponsAllowed": false,
    "isEnabled": true,
    "salesChannel": "default"
  }'
```

| Feld             | Pflicht | Beschreibung                                                                                                                                     |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `planTierId`     | ja      | Die Tarifstufe, die der Link verkauft. Muss zum Plan gehören.                                                                                    |
| `slug`           | nein    | Eigener URL-Slug. Ohne Angabe wird automatisch einer erzeugt.                                                                                    |
| `couponsAllowed` | nein    | Ob Käufer im Checkout einen Gutschein eingeben dürfen. Standard `false`.                                                                         |
| `isEnabled`      | nein    | Ob der Link aktiv ist. Standard `true`.                                                                                                          |
| `salesChannel`   | nein    | Sales-Channel als UUID oder technischer Name (zum Beispiel `default`). Ohne Angabe greift der aktive Kanal der Anfrage, sonst der Standardkanal. |

Die Antwort enthält eine `url`. Das ist der öffentliche Einstiegspunkt: Er erzeugt einen Warenkorb und leitet den Käufer zur Customerfront des Sales-Channels weiter.

Alle Felder und Antworten: [Checkout-Link erstellen](/v2-plans-api/checkout-links/create-checkout-link) und [Checkout-Links listen](/v2-plans-api/checkout-links/list-checkout-links).

## Sales-Channel des Links

Jeder Checkout-Link gehört zu einem Sales-Channel. Der Kanal bestimmt Branding, die Customerfront-Domain und Standardeinstellungen des Checkouts. Vertriebskanäle sind ein plattformweiter Standard und gelten für V1 und V2 gleichermaßen, sie haben keine eigene V2-Variante.

<Info>
  Was ein Sales-Channel ist, wie du Domain, Branding und Standards einrichtest und wie die Customerfront-Domain aufgelöst wird, beschreibt die kanonische Anleitung [Vertriebskanäle](/guide/tenant/sales-channels). Für Pläne genügt es zu wissen: gib bei Bedarf `salesChannel` an, sonst greift der Standardkanal.
</Info>

## Vom Link zum Abonnement

<Steps>
  <Step title="Warenkorb">
    Der Aufruf der `url` erstellt einen Warenkorb. Die Positionen stammen aus der gewählten Tarifstufe.
  </Step>

  <Step title="Zahlung">
    Der Käufer schließt den Checkout in der Customerfront ab.
  </Step>

  <Step title="Abonnement mit Tarifstufe">
    Nach der Zahlung entsteht ein Abonnement, das fest an die gewählte Tarifstufe gebunden ist. Ab hier laufen weitere Wechsel über den [Tarifwechsel im Kundenbereich](/v2-plans-api/upgrades-downgrades), nicht über einen neuen Checkout.
  </Step>
</Steps>

<Note>
  Die Mengen einer Tarifstufe sind beim Plan-Checkout nicht editierbar. Es gelten die Standardmengen der Positionen. Mengenanpassungen sind erst beim Tarifwechsel im Kundenbereich möglich, sofern die Position das erlaubt.
</Note>


# Create a checkout link
Source: https://docs.fynn.eu/v2-plans-api/checkout-links/create-checkout-link

post /api/plans/{id}/checkout-links
Create a checkout link that sells one tier of the plan. The returned url is the public entry point that creates a cart and redirects the buyer to the customerfront of the sales channel.



# List checkout links of a plan
Source: https://docs.fynn.eu/v2-plans-api/checkout-links/list-checkout-links

get /api/plans/{id}/checkout-links
List all checkout links that belong to a plan, newest first.



# Kernkonzepte
Source: https://docs.fynn.eu/v2-plans-api/concepts

Plan, Tarifstufe und Position im Detail, dazu Status, Mengen und die wichtigsten Felder.

Ein Plan besteht aus einer geordneten Liste von Tarifstufen, und jede Tarifstufe enthält eine oder mehrere Positionen. Diese Seite erklärt die Felder, die du beim Anlegen setzt, und die Regeln dahinter.

Im Wallet verwaltest du Pläne unter **Pläne**. So sieht die Übersicht aus:

<Frame>
  <img alt="Übersicht der Pläne mit Status und Anzahl der Tarifstufen" />
</Frame>

Und so legst du einen Plan mit seinen Tarifstufen an:

<Frame>
  <img alt="Formular zum Anlegen eines Plans mit Tarifstufen und Positionen" />
</Frame>

## Plan

| Feld       | Typ            | Beschreibung                                                                                             |
| ---------- | -------------- | -------------------------------------------------------------------------------------------------------- |
| `code`     | string         | Stabiler, innerhalb der Organisation eindeutiger Bezeichner in Kleinbuchstaben, zum Beispiel `pro-plan`. |
| `name`     | string         | Anzeigename des Plans.                                                                                   |
| `status`   | string         | Lebenszyklus: `draft`, `active` oder `archived`.                                                         |
| `currency` | string \| null | Wird aus den Preisplänen abgeleitet. `null`, solange der Plan keine Positionen hat.                      |
| `tiers`    | array          | Die Tarifstufen, sortiert nach ihrer Position.                                                           |

### Status-Lebenszyklus

| Status     | Bedeutung                                                                      |
| ---------- | ------------------------------------------------------------------------------ |
| `draft`    | Entwurf. Bearbeitbar, aber noch nicht verkaufbar.                              |
| `active`   | Aktiv. Verkaufbar und als Quelle für Tarifwechsel nutzbar. Bleibt bearbeitbar. |
| `archived` | Archiviert. Schreibgeschützt und nicht reaktivierbar.                          |

Ein Plan startet immer als `draft`. Mit der [Aktivierung](/v2-plans-api/plans/activate-plan) wird er `active`. Beim [Löschen](/v2-plans-api/plans/delete-plan) wird er hart gelöscht, falls er nirgends referenziert ist, sonst archiviert.

<Note>
  Damit du einen Plan aktivieren kannst, muss er mindestens eine Tarifstufe haben, und jede Tarifstufe muss mindestens eine Position enthalten.
</Note>

## Tarifstufe

Eine Tarifstufe ist eine Stufe innerhalb des Plans.

| Feld               | Typ            | Beschreibung                                                                                                |
| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `position`         | integer        | Rang innerhalb des Plans. Ein kleinerer Wert ist eine niedrigere Tarifstufe. Eindeutig innerhalb des Plans. |
| `name`             | string         | Anzeigename, zum Beispiel Starter, Pro oder Business.                                                       |
| `upgradeable`      | boolean        | Ob diese Stufe nach oben verlassen werden darf. Standard `true`.                                            |
| `downgradeable`    | boolean        | Ob diese Stufe nach unten verlassen werden darf. Standard `false`.                                          |
| `changeTiming`     | string         | `immediately` oder `end_of_period`. Wann ein Wechsel in diese Stufe wirksam wird.                           |
| `creditType`       | string         | `pro_rata` oder `none`. Wie ungenutzte Zeit beim Wechsel in diese Stufe gutgeschrieben wird.                |
| `commitmentPeriod` | string \| null | Mindestlaufzeit als ISO-8601-Dauer, zum Beispiel `P1Y`. `null` bedeutet keine Mindestlaufzeit.              |

<Warning>
  Die Felder `upgradeable` und `downgradeable` beschreiben, ob eine Tarifstufe **verlassen** werden darf, nicht ob sie betreten werden darf. So kannst du gezielte Sperren zwischen Tarifstufen einbauen, etwa eine Testphase, die nur nach oben verlassen werden kann.
</Warning>

`changeTiming` und `creditType` der **Zielstufe** bestimmen gemeinsam die anteilige Berechnung. Details dazu findest du unter [Up- und Downgrades](/v2-plans-api/upgrades-downgrades#anteilige-berechnung).

## Position

Eine Position verbindet ein Produkt mit einem Preisplan innerhalb einer Tarifstufe.

| Feld              | Typ            | Beschreibung                                                                                     |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| `productId`       | string         | Produkt, das abonniert wird.                                                                     |
| `pricePlanId`     | string         | Preisplan, der zum Produkt gehört.                                                               |
| `defaultQuantity` | number         | Menge, die beim Checkout und beim Wechsel verwendet wird, wenn keine Mengenangabe gesendet wird. |
| `minQuantity`     | number \| null | Untere Grenze für Mengenanpassungen durch Kunden. `null` bedeutet keine untere Grenze.           |
| `maxQuantity`     | number \| null | Obere Grenze für Mengenanpassungen durch Kunden. `null` bedeutet keine obere Grenze.             |

<Info>
  Alle Preispläne innerhalb eines Plans müssen dieselbe Währung verwenden. Bei nutzungsbasierten Produkten ist die Menge nicht editierbar, da sie aus den Nutzungsdaten entsteht.
</Info>

### Editierbare Mengen

Ob ein Kunde die Menge einer Position anpassen darf, leitet die API automatisch ab. Eine Menge ist nicht editierbar, wenn

* das Produkt nutzungsbasiert ist (die Menge kommt aus Nutzungsereignissen), oder
* `minQuantity`, `defaultQuantity` und `maxQuantity` gleich sind (es gibt nur einen gültigen Wert).

In allen anderen Fällen ist die Menge editierbar. In der Antwort des Kundenbereichs erkennst du das am Feld `quantityEditable`.


# Get plan switch options
Source: https://docs.fynn.eu/v2-plans-api/customer/plan-options

get /api/customer/subscriptions/{id}/plan-options
Return the current tier of a subscription and all tiers it can reach, each with a financial preview. This endpoint runs in the customer context and requires a customer token with the customer.plan.switch scope.



# Preview a tier switch
Source: https://docs.fynn.eu/v2-plans-api/customer/preview-plan-tier-switch

post /api/customer/subscriptions/{id}/plan-tier-preview
Return a financial preview for switching the subscription into a target tier, with optional quantity overrides. This call does not change anything.



# Switch the plan tier
Source: https://docs.fynn.eu/v2-plans-api/customer/switch-plan-tier

post /api/customer/subscriptions/{id}/switch-plan-tier
Switch the subscription into a target tier. The change takes effect immediately or at the end of the current period, depending on the target tier. Any proration credit or charge is collected into the next invoice.



# Fynn API V2
Source: https://docs.fynn.eu/v2-plans-api/introduction

Modelliere dein Angebot als Pläne mit Tarifstufen, Up- und Downgrades und Checkout über die Fynn API V2.

Mit der Fynn API V2 modellierst du dein Angebot als **Pläne**: eine Leiter aus Tarifstufen, zwischen denen Kunden auf- und absteigen, mit Checkout und anteiliger Abrechnung beim Wechsel.

<Info>
  Pläne bildest du über die V2-Endpunkte ab. Für alle anderen Anwendungsfälle nutzt du weiterhin die [API-Referenz](/api-reference/introduction). Beide laufen parallel, du wählst pro Anwendungsfall die passende.
</Info>

## Plattformweite Grundlagen

Diese Bausteine gelten unabhängig vom Anwendungsfall:

<CardGroup>
  <Card title="Authentifizierung" icon="key" href="/v2-plans-api/authentication">
    API-Token für die Einrichtung, Kunden-Token für den Kundenbereich.
  </Card>

  <Card title="Asynchrone Abrechnung" icon="receipt" href="/v2-plans-api/billing">
    Wie Änderungen gesammelt und Rechnungen asynchron erzeugt werden.
  </Card>
</CardGroup>

<Note>
  Manche Konzepte sind plattformweiter Standard und gelten für V1 und V2 gleichermaßen. Vertriebskanäle (Sales-Channels) zum Beispiel steuern Branding, Domain und Standardeinstellungen für jeden Verkauf. Sie haben keine eigene V2-Variante. Die vollständige Anleitung findest du unter [Vertriebskanäle](/guide/tenant/sales-channels).
</Note>

## Pläne

Mit Plänen modellierst du dein Angebot als eine Leiter aus Tarifstufen, zwischen denen Kunden auf- und absteigen. Das Modell besteht aus drei Bausteinen:

<CardGroup>
  <Card title="Plan" icon="box">
    Die Klammer um dein Angebot, mit stabilem `code`, Namen und Status.
  </Card>

  <Card title="Tarifstufe" icon="stairs">
    Eine Stufe auf der Leiter, zum Beispiel Starter, Pro oder Business.
  </Card>

  <Card title="Position" icon="cube">
    Ein Produkt mit Preisplan innerhalb einer Stufe, inklusive Mengen.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Schnellstart" icon="rocket" href="/v2-plans-api/quickstart">
    Vom ersten Plan bis zum ersten Tarifwechsel in wenigen Aufrufen.
  </Card>

  <Card title="Kernkonzepte" icon="book" href="/v2-plans-api/concepts">
    Plan, Tarifstufe, Position, Status und die wichtigsten Felder.
  </Card>

  <Card title="Up- und Downgrades" icon="arrow-up-arrow-down" href="/v2-plans-api/upgrades-downgrades">
    Erreichbarkeit, Vorschau und die anteilige Berechnung.
  </Card>

  <Card title="Checkout" icon="cart-shopping" href="/v2-plans-api/checkout-and-sales-channels">
    Checkout-Links für Tarifstufen und der Weg zum Abonnement.
  </Card>

  <Card title="API-Referenz" icon="code" href="/v2-plans-api/plans/create-plan">
    Alle Endpunkte mit Parametern, Antworten und Beispielen.
  </Card>
</CardGroup>


# Activate a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/activate-plan

post /api/plans/{id}/activate
Move a plan from draft to active. The plan must have at least one tier and every tier must contain at least one item.



# Create a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/create-plan

post /api/plans
Create a new plan with its tiers and items. The plan starts in draft status. Activate it before you sell or switch into it.



# Delete or archive a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/delete-plan

delete /api/plans/{id}
Delete a plan. If the plan is not referenced anywhere it is hard deleted and the response is 204. If it is still referenced by checkout links, subscriptions or schedules it is archived instead and the response is 200 with the reference counts.



# Retrieve a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/get-plan

get /api/plans/{id}
Retrieve a single plan with all tiers and items.



# List plans
Source: https://docs.fynn.eu/v2-plans-api/plans/list-plans

get /api/plans
List the plans of your Organisation. Without a status filter all statuses are returned. Supports cursor based pagination by default and page based pagination when you pass page or offset.



# Update a plan
Source: https://docs.fynn.eu/v2-plans-api/plans/update-plan

put /api/plans/{id}
Replace a plan as a whole. Send every tier and item you want to keep. Provide ids to keep existing rows stable, and omit rows you want removed. An archived plan cannot be updated.



# Schnellstart
Source: https://docs.fynn.eu/v2-plans-api/quickstart

Vom ersten Plan bis zum ersten Tarifwechsel in wenigen Aufrufen.

Dieser Schnellstart führt dich einmal durch den gesamten Ablauf: einen Plan anlegen, ihn aktivieren, einen Checkout-Link erstellen und im Kundenbereich einen Tarifwechsel ausführen. Alle Beispiele nutzen die Sandbox unter `https://preview.coreapi.io`. Die vollständigen Parameter und Antwortfelder findest du jeweils auf der verlinkten Referenzseite.

<Steps>
  <Step title="Plan anlegen">
    Lege einen Plan mit drei Stufen an. Die Stufe Starter ist die niedrigste, Business die höchste. Der Plan startet als `draft`.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/plans \
      -H "Authorization: Bearer api_DEIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "code": "pro-plan",
        "name": "Pro Plan",
        "tiers": [
          {
            "position": 0,
            "name": "Starter",
            "upgradeable": true,
            "downgradeable": false,
            "changeTiming": "immediately",
            "creditType": "pro_rata",
            "items": [
              { "productId": "PRODUCT_STARTER", "pricePlanId": "PRICEPLAN_STARTER", "defaultQuantity": 1 }
            ]
          },
          {
            "position": 1,
            "name": "Pro",
            "upgradeable": true,
            "downgradeable": true,
            "changeTiming": "immediately",
            "creditType": "pro_rata",
            "items": [
              { "productId": "PRODUCT_PRO", "pricePlanId": "PRICEPLAN_PRO", "defaultQuantity": 1 },
              { "productId": "PRODUCT_ADDON", "pricePlanId": "PRICEPLAN_ADDON", "defaultQuantity": 1, "minQuantity": 0, "maxQuantity": 50 }
            ]
          },
          {
            "position": 2,
            "name": "Business",
            "upgradeable": false,
            "downgradeable": true,
            "changeTiming": "end_of_period",
            "creditType": "none",
            "items": [
              { "productId": "PRODUCT_BUSINESS", "pricePlanId": "PRICEPLAN_BUSINESS", "defaultQuantity": 1 }
            ]
          }
        ]
      }'
    ```

    Die Antwort enthält den Plan mit generierten IDs. Notiere dir die `id` des Plans und die `id` der Tarifstufe Pro, beides brauchst du gleich.

    Alle Felder und Antworten: [Plan anlegen](/v2-plans-api/plans/create-plan).
  </Step>

  <Step title="Plan aktivieren">
    Ein Plan muss aktiv sein, bevor du ihn verkaufen kannst.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/plans/PLAN_ID/activate \
      -H "Authorization: Bearer api_DEIN_TOKEN"
    ```

    Die Antwort zeigt den Plan mit `"status": "active"`.

    Referenz: [Plan aktivieren](/v2-plans-api/plans/activate-plan).
  </Step>

  <Step title="Checkout-Link erstellen">
    Erstelle einen Checkout-Link für die Tarifstufe, mit der neue Kunden starten sollen, hier die Stufe Pro.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/plans/PLAN_ID/checkout-links \
      -H "Authorization: Bearer api_DEIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "planTierId": "TIER_PRO_ID",
        "couponsAllowed": false,
        "isEnabled": true,
        "salesChannel": "default"
      }'
    ```

    In der Antwort steht eine `url`. Über diese URL schließt ein Kunde sein Abonnement ab. Nach der Zahlung entsteht ein Abonnement, das fest an die gewählte Tarifstufe gebunden ist.

    Alle Felder und Antworten: [Checkout-Link erstellen](/v2-plans-api/checkout-links/create-checkout-link).
  </Step>

  <Step title="Tarifoptionen im Kundenbereich abrufen">
    Ab jetzt arbeitest du im Kundenkontext mit einem Kunden-Token. Ein solches Token erzeugst du serverseitig über `POST /customers/{id}/authenticate`, siehe [Authentifizierung](/v2-plans-api/authentication). Frage damit die erreichbaren Stufen für das Abonnement des Kunden ab.

    ```bash theme={null}
    curl https://preview.coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-options \
      -H "Authorization: Bearer CUSTOMER_TOKEN"
    ```

    Die Antwort enthält die aktuelle Stufe und alle erreichbaren Optionen, jeweils mit einer Kostenvorschau.

    Referenz: [Tarifoptionen abrufen](/v2-plans-api/customer/plan-options).
  </Step>

  <Step title="Wechsel vorab prüfen">
    Zeige dem Kunden, was ein Wechsel kostet, bevor er ihn bestätigt. Die Vorschau ändert nichts.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/plan-tier-preview \
      -H "Authorization: Bearer CUSTOMER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "planTierId": "TIER_BUSINESS_ID" }'
    ```

    Referenz: [Wechsel-Vorschau](/v2-plans-api/customer/preview-plan-tier-switch).
  </Step>

  <Step title="Wechsel ausführen">
    Bestätigt der Kunde, führst du den Wechsel aus.

    ```bash theme={null}
    curl -X POST https://preview.coreapi.io/api/customer/subscriptions/SUBSCRIPTION_ID/switch-plan-tier \
      -H "Authorization: Bearer CUSTOMER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "planTierId": "TIER_BUSINESS_ID" }'
    ```

    Die Antwort bestätigt die neue Tarifstufe. Eine eventuelle Gutschrift oder Nachberechnung landet in der nächsten Rechnung, siehe [Abrechnung](/v2-plans-api/billing).

    Referenz: [Tarif wechseln](/v2-plans-api/customer/switch-plan-tier).
  </Step>
</Steps>

## Nächste Schritte

<CardGroup>
  <Card title="Up- und Downgrades" icon="arrow-up-arrow-down" href="/v2-plans-api/upgrades-downgrades">
    Erreichbarkeit, Vorschau und die anteilige Berechnung im Detail.
  </Card>

  <Card title="API-Referenz" icon="code" href="/v2-plans-api/plans/create-plan">
    Alle Felder und Antworten der einzelnen Endpunkte.
  </Card>
</CardGroup>


# Up- und Downgrades
Source: https://docs.fynn.eu/v2-plans-api/upgrades-downgrades

Erreichbare Stufen, Kostenvorschau, Ausführung und die anteilige Berechnung.

Ein Tarifwechsel verschiebt ein Abonnement von seiner aktuellen Stufe auf eine andere Stufe desselben Plans. Der Wechsel passiert immer im Kundenbereich, mit einem Kunden-Token mit der Berechtigung `customer:plan:switch`.

## Der Ablauf

<Steps>
  <Step title="Optionen abrufen">
    `GET /api/customer/subscriptions/{id}/plan-options` liefert die aktuelle Stufe und alle erreichbaren Zielstufen, jeweils mit Richtung (`upgrade` oder `downgrade`) und einer Kostenvorschau. Referenz: [Tarifoptionen abrufen](/v2-plans-api/customer/plan-options).
  </Step>

  <Step title="Vorschau berechnen">
    `POST /api/customer/subscriptions/{id}/plan-tier-preview` berechnet die Kosten für eine konkrete Zielstufe, optional mit Mengenanpassungen. Dieser Aufruf ändert nichts. Referenz: [Wechsel-Vorschau](/v2-plans-api/customer/preview-plan-tier-switch).
  </Step>

  <Step title="Wechsel ausführen">
    `POST /api/customer/subscriptions/{id}/switch-plan-tier` führt den Wechsel aus. Alle Positionen der aktuellen Stufe werden durch die Positionen der Zielstufe ersetzt. Referenz: [Tarif wechseln](/v2-plans-api/customer/switch-plan-tier).
  </Step>
</Steps>

## Erreichbarkeit

Nicht jede Stufe ist von jeder anderen aus erreichbar. Eine Zielstufe ist erreichbar, wenn

1. sie zum selben Plan gehört wie die aktuelle Stufe,
2. sie eine andere Position hat (die Richtung ergibt sich aus dem Vergleich der Positionen), und
3. jede Stufe auf dem Weg dorthin in der passenden Richtung verlassen werden darf.

Für einen Aufstieg muss jede Stufe von der aktuellen Stufe (einschließlich) bis kurz vor der Zielstufe `upgradeable` sein. Für einen Abstieg gilt dasselbe mit `downgradeable`. Die Zielstufe selbst wird nicht geprüft, sie wird ja betreten, nicht verlassen.

<Tip>
  Verlasse dich nicht auf eigene Berechnungen, welche Stufen erreichbar sind. `plan-options` liefert dir genau die Stufen, die für dieses Abonnement gültig sind, inklusive Vorschau.
</Tip>

## Mengenanpassungen

Erlaubt eine Position editierbare Mengen, kannst du im `items`-Feld der Vorschau und des Wechsels abweichende Mengen senden:

```json theme={null}
{
  "planTierId": "TIER_PRO_ID",
  "items": [
    { "planTierItemId": "ITEM_ADDON_ID", "quantity": 5 }
  ]
}
```

Die Menge muss innerhalb von `minQuantity` und `maxQuantity` der Position liegen, und die Position muss editierbar sein (`quantityEditable: true`). Andernfalls antwortet die API mit `422`.

## Anteilige Berechnung

Ob und wie beim Wechsel anteilig abgerechnet wird, bestimmen `changeTiming` und `creditType` der **Zielstufe**. Der Kunde hat darauf keinen Einfluss, das Verhalten steckt in der Konfiguration der Stufe.

| `changeTiming`  | `creditType` | Verhalten                                                                                                                                                                 |
| --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `immediately`   | `pro_rata`   | Wechsel sofort. Für die ungenutzte Zeit der bisherigen Positionen gibt es eine Gutschrift, für den angebrochenen Zeitraum der neuen Positionen eine anteilige Berechnung. |
| `immediately`   | `none`       | Wechsel sofort, ohne Gutschrift für die ungenutzte Zeit.                                                                                                                  |
| `end_of_period` | `none`       | Wechsel zum Ende der laufenden Periode. Keine anteilige Berechnung, da kein Zeitraum angebrochen wird.                                                                    |

Die Werte `full` und `last_invoiced` stehen für Pläne nicht zur Verfügung, und bei `end_of_period` ist nur `none` zulässig.

### Vorschau lesen

Die Vorschau (`SwitchPreview`) liefert die Beträge als positive Dezimalzahlen, die Richtung ergibt sich aus dem Feldnamen:

| Feld             | Bedeutung                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `creditAmount`   | Gutschrift für die ungenutzte Zeit der bisherigen Positionen. `0.00`, wenn die Zielstufe nicht gutschreibt. |
| `chargeAmount`   | Berechnung für den angebrochenen Zeitraum der neuen Positionen.                                             |
| `recurringTotal` | Der wiederkehrende Betrag der Zielstufe pro Periode (netto, Steuer, brutto).                                |
| `effectiveAt`    | Datum, für das gerechnet wird.                                                                              |
| `warnings`       | Hinweise auf Nebenwirkungen, zum Beispiel `active_discount_will_be_lost`.                                   |

<Warning>
  Bei Stufen mit `end_of_period` rechnet die Vorschau mit dem aktuellen Zeitpunkt. Die angezeigten Beträge sind dann eine Näherung. Der tatsächliche Wechsel rechnet mit dem korrekten Datum am Periodenende.
</Warning>

<Note>
  Ein aktiver Rabatt auf den bisherigen Positionen wird bei einem Wechsel nicht automatisch übernommen. Die Vorschau weist mit `active_discount_will_be_lost` darauf hin. Plane diesen Fall in deiner Oberfläche ein.
</Note>

## Antwort des Wechsels

Ein erfolgreicher Wechsel bestätigt die neue Stufe:

```json theme={null}
{
  "subscriptionId": "0c2a8f1e-9b34-7d22-8e55-1a2b3c4d5e6f",
  "newPlanTierId": "7a3d5b90-2c61-74e8-8f09-9b8c7d6e5f40",
  "warnings": []
}
```

Die finanzielle Auswirkung erscheint nicht sofort als Rechnung. Sie wird gesammelt und in die nächste Rechnung übernommen, siehe [Abrechnung](/v2-plans-api/billing).