> ## 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, 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 caption="Plan-Übersicht im Wallet.">
  <img src="https://mintcdn.com/fynnsubscriptionbilling/YifwwUxUm_gUtslw/images/v2-plans/plans-list.png?fit=max&auto=format&n=YifwwUxUm_gUtslw&q=85&s=ae137c63cdcc212697abe62ced48fb85" alt="Übersicht der Pläne mit Status und Anzahl der Tarifstufen" width="1440" height="900" data-path="images/v2-plans/plans-list.png" />
</Frame>

Und so legst du einen Plan mit seinen Tarifstufen an:

<Frame caption="Plan anlegen im Wallet.">
  <img src="https://mintcdn.com/fynnsubscriptionbilling/YifwwUxUm_gUtslw/images/v2-plans/plan-create.png?fit=max&auto=format&n=YifwwUxUm_gUtslw&q=85&s=b9df6c6c2c19fe0a5344c188a509ee90" alt="Formular zum Anlegen eines Plans mit Tarifstufen und Positionen" width="1440" height="900" data-path="images/v2-plans/plan-create.png" />
</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`.