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

# Up- und 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).