Skip to content
Helpcentrum-gids · Pakketten & verbruik
2 min leestijdGecontroleerd 2026-11-16

Pakketwijziging & opzegging

Upgrade direct tussen capaciteitspakketten, wijzig factuurcycli of zeg netjes op per einde looptijd.

In deze gids

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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
TOESTANDSMACHINE VOOR ABONNEMENTSOORGANG & PRO-RATA
FASE 01 STAP 1: PRO-RATA VOORVERTONING
POST/api/v1/billing/subscription/preview (request payload)
Berekent ongebruikt tegoed op huidig plan vs. resterende duur nieuw doelplan
Valideert huidig aantal activePasses tegen limiet van doelniveau
FASE 02 STAP 2: IDEMPOTENTE UITVOERING
Tussentijdse upgrade / interval
Directe capaciteitsuitbreiding
Valideert expectedAmountDueToday om prijsafwijking te voorkomen
Niveau-downgrade
Gepland op currentPeriodEnd
Intrekbaar via `/scheduled-change
/cancel` vóór verlenging
POST/api/v1/billing/subscription/change (request payload)
FASE 03 STAP 3: OPZEGGING EINDE PERIODE & HERVATTEN
POST/api/v1/billing/subscription/cancel (CANCEL_AT_PERIOD_END / Cancel)
POST/api/v1/billing/subscription/resume (Herstelt automatische verlenging)

Belangrijk: U kunt alleen downgraden naar een lager pakket als het huidige aantal activePasses van uw werkruimte gelijk is aan of lager ligt dan de limiet van het doelplan. Overschrijden uw actieve passen de doellimiet, dan geven /preview en /change een gestructureerde capaciteitsblokkade terug met het aantal actieve passen dat eerst moet worden verminderd.

Endpoints voor abonnementswijzigingen (Billing API)

EndpointHTTP-methodeOperationeel gedrag
/api/v1/billing/subscription/previewPOSTEvalueert request payload ({ planId, promotionCode? }) en berekent exacte pro-rata, btw en geschiktheid zonder de status te wijzigen.
/api/v1/billing/subscription/changePOSTVoert request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }) uit.
/api/v1/billing/subscription/scheduled-change/cancelPOSTTrekt een geplande downgrade per einde periode in zodat de werkruimte op het huidige niveau blijft.
/api/v1/billing/subscription/cancelPOSTPlant abonnementsopzegging aan het einde van de huidige periode (request payload: { reason?, feedback? }).
/api/v1/billing/subscription/resumePOSTMaakt 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):

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"
}

Antwoordpayload (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. 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:

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

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

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"
}

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

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.