Skip to content
Guide du centre d'aide · Forfaits & utilisation
3 min de lectureVérifié 2026-11-16

Changement de formule & résiliation

Évoluez immédiatement de palier, modifiez la périodicité ou résiliez en fin de période sans frais inattendus.

Dans ce guide

Présentation

Passinstance fournit un moteur déterministe et idempotent de transition d'abonnement (Billing API sur /api/v1/billing/subscription/* et sous Settings -> Billing /settings/billing/overview, ainsi que des sessions hébergées Checkout/Portal sur POST /api/v1/billing/checkout/session et /portal) qui vous permet de prévisualiser à la minute près vos avoirs au prorata avant de confirmer un changement de forfait, d'exécuter des mises à niveau instantanées, de planifier ou d'annuler des rétrogradations en fin de période, et de résilier ou reprendre vos abonnements sans aucune interruption pour vos passes en production.

Cycle de vie de transition de forfait et de calcul au prorata

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : TRANSITION D'ABONNEMENT & MACHINE À ÉTATS PRORATA
ÉTAPE 01 ÉTAPE 1 : APERÇU DU PRORATA
POST/api/v1/billing/subscription/preview (request payload)
Calcule l'avoir du temps non utilisé vs le temps restant sur le forfait cible
Valide le nombre actuel d'activePasses par rapport au plafond cible
ÉTAPE 02 ÉTAPE 2 : EXÉCUTION IDEMPOTENTE
Mise à niveau / Changement cycle
Déblocage immédiat de la capacité
Valide expectedAmountDueToday pour éviter tout écart de prix
Rétrogradation de palier
Planifiée à currentPeriodEnd
Révocable via `/scheduled-change
/cancel` avant le renouvellement
POST/api/v1/billing/subscription/change (request payload)
ÉTAPE 03 ÉTAPE 3 : RÉSILIATION EN FIN DE PÉRIODE & REPRISE
POST/api/v1/billing/subscription/cancel (CANCEL_AT_PERIOD_END / Cancel)
POST/api/v1/billing/subscription/resume (Restaure le renouvellement auto)

Important : Vous ne pouvez rétrograder vers un palier inférieur que si le nombre actuel d'activePasses de votre espace de travail est inférieur ou égal à la limite de capacité du forfait cible. Si vos passes actifs dépassent le palier cible, /preview et /change renvoient un blocage de capacité structuré indiquant combien de passes actifs doivent d'abord être réduits.

Points de terminaison de transition d'abonnement (Billing API)

Point de terminaisonVerbe HTTPComportement opérationnel
/api/v1/billing/subscription/previewPOSTÉvalue request payload ({ planId, promotionCode? }) et calcule le prorata exact, la taxe et l'éligibilité de capacité sans modifier l'état.
/api/v1/billing/subscription/changePOSTExécute request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }).
/api/v1/billing/subscription/scheduled-change/cancelPOSTRévoque une rétrogradation en fin de période en attente afin que l'espace de travail conserve son palier actuel.
/api/v1/billing/subscription/cancelPOSTPlanifie la résiliation de l'abonnement à la fin de la période (request payload : { reason?, feedback? }).
/api/v1/billing/subscription/resumePOSTAnnule une résiliation en attente avant l'échéance de currentPeriodEnd, préservant ainsi le renouvellement continu.

Guide de l'API : Prévisualisation et exécution des changements de forfait

1. Prévisualiser le prorata avant de changer de forfait

Appelez toujours POST /api/v1/billing/subscription/preview avec le planId cible (récupéré depuis 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"
}

Charge utile de réponse (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. Exécuter une mise à niveau ou une rétrogradation idempotente de forfait

Transmettez planId et une clé idempotencyKey unique (ainsi que la protection facultative expectedAmountDueToday correspondant à l'aperçu) à 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. Révoquer une rétrogradation planifiée (scheduled-change/cancel)

Si une rétrogradation a été planifiée pour prendre effet à la fin de la période de facturation, vous pouvez annuler cette transition en attente à tout moment avant currentPeriodEnd :

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. Planifier une résiliation en fin de période et reprendre l'abonnement

Lorsque vous résiliez via POST /api/v1/billing/subscription/cancel, votre espace de travail conserve l'intégralité de sa capacité payée jusqu'à l'expiration de la période déjà réglée :

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

Pour annuler la résiliation avant le 2026-12-01T00:00:00.000Z, appelez POST /api/v1/billing/subscription/resume, ce qui réinitialise immédiatement cancelAtPeriodEnd: false.

Documentation connexe

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.