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

# Kernkonzepte

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