Zum Hauptinhalt springen
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

1

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

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

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.

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

​
Mengenanpassungen

Erlaubt eine Position editierbare Mengen, kannst du im items-Feld der Vorschau und des Wechsels abweichende Mengen senden: 
{
  "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.
changeTimingcreditTypeVerhalten
immediatelypro_rataWechsel sofort. Für die ungenutzte Zeit der bisherigen Positionen gibt es eine Gutschrift, für den angebrochenen Zeitraum der neuen Positionen eine anteilige Berechnung.
immediatelynoneWechsel sofort, ohne Gutschrift für die ungenutzte Zeit.
end_of_periodnoneWechsel 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:
FeldBedeutung
creditAmountGutschrift für die ungenutzte Zeit der bisherigen Positionen. 0.00, wenn die Zielstufe nicht gutschreibt.
chargeAmountBerechnung für den angebrochenen Zeitraum der neuen Positionen.
recurringTotalDer wiederkehrende Betrag der Zielstufe pro Periode (netto, Steuer, brutto).
effectiveAtDatum, für das gerechnet wird.
warningsHinweise auf Nebenwirkungen, zum Beispiel active_discount_will_be_lost.
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.
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.

​
Antwort des Wechsels

Ein erfolgreicher Wechsel bestätigt die neue Stufe: 
{
  "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.