Überblick
Passinstance stellt eine deterministische, idempotente Engine für Abonnementwechsel bereit (Billing API unter /api/v1/billing/subscription/* sowie Einstellungen -> Abrechnung /settings/billing/overview, ergänzt durch gehostete Checkout-/Portal-Sitzungen unter POST /api/v1/billing/checkout/session und /portal). Sie ermöglicht es Ihnen, exakte minutengenaue Anteilig-Gutschriften (Proration) vor der Bestätigung zu prüfen, sofortige Upgrades auszuführen, Downgrades zum Periodenende zu planen oder zu widerrufen sowie Abonnements ohne Unterbrechung aktiver Pässe zu kündigen oder fortzusetzen.
Lebenszyklus von Tarifwechseln & Anteilig-Verrechnung (Proration)
Wichtig: Ein Downgrade auf eine kleinere Stufe ist nur möglich, wenn die aktuelle Anzahl
activePassesIhres Workspaces kleiner oder gleich dem Kapazitätslimit des Zieltarifs ist. Übersteigen Ihre aktiven Pässe das Ziellimit, geben/previewund/changeeine strukturierte Kapazitätsblockade zurück, die ausweist, um wie viele aktive Pässe zuerst reduziert werden muss.
Endpunkte für Tarifwechsel (Billing API)
| Endpunkt | HTTP-Verb | Betriebliches Verhalten |
|---|---|---|
/api/v1/billing/subscription/preview | POST | Bewertet request payload ({ planId, promotionCode? }) und berechnet exakte Proration, Steuern und Kapazitätsfähigkeit ohne Zustandsänderung. |
/api/v1/billing/subscription/change | POST | Führt request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }) aus. |
/api/v1/billing/subscription/scheduled-change/cancel | POST | Widerruft ein geplantes Downgrade zum Periodenende, sodass der Workspace im aktuellen Tarif bleibt. |
/api/v1/billing/subscription/cancel | POST | Plant die Abonnementkündigung zum Periodenende (request payload: { reason?, feedback? }). |
/api/v1/billing/subscription/resume | POST | Nimmt eine vorgemerkte Kündigung vor Erreichen von currentPeriodEnd zurück und stellt die fortlaufende Verlängerung wieder her. |
API-Praxisbeispiel: Tarifwechsel vorausschauen & ausführen
1. Proration vor dem Tarifwechsel prüfen
Rufen Sie vorab POST /api/v1/billing/subscription/preview mit der gewünschten planId auf (abrufbar unter GET /api/v1/billing/plans):
POST /api/v1/billing/subscription/preview HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"planId": "scale_10k_monthly",
"promotionCode": "SCALEUP15"
}
Antwort-Payload (200 OK)
{
"eligible": true,
"transitionType": "IMMEDIATE_UPGRADE",
"currentPlan": { "planId": "growth_monthly", "activePassLimit": 2000 },
"targetPlan": { "planId": "scale_10k_monthly", "activePassLimit": 10000 },
"proration": {
"currency": "EUR",
"unusedCreditCents": -6000,
"proratedNewPlanCents": 20000,
"discountCents": -2100,
"subtotalCents": 11900,
"taxCents": 2261,
"totalDueNowCents": 14161,
"nextRenewalAmountCents": 40000,
"nextRenewalDate": "2026-12-01T00:00:00.000Z"
},
"blockers": []
}
2. Idempotentes Tarif-Upgrade oder -Downgrade ausführen
Übergeben Sie planId und einen eindeutigen idempotencyKey (sowie optional die Sicherheitsprüfung expectedAmountDueToday passend zur Vorschau) an POST /api/v1/billing/subscription/change:
POST /api/v1/billing/subscription/change HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"planId": "scale_10k_monthly",
"idempotencyKey": "chg_20261116_scale10k",
"promotionCode": "SCALEUP15",
"expectedAmountDueToday": 141.61
}
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"status": "ACTIVE",
"planId": "scale_10k_monthly",
"effectiveActivePassLimit": 10000,
"appliedImmediately": true,
"invoiceId": "inv_01933220-5a11-7e00-9c44-887766554433"
}
3. Geplantes Downgrade widerrufen (scheduled-change/cancel)
Wenn ein Downgrade zum Ende des Abrechnungszeitraums vorgemerkt wurde, können Sie diesen ausstehenden Wechsel jederzeit vor currentPeriodEnd abbrechen:
POST /api/v1/billing/subscription/scheduled-change/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"scheduledChangeCanceled": true,
"activePlanKey": "scale_10k"
}
4. Kündigung zum Periodenende planen & reaktivieren
Bei einer Kündigung über POST /api/v1/billing/subscription/cancel behält Ihr Workspace die volle bezahlte Kapazität bis zum Ablauf des bereits bezahlten Zeitraums:
POST /api/v1/billing/subscription/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"reason": "SEASONAL_EVENT_ENDED",
"feedback": "Our annual festival concluded; we will return next summer."
}
{
"subscriptionId": "sub_019331b2-7e10-7a44-9b00-112233445566",
"status": "ACTIVE",
"cancelAtPeriodEnd": true,
"accessValidUntil": "2026-12-01T00:00:00.000Z"
}
Um die Kündigung vor dem 2026-12-01T00:00:00.000Z zurückzunehmen, rufen Sie POST /api/v1/billing/subscription/resume auf, wodurch cancelAtPeriodEnd: false sofort wiederhergestellt wird.
Weiterführende Dokumentation
-
Tarifstufen vergleichen in Preise & Abonnement-Tarife.
-
Anteilig berechnete PDF-Rechnungen herunterladen in Rechnungen & Abrechnungshistorie.
-
Gespeicherte Kreditkarten und Zahlungsinstrumente verwalten in Zahlungsmethoden.
