Panoramica
Passinstance fornisce un motore di transizione degli abbonamenti deterministico e idempotente (Billing API su /api/v1/billing/subscription/* e Impostazioni -> Fatturazione /settings/billing/overview, oltre alle sessioni ospitate di Checkout/Portale su POST /api/v1/billing/checkout/session e /portal) che Le consente di visualizzare in anteprima i crediti di conguaglio proporzionale calcolati al minuto prima di confermare una modifica del piano, eseguire upgrade istantanei, pianificare o revocare downgrade di fine periodo e annullare o riattivare gli abbonamenti senza alcuna interruzione per i pass attivi.
Ciclo di vita della transizione del piano e del conguaglio proporzionale
Importante: Può effettuare il downgrade a una fascia inferiore solo se il conteggio attuale di
activePassesdel workspace è pari o inferiore al limite di capacità del piano di destinazione. Se i pass attivi superano la fascia di destinazione,/previewe/changerestituiscono un blocco di capacità strutturato che indica quanti pass attivi devono essere ridotti prima di procedere.
Endpoint di transizione dell'abbonamento (Billing API)
| Endpoint | Verbo HTTP | Comportamento operativo |
|---|---|---|
/api/v1/billing/subscription/preview | POST | Valuta request payload ({ planId, promotionCode? }) e calcola l'esatto conguaglio proporzionale, le imposte e l'idoneità di capacità senza modificare lo stato. |
/api/v1/billing/subscription/change | POST | Esegue request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }). |
/api/v1/billing/subscription/scheduled-change/cancel | POST | Revoca un downgrade di fine periodo in sospeso in modo che il workspace rimanga sulla fascia corrente. |
/api/v1/billing/subscription/cancel | POST | Pianifica la cancellazione dell'abbonamento alla fine del periodo (request payload: { reason?, feedback? }). |
/api/v1/billing/subscription/resume | POST | Annulla una cancellazione in sospeso prima della scadenza di currentPeriodEnd, preservando il rinnovo continuo. |
Guida API: anteprima ed esecuzione delle modifiche al piano
1. Visualizzare l'anteprima del conguaglio prima di cambiare piano
Chiami sempre POST /api/v1/billing/subscription/preview indicando il planId di destinazione (recuperato da 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"
}
Payload di risposta (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. Eseguire un upgrade o downgrade idempotente del piano
Passi planId e una idempotencyKey univoca (più il controllo opzionale expectedAmountDueToday corrispondente all'anteprima) a 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. Revocare un downgrade pianificato (scheduled-change/cancel)
Se un downgrade è stato pianificato per entrare in vigore alla fine del periodo di fatturazione, può annullare tale transizione in sospeso in qualsiasi momento prima di 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. Pianificare la cancellazione a fine periodo e riattivare l'abbonamento
Quando effettua la cancellazione tramite POST /api/v1/billing/subscription/cancel, il Suo workspace mantiene l'intera capacità pagata fino alla scadenza del periodo già saldato:
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"
}
Per annullare la cancellazione prima del 2026-12-01T00:00:00.000Z, chiami POST /api/v1/billing/subscription/resume, che reimposta immediatamente cancelAtPeriodEnd: false.
Documentazione correlata
-
Confronti le fasce dei piani in Prezzi e piani di abbonamento.
-
Scarichi le fatture PDF con conguaglio proporzionale in Fatture e cronologia di fatturazione.
-
Gestisca le carte di credito salvate e gli strumenti di pagamento in Metodi di pagamento.
