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
Important : Vous ne pouvez rétrograder vers un palier inférieur que si le nombre actuel d'
activePassesde 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,/previewet/changerenvoient 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 terminaison | Verbe HTTP | Comportement opérationnel |
|---|---|---|
/api/v1/billing/subscription/preview | POST | É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/change | POST | Exécute request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }). |
/api/v1/billing/subscription/scheduled-change/cancel | POST | Ré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/cancel | POST | Planifie la résiliation de l'abonnement à la fin de la période (request payload : { reason?, feedback? }). |
/api/v1/billing/subscription/resume | POST | Annule 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) :
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)
{
"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 :
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. 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 :
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. 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 :
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"
}
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
-
Comparez les paliers d'abonnement dans Tarification et forfaits d'abonnement.
-
Téléchargez vos factures PDF au prorata dans Factures et historique de facturation.
-
Gérez vos cartes bancaires et instruments de paiement enregistrés dans Moyens de paiement.
