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:
Und so legst du einen Plan mit seinen Tarifstufen an:
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. |
draft. Mit der Aktivierung wird er active. Beim Löschen wird er hart gelöscht, falls er nirgends referenziert ist, sonst archiviert.
Damit du einen Plan aktivieren kannst, muss er mindestens eine Tarifstufe haben, und jede Tarifstufe muss mindestens eine Position enthalten.
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. |
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.
changeTiming und creditType der Zielstufe bestimmen gemeinsam die anteilige Berechnung. Details dazu findest du unter Up- und Downgrades.
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. |
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.
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. 
