Skip to content
Guida del Centro assistenza · Piani e utilizzo
3 min di letturaVerificato 2026-11-16

Cambio piano e disdetta

Aggiorna la capacità immediatamente, modifica la cadenza di rinnovo o annulla a fine periodo senza sorprese.

In questa guida

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
MACCHINA A STATI DI TRANSIZIONE E CONGUAGLIO ABBONAMENTO
FASE 01 FASE 1: ANTEPRIMA DEL CONGUAGLIO PROPORZIONALE
POST/api/v1/billing/subscription/preview (request payload)
Calcola il credito per il tempo non utilizzato rispetto al piano di destinaz.
Convalida i activePasses attuali rispetto al limite della fascia scelta
FASE 02 FASE 2: ESECUZIONE IDEMPOTENTE
Upgrade a metà ciclo / Cambio ciclo
Sblocco immediato della capacità
Convalida expectedAmountDueToday per evitare scostamenti di prezzo
Downgrade di fascia
Pianificato a currentPeriodEnd
Revocabile via `/scheduled-change
/cancel` prima del rinnovo
POST/api/v1/billing/subscription/change (request payload)
FASE 03 FASE 3: CANCELLAZIONE A FINE PERIODO E RIATTIVAZIONE
POST/api/v1/billing/subscription/cancel (CANCEL_AT_PERIOD_END / Cancel)
POST/api/v1/billing/subscription/resume (Ripristina il rinnovo automatico)

Importante: Può effettuare il downgrade a una fascia inferiore solo se il conteggio attuale di activePasses del workspace è pari o inferiore al limite di capacità del piano di destinazione. Se i pass attivi superano la fascia di destinazione, /preview e /change restituiscono un blocco di capacità strutturato che indica quanti pass attivi devono essere ridotti prima di procedere.

Endpoint di transizione dell'abbonamento (Billing API)

EndpointVerbo HTTPComportamento operativo
/api/v1/billing/subscription/previewPOSTValuta 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/changePOSTEsegue request payload ({ planId, idempotencyKey, promotionCode?, paymentMethodId?, expectedAmountDueToday?, intent? }).
/api/v1/billing/subscription/scheduled-change/cancelPOSTRevoca un downgrade di fine periodo in sospeso in modo che il workspace rimanga sulla fascia corrente.
/api/v1/billing/subscription/cancelPOSTPianifica la cancellazione dell'abbonamento alla fine del periodo (request payload: { reason?, feedback? }).
/api/v1/billing/subscription/resumePOSTAnnulla 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):

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

Payload di risposta (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. 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:

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

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

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

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

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.