Overzicht
Passinstance biedt een deterministische, idempotente abonnementswissel-engine (Billing API op /api/v1/billing/subscription/* en Instellingen -> Facturatie /settings/billing/overview, plus gehoste Checkout/Portal-sessies via POST /api/v1/billing/checkout/session en /portal) waarmee u op de minuut nauwkeurige pro-ratakredieten vooraf kunt bekijken, directe upgrades kunt uitvoeren, downgrades per einde periode kunt plannen of intrekken en abonnementen zonder uitvaltijd voor actieve passen kunt opzeggen of hervatten.
Levenscyclus van abonnementswijziging & pro-rata verrekening
Belangrijk: U kunt alleen downgraden naar een lager pakket als het huidige aantal
activePassesvan uw werkruimte gelijk is aan of lager ligt dan de limiet van het doelplan. Overschrijden uw actieve passen de doellimiet, dan geven/previewen/changeeen gestructureerde capaciteitsblokkade terug met het aantal actieve passen dat eerst moet worden verminderd.
Endpoints voor abonnementswijzigingen (Billing API)
| Endpoint | HTTP-methode | Operationeel gedrag |
|---|---|---|
/api/v1/billing/subscription/preview | POST | Evalueert request payload ({ planId, promotionCode? }) en berekent exacte pro-rata, btw en geschiktheid zonder de status te wijzigen. |
/api/v1/billing/subscription/change | POST | Voert request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }) uit. |
/api/v1/billing/subscription/scheduled-change/cancel | POST | Trekt een geplande downgrade per einde periode in zodat de werkruimte op het huidige niveau blijft. |
/api/v1/billing/subscription/cancel | POST | Plant abonnementsopzegging aan het einde van de huidige periode (request payload: { reason?, feedback? }). |
/api/v1/billing/subscription/resume | POST | Maakt een geplande opzegging ongedaan voordat currentPeriodEnd aanbreekt, zodat verlenging doorloopt. |
API-uitleg: planwijzigingen vooraf bekijken en uitvoeren
1. Pro-rata vooraf bekijken vóór wijziging
Roep altijd eerst POST /api/v1/billing/subscription/preview aan met de gewenste planId (opgehaald via 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"
}
Antwoordpayload (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. Idempotente upgrade of downgrade uitvoeren
Geef planId en een unieke idempotencyKey (plus optionele expectedAmountDueToday-controle op basis van de voorvertoning) door aan 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. Een geplande downgrade intrekken (scheduled-change/cancel)
Als een downgrade gepland staat voor het einde van de factureringsperiode, kunt u die geplande overgang op elk moment vóór currentPeriodEnd annuleren:
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. Opzegging per einde periode plannen & hervatten
Bij opzegging via POST /api/v1/billing/subscription/cancel behoudt uw werkruimte de volledige betaalde capaciteit totdat de reeds betaalde periode afloopt:
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"
}
Om de opzegging vóór 2026-12-01T00:00:00.000Z ongedaan te maken, roept u POST /api/v1/billing/subscription/resume aan, waarmee cancelAtPeriodEnd: false direct wordt hersteld.
Gerelateerde documentatie
-
Vergelijk abonnementsniveaus in Prijzen & abonnementsplannen.
-
Download pro-rata PDF-facturen in Facturen & facturatiegeschiedenis.
-
Beheer opgeslagen betaalkaarten en betaalmethoden in Betaalmethoden.
