Skip to content
Hilfecenter-Anleitung · Tarife & Nutzung
2 Min. LesezeitGeprüft 2026-11-16

Tarifwechsel & Kündigung

Wechseln Sie Kapazitätsstufen sofort, ändern Sie Abrechnungszyklen und kündigen Sie Abonnements sauber zum Laufzeitende.

In dieser Anleitung

Ü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)

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
ZUSTANDSAUTOMAT FÜR ABONNEMENTWECHSEL & PRORATION
STUFE 01 SCHRITT 1: PRORATION-VORSCHAU
POST/api/v1/billing/subscription/preview (request payload)
Berechnet ungenutzte Restzeit-Gutschrift vs. Restlaufzeit des Zieltarifs
Prüft aktuelle activePasses gegen das Kapazitätslimit der Zielstufe
STUFE 02 SCHRITT 2: IDEMPOTENTE AUSFÜHRUNG
Unterjähriges Upgrade / Intervall
Sofortige Kapazitätsfreischaltung
Prüft expectedAmountDueToday gegen Preisabweichungen
Stufen-Downgrade
Geplant auf currentPeriodEnd
Widerrufbar via `/scheduled-change
/cancel` vor Verlängerung
POST/api/v1/billing/subscription/change (request payload)
STUFE 03 SCHRITT 3: KÜNDIGUNG ZUM PERIODENENDE & RESUME
POST/api/v1/billing/subscription/cancel (CANCEL_AT_PERIOD_END / Cancel)
POST/api/v1/billing/subscription/resume (Auto-Verlängerung jederzeit wieder)

Wichtig: Ein Downgrade auf eine kleinere Stufe ist nur möglich, wenn die aktuelle Anzahl activePasses Ihres Workspaces kleiner oder gleich dem Kapazitätslimit des Zieltarifs ist. Übersteigen Ihre aktiven Pässe das Ziellimit, geben /preview und /change eine strukturierte Kapazitätsblockade zurück, die ausweist, um wie viele aktive Pässe zuerst reduziert werden muss.

Endpunkte für Tarifwechsel (Billing API)

EndpunktHTTP-VerbBetriebliches Verhalten
/api/v1/billing/subscription/previewPOSTBewertet request payload ({ planId, promotionCode? }) und berechnet exakte Proration, Steuern und Kapazitätsfähigkeit ohne Zustandsänderung.
/api/v1/billing/subscription/changePOSTFührt request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }) aus.
/api/v1/billing/subscription/scheduled-change/cancelPOSTWiderruft ein geplantes Downgrade zum Periodenende, sodass der Workspace im aktuellen Tarif bleibt.
/api/v1/billing/subscription/cancelPOSTPlant die Abonnementkündigung zum Periodenende (request payload: { reason?, feedback? }).
/api/v1/billing/subscription/resumePOSTNimmt 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):

HTTP
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)

JSON
{
  "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:

HTTP
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
}
JSON
{
  "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:

HTTP
POST /api/v1/billing/subscription/scheduled-change/cancel HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "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:

HTTP
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."
}
JSON
{
  "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

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.