Subscription Upgrade & Downgrade Guide - Dodo Payments Documentation

Change Plan API

Full API docs for updating subscriptions.

Plan Change Preview

See charge amounts before changing plans.

Integration Guide

Step-by-step subscription setup.

What Is a Subscription Upgrade or Downgrade?

Change a customer’s subscription plan to move them between tiers, adjust quantity for seat-based products, or migrate to a new product. The API automatically calculates prorations and charges based on your chosen billing mode.

Plan changes can trigger an immediate charge depending on the proration mode you choose.

When to Use Plan Changes

Upgrade when a customer needs more features, usage, or seats
Downgrade when usage decreases
Migrate users to a new product or price without cancelling their subscription

Plan Change Flow

Prerequisites

Before implementing subscription plan changes, ensure you have:

A Dodo Payments merchant account with active subscription products
API credentials (API key and webhook secret key) from the dashboard
An existing active subscription to modify
Webhook endpoint configured to handle subscription events

For detailed setup instructions, see the Integration Guide.

Step-by-Step Implementation Guide

Follow this comprehensive guide to implement subscription plan changes in your application:

Understand Plan Change Requirements

Before implementing, determine:

Which subscription products can be changed to which others
What proration mode fits your business model
How to handle failed plan changes gracefully
Which webhook events to track for state management

Test plan changes thoroughly in test mode before implementing in production.

Choose Your Proration Strategy

Select the billing approach that aligns with your business needs:

prorated_immediately
difference_immediately
full_immediately
do_not_bill

Best for: SaaS applications that want to credit unused time on the old plan.

Credits the unused portion of the current cycle, prorated by time remaining
Then charges a full cycle at the new plan — the new plan price is never prorated
Net charge = full new cycle − (remaining fraction × full old cycle)

Implement the Change Plan API

Use the Change Plan API to modify subscription details:

string

obbligatorio

The ID of the active subscription to modify.

string

obbligatorio

Il nuovo ID prodotto a cui cambiare l’abbonamento.

integer

obbligatorio

Numero di unità per il nuovo piano (per prodotti basati sui posti).

string

obbligatorio

Come gestire la fatturazione immediata: prorated_immediately, full_immediately, difference_immediately o do_not_bill.

array

Componenti aggiuntivi facoltativi per il nuovo piano. Omettere questo campo, inviare null o inviare un array vuoto rimuove tutti i componenti aggiuntivi esistenti; includi quindi i componenti aggiuntivi attuali per mantenerli.

string

Controlla il comportamento quando il pagamento della modifica del piano non va a buon fine:

prevent_change: Mantieni l’abbonamento sul piano attuale finché il pagamento non va a buon fine
apply_change (predefinito): Applica immediatamente la modifica del piano indipendentemente dall’esito del pagamento

If not specified, uses the business-level default setting.

boolean

Raccogli l’importo della modifica del piano con un link di pagamento invece di addebitare il metodo di pagamento salvato dell’abbonamento. Il cliente paga su una pagina di checkout ospitata.Requires the business’s allow_plan_change_via_payment_link capability (Settings → Subscriptions → Collect Plan Change Payments by Payment Link), effective_at: immediately, and on_payment_failure: prevent_change. See Collecting Payment via a Checkout Link. Ignored by the preview route.

string

L’URL che riceve il cliente dopo aver pagato il link di pagamento. Il reindirizzamento aggiunge subscription_id, payment_id e status. Richiede collect_via_payment_link: true; in caso contrario, la richiesta fallisce con 422. Consulta Reindirizzamento del cliente dopo il pagamento.

boolean

predefinito:"false"

Annulla il link di pagamento non pagato di una modifica del piano in sospeso, in modo che questa richiesta lo sostituisca. Un pagamento già effettuato o in corso restituisce 409. Consulta Sostituzione di un link di pagamento in sospeso. Ignorato dalla route di anteprima.

array

Codici sconto stacked facoltativi da applicare al nuovo piano (massimo 20, applicati nell’ordine dell’array). Il comportamento dipende da ciò che passi:

Non fornito / null — gli sconti esistenti con preserve_on_plan_change=true vengono mantenuti, se applicabili al nuovo prodotto.
[] (array vuoto) — rimuove tutti gli sconti esistenti dall’abbonamento.
["CODE_A", "CODE_B", ...] — sostituisce gli sconti esistenti con questo set stacked.

string

deprecato

Deprecato — per le nuove integrazioni, preferisci discount_codes. Questo campo continua a funzionare per la compatibilità con le versioni precedenti, ma non può essere combinato con discount_codes nella stessa richiesta.

string

predefinito:"immediately"

Quando applicare la modifica del piano:

immediately (predefinito): Applica subito la modifica del piano
next_billing_date: Pianifica la modifica per la prossima data di fatturazione. Il cliente mantiene il piano attuale fino alla fine del periodo di fatturazione. Usalo per i downgrade, così i clienti mantengono i vantaggi del piano attuale fino alla fine del periodo di fatturazione.

Handle Webhook Events

Configura la gestione dei webhook per monitorare gli esiti delle modifiche del piano:

subscription.active: Modifica del piano completata, abbonamento aggiornato
subscription.plan_changed: Piano dell’abbonamento modificato (upgrade/downgrade/aggiornamento dell’addon)
subscription.on_hold: Addebito della modifica del piano non riuscito, rinnovi interrotti
payment.succeeded: Addebito immediato della modifica del piano completato
payment.failed: Addebito immediato non riuscito

Verifica sempre le firme dei webhook e implementa l’elaborazione idempotente degli eventi.

Update Your Application State

In base agli eventi webhook, aggiorna la tua applicazione:

Concedi/revoca le funzionalità in base al nuovo piano
Aggiorna il dashboard del cliente con i dettagli del nuovo piano
Invia email di conferma sulle modifiche del piano
Registra le modifiche di fatturazione per scopi di audit

Test and Monitor

Testa accuratamente la tua implementazione:

Testa tutte le modalità di prorazione con scenari diversi
Verifica che la gestione dei webhook funzioni correttamente
Monitora i tassi di successo delle modifiche del piano
Configura avvisi per le modifiche del piano non riuscite

L’implementazione della modifica del piano dell’abbonamento è ora pronta per l’uso in produzione.

Anteprima delle modifiche del piano

Prima di confermare una modifica del piano, usa l’API Preview per mostrare ai clienti esattamente quanto verrà loro addebitato:

Node.js SDK
Python SDK

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('Immediate charge:', preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency);
console.log('New plan details:', preview.new_plan);

preview = client.subscriptions.preview_change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately"
)

# Show customer the charge before confirming
print("Immediate charge:", preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency)
print("New plan details:", preview.new_plan)

Usa l’API Preview per creare finestre di conferma che mostrino ai clienti l’importo esatto che verrà loro addebitato prima che confermino una modifica del piano.

In immediate_charge.summary, customer_credits è la variazione netta del saldo crediti del cliente, nella valuta indicata da customer_credits_currency. Questa è la valuta del portafoglio crediti del cliente, che corrisponde alla valuta dell’abbonamento. Può differire da currency del riepilogo, che si applica a total_amount e tax. Ad esempio, un cliente che paga in INR per un abbonamento in USD visualizza i crediti in USD.

API Change Plan

Usa l’API Change Plan per modificare prodotto, quantità e comportamento della prorazione per un abbonamento attivo.

Esempi rapidi

Node.js SDK
Python SDK
Go SDK
HTTP

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function changePlan() {
  // change-plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
  // client_secret, expires_on) — all null for an ordinary off-session change.
  await client.subscriptions.changePlan('sub_123', {
    product_id: 'pdt_new',
    quantity: 3,
    proration_billing_mode: 'prorated_immediately',
    on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
  });
  console.log('Plan change accepted; awaiting webhooks');
}

changePlan();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

# change_plan returns 200 with a ChangePlanResponse body (payment_id, payment_link,
# client_secret, expires_on) — all None for an ordinary off-session change.
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_new",
    quantity=3,
    proration_billing_mode="prorated_immediately",
    on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
)
print("Plan change accepted; awaiting webhooks")

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_TOKEN"))
  // ChangePlan returns a SubscriptionChangePlanResponse alongside the error.
  _, err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
    UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
      ProductID:            dodopayments.F("pdt_new"),
      Quantity:             dodopayments.F(int64(3)),
      ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),
      OnPaymentFailure:     dodopayments.F(dodopayments.UpdateSubscriptionPlanReqOnPaymentFailurePreventChange), // Optional
    },
  })
  if err != nil { panic(err) }
  fmt.Println("Plan change applied")
}

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_new",
    "quantity": 3,
    "proration_billing_mode": "prorated_immediately",
    "on_payment_failure": "prevent_change"
  }'

Una modifica del piano completata restituisce immediatamente 200 OK — prima che qualsiasi addebito sia stato effettivamente regolato. Il contenuto del body (ChangePlanResponse) dipende dal metodo di riscossione della modifica:

Caso	`payment_id` / `payment_link` / `client_secret` / `expires_on`
Modifica pianificata (`effective_at: next_billing_date`)	Tutti `null` — nulla viene ancora addebitato
`proration_billing_mode: do_not_bill`	Tutti `null` — nulla da addebitare
Addebito immediato ordinario (metodo di pagamento salvato)	Tutti `null`
`collect_via_payment_link: true` (link emesso)	Tutti compilati — riferimenti al checkout per il cliente

Questa risposta conferma che la richiesta è stata accettata, non che un addebito sia andato a buon fine. Per un addebito immediato ordinario, l’esito viene determinato off-session subito dopo la chiamata. Per una richiesta collect_via_payment_link, l’abbonamento rimane sul piano attuale finché il cliente non completa il pagamento.Conferma l’esito tramite webhook (payment.succeeded, payment.failed, subscription.plan_changed) oppure rileggi l’abbonamento con GET /subscriptions/{subscription_id} — per il caso del link di pagamento, consulta Cosa succede mentre il link non è pagato.

Se l’addebito immediato non va a buon fine, l’abbonamento può passare allo stato subscription.on_hold finché il pagamento non viene completato.

Riscossione del pagamento tramite un link di checkout

Per impostazione predefinita, una modifica immediata del piano addebita direttamente il metodo di pagamento salvato dell’abbonamento. Imposta collect_via_payment_link: true per inviare il cliente a una pagina di checkout ospitata, utile quando non esiste un metodo di pagamento salvato o vuoi che il cliente confermi attivamente il nuovo prezzo.

Questa opzione abilita l’interruttore Raccogli i pagamenti delle modifiche del piano tramite link di pagamento in Impostazioni → Abbonamenti, che instrada il flusso di modifica del piano del Customer Portal attraverso il checkout.

Requisiti

collect_via_payment_link: true ha esito positivo solo quando sono soddisfatte tutte le condizioni seguenti; in caso contrario, la richiesta fallisce con 422:

L’azienda ha abilitata la funzionalità allow_plan_change_via_payment_link (Impostazioni → Abbonamenti → Raccogli i pagamenti delle modifiche del piano tramite link di pagamento).
effective_at è immediately (il valore predefinito). Una modifica pianificata (next_billing_date) non richiede mai una pagina di checkout.
La richiesta imposta on_payment_failure: prevent_change. Un apply_change esplicito fallisce con 422.

collect_via_payment_link si applica a qualsiasi modifica immediata che comporti un addebito, inclusi i downgrade, purché siano soddisfatti i requisiti precedenti.

Se la modifica produce un totale pari a zero o un credito, non viene emesso alcun link di pagamento: payment_link e gli altri campi del checkout restituiscono null e la modifica viene applicata immediatamente. Questo non è un 422. Chiama prima Preview Plan Change per verificare l’importo prima di richiedere un link.

Node.js SDK
Python SDK
HTTP

const response = await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  effective_at: 'immediately',
  on_payment_failure: 'prevent_change',
  collect_via_payment_link: true,
});

// Hand response.payment_link to your frontend and send the customer there
console.log(response.payment_link);

response = client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    effective_at="immediately",
    on_payment_failure="prevent_change",
    collect_via_payment_link=True,
)

# Hand response.payment_link to your frontend and send the customer there
print(response.payment_link)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "effective_at": "immediately",
    "on_payment_failure": "prevent_change",
    "collect_via_payment_link": true
  }'

Una richiesta completata restituisce i riferimenti al checkout:

{
  "payment_id": "<payment_id>",
  "payment_link": "https://checkout.dodopayments.com/...",
  "client_secret": "<client_secret>",
  "expires_on": "<expires_on>"
}

Cosa succede mentre il link non è pagato

L’abbonamento rimane sul piano attuale: product_id, recurring_pre_tax_amount e next_billing_date rimangono tutti invariati finché il link non viene pagato.
Un’ulteriore richiesta change-plan viene rifiutata con 409 PendingPlanChangeExists mentre il link è in sospeso. Per sostituire la modifica in sospeso, invia la nuova richiesta con cancel_older_payment_link: true. Consulta Sostituzione di un link di pagamento in sospeso.
Per riprovare dopo un pagamento rifiutato, chiama nuovamente change-plan per ottenere un nuovo link.
Se il link non viene mai pagato, smette di funzionare dopo expires_on; l’abbonamento diventa automaticamente disponibile per accettare una nuova richiesta di modifica del piano poco dopo.
Se esisteva già una modifica pianificata e la sostituisci con cancel_scheduled_change_plan: true, la pianificazione originale rimane attiva mentre il link non è pagato e viene annullata solo dopo il pagamento del link, nella stessa transazione che applica il nuovo piano.

Dopo l’emissione di una modifica immediata tramite link di pagamento, ogni ulteriore richiesta di modifica del piano per quell’abbonamento, inclusa l’anteprima senza effetti collaterali, viene bloccata finché il link non viene risolto. Una richiesta change-plan può sostituire il link impostando cancel_older_payment_link: true. L’anteprima ignora questo campo, quindi rimane bloccata.

Reindirizzamento del cliente dopo il pagamento

Imposta return_url per rimandare il cliente al tuo sito dopo il pagamento del link:

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "return_url": "https://example.com/billing/done"
}

Dopo il checkout, il cliente viene indirizzato a return_url con questi parametri di query:

Parametro	Valore
`subscription_id`	L’abbonamento a cui si applica la modifica del piano.
`payment_id`	Il pagamento della modifica del piano.
`status`	Lo stato del pagamento della modifica del piano, non dell’abbonamento: `active` quando pagato, `failed` quando rifiutato, `pending` mentre è in corso.

Quando il pagamento non va a buon fine, l’abbonamento rimane attivo sul piano attuale. Il nuovo piano può essere applicato poco dopo il reindirizzamento, quando arriva il webhook del pagamento; quindi rileggi l’abbonamento prima di mostrare il nuovo piano. return_url richiede collect_via_payment_link: true. Senza di esso, la richiesta fallisce con 422.

Sostituzione di un link di pagamento in sospeso

Se il cliente abbandona il checkout senza pagare, imposta cancel_older_payment_link: true nella richiesta change-plan successiva. Dodo Payments annulla il link non pagato e la nuova modifica del piano sostituisce quella in sospeso. Il link annullato non accetta più pagamenti, nemmeno in una pagina di checkout già aperta.

{
  "product_id": "pdt_pro",
  "quantity": 1,
  "proration_billing_mode": "prorated_immediately",
  "on_payment_failure": "prevent_change",
  "collect_via_payment_link": true,
  "cancel_older_payment_link": true
}

La richiesta viene convalidata prima dell’annullamento del link, quindi una richiesta non valida mantiene il link del cliente. Il link viene annullato solo se il cliente non ha iniziato a pagare:

Pagamento precedente	Risposta
Non aperto, aperto ma non pagato o rifiutato	`200` con il nuovo link.
Il cliente sta pagando, ad esempio durante 3D Secure	`409` `PLAN_CHANGE_PAYMENT_IN_PROGRESS`. Riprova dopo il completamento o il fallimento del pagamento.
Già pagato	`409` `PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED`. Non riprovare: viene applicata la modifica del piano precedente.
Impossibile annullare il link	`503` `PLAN_CHANGE_LINK_CANCEL_FAILED`. Nulla è cambiato, quindi puoi riprovare.

Ogni richiesta change-plan emette la propria fattura. La modifica del piano sostituita e la relativa fattura vengono annullate. Se non è in sospeso alcuna modifica del piano, cancel_older_payment_link non ha effetto.

Un controllo eseguito dopo la convalida, ad esempio l’importo minimo dell’addebito, può ancora non riuscire dopo l’annullamento del link. L’abbonamento rimane quindi sul piano attuale senza alcun link aperto. Invia nuovamente la richiesta per emettere un nuovo link.

Gestione degli addon

Quando modifichi i piani degli abbonamenti, puoi modificare anche gli addon:

// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing addons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});

Gli addon sono inclusi nel calcolo della prorazione e vengono addebitati in base alla modalità di prorazione selezionata.

Applicazione dei codici sconto

Applica uno o più codici sconto stacked durante la modifica dei piani degli abbonamenti (massimo 20, applicati nell’ordine dell’array):

Node.js SDK
Python SDK
HTTP

// Apply stacked discount codes during plan change
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

# Apply stacked discount codes during plan change
client.subscriptions.change_plan(
    subscription_id="sub_123",
    product_id="pdt_pro",
    quantity=1,
    proration_billing_mode="prorated_immediately",
    discount_codes=["UPGRADE20"]
)

curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pdt_pro",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "discount_codes": ["UPGRADE20"]
  }'

Comportamento degli sconti durante la modifica del piano

Valore di `discount_codes`	Comportamento
Non fornito / `null`	Gli sconti esistenti con `preserve_on_plan_change=true` vengono mantenuti automaticamente, se applicabili al nuovo prodotto.
`[]` (array vuoto)	Tutti gli sconti esistenti vengono rimossi dall’abbonamento.
`["CODE_A", "CODE_B", ...]`	Sostituisce gli sconti esistenti con questo set stacked, convalidato e applicato nell’ordine dell’array.

Il campo singolare discount_code di questo endpoint è deprecato, ma continua a funzionare per la compatibilità con le versioni precedenti; le integrazioni esistenti non devono essere modificate immediatamente. Non può essere combinato con discount_codes nella stessa richiesta. Esegui la migrazione al formato array quando è opportuno.

Usa la Preview Plan Change API con discount_codes per mostrare ai clienti esattamente quanto risparmieranno prima di confermare la modifica del piano.

Modalità di prorazione

Scegli come addebitare il cliente quando modifichi il piano:

`prorated_immediately`

Accredita la parte inutilizzata del ciclo attuale — piano base, quantità e addon — calcolata proporzionalmente al tempo rimanente
Quindi addebita un ciclo completo del nuovo piano, della nuova quantità e dei nuovi addon. L’addebito non viene mai calcolato proporzionalmente
Addebito immediato netto = (nuovo ciclo completo) − (frazione rimanente × vecchio ciclo completo)
Se il credito supera l’addebito del nuovo ciclo (caso comune nei downgrade), la differenza viene mantenuta come credito associato all’abbonamento per i rinnovi futuri
Se l’abbonamento è in prova, addebita immediatamente e passa ora al nuovo piano

`full_immediately`

Addebita immediatamente l’intero importo del nuovo piano
Ignora il tempo rimanente del vecchio piano: nessun credito per il ciclo attuale

I crediti creati da prorated_immediately e dai downgrade che usano difference_immediately sono associati all’abbonamento e distinti dalle disponibilità di Credit-Based Billing. Vengono applicati automaticamente ai rinnovi futuri dello stesso abbonamento e non sono trasferibili tra abbonamenti.

`difference_immediately`

Upgrade: addebita immediatamente la differenza di prezzo tra il vecchio e il nuovo piano
Downgrade: aggiunge il valore rimanente come credito interno all’abbonamento e lo applica automaticamente ai rinnovi

`do_not_bill`

Non vengono calcolati addebiti o crediti
Il cliente passa immediatamente al nuovo piano senza alcun adeguamento di fatturazione
Il ciclo di fatturazione rimane invariato
Ideale per migrazioni per cortesia, passaggi a piani gratuiti o per assorbire differenze di costo

Funzionalità	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Addebito per upgrade	Ciclo nuovo completo, meno il credito per il tempo inutilizzato	Differenza di prezzo completa tra i piani	Prezzo completo del nuovo piano	Nessun addebito
Credito per downgrade	Credito per il tempo inutilizzato, meno un ciclo nuovo completo	Differenza di prezzo completa come credito	Nessun credito	Nessun credito
Ciclo di fatturazione	Si reimposta a oggi	Si reimposta a oggi	Si reimposta a oggi	Invariato
Comportamento in prova	Termina la prova, addebita immediatamente	Termina la prova, addebita immediatamente	Termina la prova, addebita l’intero importo	Mantiene la data di fine prova, nessun addebito
Ideale per	Accreditare il tempo inutilizzato	Calcolo semplice di upgrade/downgrade	Reimpostare i cicli di fatturazione	Migrazioni gratuite o passaggi per cortesia
Complessità	Media (calcolo dei giorni)	Bassa (sottrazione semplice)	Bassa (addebito completo)	Nessuna

Scenari di esempio

Usa sempre questi numeri canonici:

Piano attuale: Basic a $30/mese
Destinazione dell’upgrade: Pro a $80/mese
Destinazione del downgrade (da Pro): Starter a $20/mese
Ciclo di fatturazione: 30 giorni, iniziato il 1 gennaio
La modifica del piano avviene il 16 gennaio (15 giorni rimanenti, 15 giorni utilizzati)

Upgrade: Basic ($30) → Pro ($80) with prorated_immediately

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $80.00 (never prorated)

Step 3: Calculate immediate charge
  Charge = Full new cycle − Credit
  Charge = $80.00 − $15.00 = $65.00

→ Customer pays $65.00 now
→ Customer starts a full month of Pro today
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with prorated_immediately

Step 1: Credit the unused time on the current plan
  Unused days = 15 out of 30 days
  Credit = $80 × (15/30) = $40.00

Step 2: Charge a full cycle at the new plan
  New plan cost = $20.00 (never prorated)

Step 3: Net the two
  Net = $20.00 − $40.00 = −$20.00

→ No charge — $20.00 credit added to subscription
→ Billing cycle resets to today (January 16)
→ Credit auto-applies to future renewals
→ Next renewal (Feb 15): $20.00 − $20.00 (from credit) = $0.00 (credit exhausted)
→ Following renewal (Mar 15): $20.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_starter',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with difference_immediately

Immediate charge = New plan price − Old plan price
                 = $80 − $30
                 = $50.00

→ Customer pays $50.00 now (regardless of cycle position)
→ Billing cycle resets to today (January 16)
→ Next renewal (Feb 15): $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Downgrade: Pro ($80) → Starter ($20) with difference_immediately

Credit = Old plan price − New plan price
       = $80 − $20
       = $60.00

→ No charge — $60.00 credit added to subscription
→ Credit auto-applies to future renewals
→ Next renewal: $20.00 − $20.00 (from credit) = $0.00
→ Following renewal: $20.00 − $20.00 (from credit) = $0.00
→ Third renewal: $20.00 − $20.00 (from remaining credit) = $0.00

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_starter',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
})

Upgrade: Basic ($30) → Pro ($80) with full_immediately

Immediate charge = Full new plan price = $80.00

→ Customer pays $80.00 now
→ No credit for unused time on old plan
→ Billing cycle resets to today (January 16)
→ Next renewal: February 16 at $80.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
})

Mid-cycle upgrade with add-ons using prorated_immediately

Current: Basic plan ($30/month), no add-ons
New: Pro plan ($80/month) + Extra Seats add-on ($10/seat × 3 seats = $30/month)
Change on day 16 of 30 (15 days remaining)

Step 1: Credit the unused time on the current plan
  Credit = $30 × (15/30) = $15.00

Step 2: Charge a full cycle at the new plan + add-ons
  New plan = $80.00
  Add-ons  = $30.00
  Total new = $110.00 (never prorated)

Step 3: Immediate charge
  Charge = $110.00 − $15.00 = $95.00

→ Customer pays $95.00 now
→ Next renewal: $80.00 + $30.00 = $110.00/month

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [
    { addon_id: 'addon_seats', quantity: 3 }
  ]
})

Come ogni modalità elabora la fatturazione

Scegli prorated_immediately per accreditare il tempo inutilizzato del vecchio piano addebitando un ciclo completo del nuovo; scegli full_immediately per riavviare la fatturazione; usa difference_immediately per upgrade semplici e accrediti automatici sui downgrade; oppure usa do_not_bill per cambiare piano senza alcun adeguamento della fatturazione.

Gestione dei pagamenti non riusciti

Controlla cosa succede quando il pagamento di una modifica del piano non va a buon fine usando il parametro on_payment_failure.

Modalità di mancato pagamento

prevent_change (Recommended for critical upgrades)
apply_change (Default)

Comportamento: Mantieni l’abbonamento sul piano attuale finché il pagamento non va a buon fine.

La modifica del piano viene contrassegnata come “in sospeso”
Il cliente mantiene l’accesso al piano attuale
L’abbonamento passa allo stato active solo dopo il pagamento completato
Utile quando vuoi assicurarti del pagamento prima di concedere funzionalità avanzate

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

Comportamento: Applica immediatamente la modifica del piano indipendentemente dall’esito del pagamento.

La modifica del piano viene applicata anche se il pagamento non va a buon fine
Il cliente ottiene immediatamente l’accesso al nuovo piano
Se il pagamento non va a buon fine, l’abbonamento può passare allo stato on_hold
Indicato per upgrade non critici o quando ti fidi del cliente

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'apply_change' // This is the default
});

Se non specificato, il parametro on_payment_failure usa l’impostazione predefinita a livello aziendale configurata nel dashboard.

Quando usare ciascuna modalità

Scenario	Modalità consigliata	Motivo
Upgrade a funzionalità premium	`prevent_change`	Assicurare il pagamento prima di concedere l’accesso
Aumento della quantità (più posti)	`prevent_change`	Impedire l’utilizzo senza pagamento
Downgrade dei piani	`apply_change`	Il cliente sta riducendo la spesa
Clienti enterprise affidabili	`apply_change`	Rischio minore di mancato pagamento
Conversione da prova a pagamento	`prevent_change`	Momento di pagamento critico

Impostazioni predefinite aziendali e di riscossione

Imposta il comportamento predefinito per upgrade e downgrade a livello aziendale in Impostazioni → Abbonamenti. Queste impostazioni si applicano a tutte le modifiche del piano dal customer portal e possono essere sovrascritte per ogni raccolta di prodotti. Esistono impostazioni predefinite separate per upgrade e downgrade:

Impostazione	Campo (upgrade / downgrade)	Predefinito (upgrade)	Predefinito (downgrade)
Quando inizia il nuovo piano	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
Come viene addebitato il cliente	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
Se il pagamento del cliente non va a buon fine	`on_payment_failure`	`apply_change`	`apply_change`

Configura le impostazioni predefinite aziendali in Impostazioni → Abbonamenti e le sovrascritture per raccolta in ogni raccolta di prodotti. Ogni campo della raccolta è indipendente: lascialo non impostato per ereditare il valore predefinito aziendale oppure imposta un valore per sovrascriverlo.

Ordine di risoluzione

Per una determinata modifica del piano, ogni impostazione viene risolta nel seguente ordine:

per-request value (Change Plan API) → collection field (if set) → business field → system default

Un valore passato esplicitamente all’API Change Plan ha sempre la precedenza. Le impostazioni predefinite aziendali e della raccolta hanno effetto solo quando non viene fornito alcun valore esplicito, come avviene per tutte le modifiche del piano avviate dal customer portal.

Una configurazione comune: mantieni gli upgrade su immediately + difference_immediately, così i clienti pagano la differenza e ottengono subito l’accesso, e mantieni i downgrade su next_billing_date, così i clienti conservano il piano attuale fino alla fine del ciclo.

Gestione dei webhook

Monitora lo stato dell’abbonamento tramite webhook per confermare le modifiche del piano e i pagamenti.

Tipi di evento da gestire

subscription.active: abbonamento attivato
subscription.plan_changed: piano dell’abbonamento modificato (upgrade/downgrade/modifiche degli addon)
subscription.on_hold: addebito non riuscito, rinnovi interrotti
subscription.renewed: rinnovo completato
payment.succeeded: pagamento della modifica del piano o del rinnovo completato
payment.failed: pagamento non riuscito

Basa la logica aziendale sugli eventi dell’abbonamento e usa gli eventi di pagamento per la conferma e la riconciliazione.

Verifica delle firme e gestione degli intent

Next.js Route Handler
Express.js

import { NextRequest, NextResponse } from 'next/server';

export async function POST(req) {
  const webhookId = req.headers.get('webhook-id');
  const webhookSignature = req.headers.get('webhook-signature');
  const webhookTimestamp = req.headers.get('webhook-timestamp');
  const secret = process.env.DODO_PAYMENTS_WEBHOOK_KEY;

  const payload = await req.text();
  // verifySignature is a placeholder – in production, use a Standard Webhooks library
  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });

  switch (event.type) {
    case 'subscription.active':
      // mark subscription active in your DB
      break;
    case 'subscription.plan_changed':
      // refresh entitlements and reflect the new plan in your UI
      break;
    case 'subscription.on_hold':
      // notify user to update payment method
      break;
    case 'subscription.renewed':
      // extend access window
      break;
    case 'payment.succeeded':
      // reconcile payment for plan change
      break;
    case 'payment.failed':
      // log and alert
      break;
    default:
      // ignore unknown events
      break;
  }

  return NextResponse.json({ received: true });
}

import express from 'express';

const app = express();
app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  const webhookId = req.header('webhook-id');
  const webhookSignature = req.header('webhook-signature');
  const webhookTimestamp = req.header('webhook-timestamp');
  const secret = process.env.DODO_PAYMENTS_WEBHOOK_KEY;
  const payload = req.body.toString('utf8');

  const { valid, event } = await verifySignature(
    payload,
    { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
    secret
  );
  if (!valid) return res.status(400).send('Invalid signature');

  // handle events like above
  res.json({ received: true });
});

app.listen(3000);

Per gli schemi dettagliati dei payload, consulta i payload dei webhook degli abbonamenti e i payload dei webhook dei pagamenti.

Best practice

Strategia per le modifiche del piano

Testa accuratamente: testa sempre le modifiche del piano in modalità test prima della produzione
Scegli con attenzione la prorazione: seleziona la modalità di prorazione in linea con il tuo modello aziendale
Gestisci elegantemente gli errori: implementa una gestione degli errori e una logica di retry adeguate
Monitora i tassi di successo: monitora i tassi di successo/fallimento delle modifiche del piano e analizza i problemi

Implementazione dei webhook

Verifica le firme: convalida sempre le firme dei webhook per garantirne l’autenticità
Implementa l’idempotenza: gestisci correttamente gli eventi webhook duplicati
Elabora in modo asincrono: non bloccare le risposte dei webhook con operazioni pesanti
Registra tutto: mantieni log dettagliati per il debug e gli audit

Esperienza utente

Comunica chiaramente: informa i clienti sulle modifiche di fatturazione e sulle tempistiche
Fornisci conferme: invia email di conferma per le modifiche del piano completate
Gestisci i casi limite: considera periodi di prova, prorazioni e pagamenti non riusciti
Aggiorna subito l’interfaccia: rifletti le modifiche del piano nell’interfaccia della tua applicazione

Problemi comuni e soluzioni

Risolvi i problemi tipici riscontrati durante le modifiche dei piani degli abbonamenti:

Charge created but subscription not updated

Sintomi: la chiamata API ha esito positivo, ma l’abbonamento rimane sul vecchio pianoCause comuni:

L’elaborazione del webhook non è riuscita o è stata ritardata
Lo stato dell’applicazione non è stato aggiornato dopo la ricezione dei webhook
Problemi con la transazione del database durante l’aggiornamento dello stato

Soluzioni:

Implementa la gestione dei webhook con logica di retry
Usa operazioni idempotenti per gli aggiornamenti dello stato
Aggiungi il monitoraggio per rilevare e segnalare gli eventi webhook mancanti
Verifica che l’endpoint webhook sia accessibile e risponda correttamente

Credits not applied after downgrade

Sintomi: il cliente effettua un downgrade ma non visualizza il saldo dei creditiCause comuni:

Aspettative sulla modalità di prorazione: i downgrade accreditano la differenza completa del prezzo del piano con difference_immediately, mentre prorated_immediately accredita il tempo inutilizzato del vecchio ciclo e poi addebita un ciclo completo al nuovo piano; quindi un saldo crediti rimane solo quando tale credito supera il prezzo del nuovo piano
I crediti sono specifici dell’abbonamento e non vengono trasferiti tra abbonamenti
Il saldo dei crediti non è visibile nel dashboard del cliente

Soluzioni:

Usa difference_immediately per i downgrade quando vuoi crediti automatici
Spiega ai clienti che i crediti vengono applicati ai rinnovi futuri dello stesso abbonamento
Implementa il customer portal per mostrare i saldi dei crediti
Controlla l’anteprima della fattura successiva per visualizzare i crediti applicati

Webhook signature verification fails

Sintomi: gli eventi webhook vengono rifiutati a causa di una firma non validaCause comuni:

Chiave segreta del webhook errata
Body della richiesta originale modificato prima della verifica della firma
Algoritmo di verifica della firma errato

Soluzioni:

Verifica di usare il corretto DODO_PAYMENTS_WEBHOOK_KEY dal dashboard
Leggi il body originale della richiesta prima di qualsiasi middleware di parsing JSON
Usa la libreria standard di verifica dei webhook per la tua piattaforma
Testa la verifica della firma dei webhook nell’ambiente di sviluppo

Plan change fails with 422 error

Sintomi: l’API restituisce l’errore 422 Unprocessable EntityCause comuni:

ID abbonamento o ID prodotto non valido
Abbonamento non nello stato attivo
Parametri obbligatori mancanti
Prodotto non disponibile per le modifiche del piano

Soluzioni:

Verifica che l’abbonamento esista e sia attivo
Controlla che l’ID prodotto sia valido e disponibile
Assicurati che siano forniti tutti i parametri obbligatori
Consulta la documentazione API per i requisiti dei parametri

Immediate charge fails during plan change

Sintomi: la modifica del piano è stata avviata, ma l’addebito immediato non va a buon fineCause comuni:

Fondi insufficienti sul metodo di pagamento del cliente
Metodo di pagamento scaduto o non valido
La banca ha rifiutato la transazione
Il rilevamento delle frodi ha bloccato l’addebito

Soluzioni:

Gestisci correttamente gli eventi webhook payment.failed
Informa il cliente che deve aggiornare il metodo di pagamento
Implementa la logica di retry per gli errori temporanei
Valuta la possibilità di consentire modifiche del piano con addebiti immediati non riusciti

Subscription on hold after plan change

Sintomi: l’addebito della modifica del piano non va a buon fine e l’abbonamento passa allo stato on_holdCosa succede: Quando l’addebito della modifica del piano non va a buon fine, l’abbonamento viene automaticamente impostato sullo stato on_hold. L’abbonamento non verrà rinnovato automaticamente finché il metodo di pagamento non viene aggiornato.Soluzione: aggiorna il metodo di pagamento per riattivare l’abbonamentoPer riattivare un abbonamento dallo stato on_hold dopo una modifica del piano non riuscita:

Aggiorna il metodo di pagamento usando l’API Update Payment Method
Creazione automatica dell’addebito: l’API crea automaticamente un addebito per gli importi ancora dovuti
Generazione della fattura: viene generata una fattura per l’addebito
Elaborazione del pagamento: il pagamento viene elaborato usando il nuovo metodo di pagamento
Riattivazione: dopo il pagamento completato, l’abbonamento viene riattivato allo stato active

// Reactivate subscription from on_hold after failed plan change
async function reactivateAfterFailedPlanChange(subscriptionId) {
  // Update payment method - automatically creates charge for remaining dues
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    payment_method: { type: 'new', return_url: 'https://example.com/return' }
  });
  
  if (response.payment_id) {
    console.log('Charge created for remaining dues:', response.payment_id);
    console.log('Payment link:', response.payment_link);
    
    // Redirect customer to payment_link to complete payment
    // Monitor webhooks for:
    // 1. payment.succeeded - charge succeeded
    // 2. subscription.active - subscription reactivated
  }
  
  return response;
}

// Or use existing payment method if available
async function reactivateWithExistingPaymentMethod(subscriptionId, paymentMethodId) {
  const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
    payment_method: { type: 'existing', payment_method_id: paymentMethodId }
  });
  
  // Monitor webhooks for payment.succeeded and subscription.active
  return response;
}

# Reactivate subscription from on_hold after failed plan change
def reactivate_after_failed_plan_change(subscription_id):
    # Update payment method - automatically creates charge for remaining dues
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "new", "return_url": "https://example.com/return"},
    )
    
    if response.payment_id:
        print("Charge created for remaining dues:", response.payment_id)
        print("Payment link:", response.payment_link)
        
        # Redirect customer to payment_link to complete payment
        # Monitor webhooks for:
        # 1. payment.succeeded - charge succeeded
        # 2. subscription.active - subscription reactivated
    
    return response

# Or use existing payment method if available
def reactivate_with_existing_payment_method(subscription_id, payment_method_id):
    response = client.subscriptions.update_payment_method(
        subscription_id=subscription_id,
        payment_method={"type": "existing", "payment_method_id": payment_method_id},
    )
    
    # Monitor webhooks for payment.succeeded and subscription.active
    return response

Eventi webhook da monitorare:

subscription.on_hold: abbonamento sospeso (ricevuto quando l’addebito della modifica del piano non va a buon fine)
payment.succeeded: pagamento degli importi ancora dovuti completato (dopo l’aggiornamento del metodo di pagamento)
subscription.active: abbonamento riattivato dopo il pagamento completato

Best practice:

Informa immediatamente i clienti quando l’addebito della modifica del piano non va a buon fine
Fornisci istruzioni chiare su come aggiornare il metodo di pagamento
Monitora gli eventi webhook per seguire lo stato della riattivazione
Valuta l’implementazione di una logica di retry automatica per i pagamenti temporaneamente non riusciti

Update Payment Method API Reference

Visualizza la documentazione API completa per aggiornare i metodi di pagamento e riattivare gli abbonamenti.

Test dell’implementazione

Testa accuratamente l’implementazione della modifica del piano dell’abbonamento:

Set up test environment

Usa chiavi API di test e prodotti di test
Crea abbonamenti di test con diversi tipi di piano
Configura un endpoint webhook di test
Configura il monitoraggio e la registrazione dei log

Test different proration modes

Testa prorated_immediately con diverse posizioni nel ciclo di fatturazione
Testa difference_immediately per upgrade e downgrade
Testa full_immediately per reimpostare i cicli di fatturazione
Testa do_not_bill per passaggi di piano senza addebiti o crediti
Verifica che i calcoli dei crediti siano corretti

Test webhook handling

Verifica che vengano ricevuti tutti gli eventi webhook pertinenti
Testa la verifica delle firme dei webhook
Gestisci correttamente gli eventi webhook duplicati
Testa gli scenari di errore nell’elaborazione dei webhook

Test error scenarios

Testa con ID abbonamento non validi
Testa con metodi di pagamento scaduti
Testa errori di rete e timeout
Testa con fondi insufficienti

Monitor in production

Configura avvisi per le modifiche del piano non riuscite
Monitora i tempi di elaborazione dei webhook
Monitora i tassi di successo delle modifiche del piano
Esamina i ticket dell’assistenza clienti relativi ai problemi delle modifiche del piano

Gestione degli errori

Gestisci correttamente gli errori API comuni nella tua implementazione:

Codici di stato HTTP

200 OK

La richiesta di modifica del piano è stata elaborata correttamente. Il body della risposta è un ChangePlanResponse con payment_id, payment_link, client_secret e expires_on. Tutti e quattro sono nullable, quindi il body viene serializzato come {} per una modifica ordinaria off-session; vengono valorizzati per una richiesta collect_via_payment_link completata, che restituisce i riferimenti al checkout. Consulta Riscossione del pagamento tramite un link di checkout. Se on_payment_failure=prevent_change, la modifica del piano rimane in sospeso finché il pagamento non va a buon fine.

400 Bad Request

Parametri della richiesta non validi. Verifica che tutti i campi obbligatori siano forniti e formattati correttamente.

401 Unauthorized

Chiave API non valida o mancante. Verifica che il tuo DODO_PAYMENTS_API_KEY sia corretto e disponga delle autorizzazioni appropriate.

409 Conflict

Esiste già una modifica del piano in sospeso per questo abbonamento (PendingPlanChangeExists). Per una modifica pianificata, annullala con DELETE /subscriptions/{subscription_id}/change-plan/scheduled prima di inviarne una nuova. Per una modifica tramite link di pagamento in sospeso, invia la nuova richiesta con cancel_older_payment_link: true per sostituirla. Consulta Sostituzione di un link di pagamento in sospeso.Con cancel_older_payment_link: true, un 409 significa che il cliente sta pagando ora il link precedente (PLAN_CHANGE_PAYMENT_IN_PROGRESS) o lo ha già pagato (PLAN_CHANGE_PAYMENT_ALREADY_COMPLETED).

503 Service Unavailable

Con cancel_older_payment_link: true, il link di pagamento precedente non può essere annullato (PLAN_CHANGE_LINK_CANCEL_FAILED). Nulla è cambiato, quindi puoi riprovare la richiesta.

422 Unprocessable Entity

L’abbonamento è inattivo o on-demand, oppure la richiesta non è idonea per collect_via_payment_link: l’azienda non ha abilitato la funzionalità, effective_at non è immediately oppure on_payment_failure non è prevent_change. Consulta Requisiti. Un ID abbonamento inesistente o non appartenente al tuo account restituisce 404 con il codice NOT_FOUND.

500 Internal Server Error

Si è verificato un errore del server. Riprova la richiesta dopo una breve attesa.

Formato della risposta di errore

Gli errori restituiscono un body JSON con un code e un message leggibile dall’utente:

{
  "code": "INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED",
  "message": "Changing plans is not supported for inactive subscriptions"
}

Consulta Codici di errore per l’elenco completo.

Passaggi successivi

Consulta l’API Change Plan
Esplora Credit-Based Billing
Implementa avvisi per subscription.on_hold
Consulta la Guida all’integrazione dei webhook

Change Plan API

Plan Change Preview

Integration Guide

​What Is a Subscription Upgrade or Downgrade?

​When to Use Plan Changes

​Plan Change Flow

​Prerequisites

​Step-by-Step Implementation Guide

​Anteprima delle modifiche del piano

​API Change Plan

​Esempi rapidi

​Riscossione del pagamento tramite un link di checkout

​Requisiti

​Cosa succede mentre il link non è pagato

​Reindirizzamento del cliente dopo il pagamento

​Sostituzione di un link di pagamento in sospeso

​Gestione degli addon

​Applicazione dei codici sconto

​Comportamento degli sconti durante la modifica del piano

​Modalità di prorazione

​prorated_immediately

​full_immediately

​difference_immediately

​do_not_bill

​Scenari di esempio

​Come ogni modalità elabora la fatturazione

​Gestione dei pagamenti non riusciti

​Modalità di mancato pagamento

​Quando usare ciascuna modalità

​Impostazioni predefinite aziendali e di riscossione

​Ordine di risoluzione

​Gestione dei webhook

​Tipi di evento da gestire

​Verifica delle firme e gestione degli intent

​Best practice

​Strategia per le modifiche del piano

​Implementazione dei webhook

​Esperienza utente

​Problemi comuni e soluzioni

Update Payment Method API Reference

​Test dell’implementazione

​Gestione degli errori

​Codici di stato HTTP

​Formato della risposta di errore

​Passaggi successivi

What Is a Subscription Upgrade or Downgrade?

When to Use Plan Changes

Plan Change Flow

Prerequisites

Step-by-Step Implementation Guide

Anteprima delle modifiche del piano

API Change Plan

Esempi rapidi

Riscossione del pagamento tramite un link di checkout

Requisiti

Cosa succede mentre il link non è pagato

Reindirizzamento del cliente dopo il pagamento

Sostituzione di un link di pagamento in sospeso

Gestione degli addon

Applicazione dei codici sconto

Comportamento degli sconti durante la modifica del piano

Modalità di prorazione

`prorated_immediately`

`full_immediately`

`difference_immediately`

`do_not_bill`

Scenari di esempio

Come ogni modalità elabora la fatturazione

Gestione dei pagamenti non riusciti

Modalità di mancato pagamento

Quando usare ciascuna modalità

Impostazioni predefinite aziendali e di riscossione

Ordine di risoluzione

Gestione dei webhook

Tipi di evento da gestire

Verifica delle firme e gestione degli intent

Best practice

Strategia per le modifiche del piano

Implementazione dei webhook

Esperienza utente

Problemi comuni e soluzioni

Test dell’implementazione

Gestione degli errori

Codici di stato HTTP

Formato della risposta di errore

Passaggi successivi