Abbonamenti - Dodo Payments Documentation

Gli abbonamenti ti consentono di vendere accesso continuativo con rinnovi automatici. Usa cicli di fatturazione flessibili, periodi di prova gratuiti, modifiche dei piani e add-on per personalizzare i prezzi per ogni cliente.

Upgrade & Downgrade

Gestisci le modifiche dei piani con la proratazione e gli aggiornamenti delle quantità.

On‑Demand Subscriptions

Autorizza ora un mandato e addebita in seguito importi personalizzati.

Customer Portal

Consenti ai clienti di gestire piani, fatturazione e cancellazioni.

Subscription Webhooks

Reagisci agli eventi del ciclo di vita, come creazione, rinnovo e cancellazione.

Cosa sono gli abbonamenti?

Gli abbonamenti sono prodotti ricorrenti che i clienti acquistano secondo una determinata pianificazione. Sono ideali per:

Licenze SaaS: app, API o accesso alla piattaforma
Membership: community, programmi o club
Contenuti digitali: corsi, media o contenuti premium
Piani di assistenza: SLA, pacchetti di successo o manutenzione

Vantaggi principali

Ricavi prevedibili: fatturazione ricorrente con rinnovi automatici
Cicli flessibili: intervalli mensili, annuali o personalizzati e periodi di prova
Flessibilità dei piani: proratazione per upgrade e downgrade
Add-on e postazioni: aggiungi upgrade opzionali e quantificabili
Checkout fluido: checkout ospitato e Customer Portal
Developer-first: API chiare per creazione, modifiche e monitoraggio dell’utilizzo

Creazione degli abbonamenti

Crea i prodotti in abbonamento nella dashboard di Dodo Payments, quindi vendili tramite checkout o la tua API. Separare i prodotti dagli abbonamenti attivi ti consente di gestire le versioni dei prezzi, aggiungere add-on e monitorare le prestazioni in modo indipendente.

Creazione di un prodotto in abbonamento

Configura i campi nella dashboard per definire come il tuo abbonamento viene venduto, rinnovato e fatturato. Le sezioni seguenti corrispondono direttamente a ciò che vedi nel modulo di creazione.

Dettagli del prodotto

Nome del prodotto (obbligatorio): il nome visualizzato nel checkout, nel Customer Portal e nelle fatture.
Descrizione del prodotto (obbligatorio): una descrizione chiara del valore offerto, visualizzata nel checkout e nelle fatture.
Immagine del prodotto (obbligatorio): PNG/JPG/WebP fino a 3 MB. Utilizzata nel checkout e nelle fatture.
Brand: associa il prodotto a un brand specifico per personalizzare tema ed email.
Categoria fiscale (obbligatorio): scegli la categoria (ad esempio, SaaS) per determinare le regole fiscali.

Scegli la categoria fiscale più accurata per garantire una corretta riscossione delle imposte per ogni area geografica.

Prezzi

Tipo di prezzo: scegli Subscription (questa guida). Le alternative sono Pagamento singolo e Fatturazione basata sull’utilizzo.
Prezzo (obbligatorio): prezzo ricorrente di base con valuta. Il prezzo deve essere almeno $1 (o l’equivalente nella valuta scelta). Gli importi inferiori a questo minimo non sono supportati e la subscription non funzionerà.
Sconto applicabile (%): percentuale di sconto facoltativa applicata al prezzo di base; viene mostrata nel checkout e nelle fatture.
Ripeti il pagamento ogni (obbligatorio): intervallo per i rinnovi, ad esempio ogni 1 mese. Seleziona la frequenza (mesi o anni) e la quantità.
Periodo della subscription (obbligatorio): durata totale per cui la subscription rimane attiva (ad esempio 10 anni). Al termine di questo periodo, i rinnovi si interrompono se non vengono estesi.
Giorni del periodo di prova (obbligatorio): imposta la durata della prova in giorni. Usa 0 per disabilitare le prove. Il primo addebito avviene automaticamente al termine della prova.
Importo della prova: addebito anticipato facoltativo per una prova a pagamento. Lascialo non impostato per una prova gratuita. Consulta Prove a pagamento.
Seleziona add-on: associa fino a 10 add-on che i clienti possono acquistare insieme al piano di base.

La modifica dei prezzi di un prodotto attivo influisce sui nuovi acquisti. Gli abbonamenti esistenti seguono le impostazioni di modifica del piano e di proratazione.

Gli add-on sono ideali per extra quantificabili, come postazioni o spazio di archiviazione. Puoi controllare le quantità consentite e il comportamento della proratazione quando i clienti li modificano.

Impostazioni avanzate

Prezzi con imposte incluse: visualizza i prezzi comprensivi delle imposte applicabili. Il calcolo fiscale finale varia comunque in base alla posizione del cliente.
Genera chiavi di licenza: emetti una chiave univoca per ogni cliente dopo l’acquisto. Consulta la guida License Keys.
Distribuzione dei prodotti digitali: distribuisci automaticamente file o contenuti dopo l’acquisto. Scopri di più in Digital Product Delivery.
Metadati: aggiungi coppie chiave-valore personalizzate per tag interni o integrazioni client. Consulta Metadata.

Usa i metadati per memorizzare gli identificatori del tuo sistema (ad esempio, accountId), così potrai riconciliare in seguito eventi e fatture.

Periodi di prova degli abbonamenti

Le prove consentono ai clienti di valutare una subscription prima di pagare il prezzo ricorrente completo. Una prova può essere gratuita, senza alcun addebito fino alla sua scadenza, oppure a pagamento, con un importo ridotto addebitato in anticipo. In entrambi i casi, il prezzo completo entra in vigore al primo rinnovo successivo alla fine della prova.

Configurazione dei periodi di prova

Imposta Giorni del periodo di prova nella sezione dei prezzi del prodotto (usa 0 per disabilitare). Puoi sostituire questo valore durante la creazione degli abbonamenti:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

Il valore trial_period_days deve essere compreso tra 0 e 10.000 giorni.

Prove a pagamento

Le prove non devono necessariamente essere gratuite. Imposta un Importo della prova sul prezzo ricorrente di un prodotto in subscription per addebitare una tariffa anticipata ridotta durante il periodo di prova. Il prezzo ricorrente completo subentra al primo rinnovo.

Modulo di prezzo della subscription con durata della prova e importo facoltativo per una prova a pagamento

Le prove a pagamento vengono configurate sul prezzo del prodotto, non per subscription o sessione di checkout:

Campo	Tipo	Descrizione
`trial_amount`	integer	Importo addebitato oggi per la prova, nelle unità minori della valuta del prezzo (ad esempio `500` per $5.00). Richiede `trial_period_days > 0`. Ometti il valore o impostalo su `null` per una prova gratuita.
`trial_apply_discounts`	boolean	Indica se i codici sconto del checkout riducono l’addebito della prova. Il valore predefinito è `false`, quindi l’importo della prova viene addebitato per intero anche quando lo sconto si applica al prezzo ricorrente.

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

Anche le prove a pagamento passano dal checkout. L’importo della prova è soggetto a imposte, viene mostrato nei calcoli della sessione di checkout e nei prezzi dei payment link, e il markup di Adaptive Currency viene applicato per valuta. L’endpoint di anteprima restituisce trial_amount e trial_period_days, così puoi mostrare l’importo dovuto oggi prima della creazione della subscription.

Le prove gratuite non cambiano. Lasciare non impostato Importo della prova mantiene il comportamento esistente: il primo addebito è 0 e il prezzo completo viene addebitato al termine della prova.

Prevenire l’uso improprio delle prove

Previeni l’uso improprio delle prove impedisce ai clienti di richiedere ripetutamente prove per la stessa attività. Quando è abilitata, un cliente che ha già usufruito di una prova viene automaticamente convertito in un acquisto a pagamento senza prova, invece di ricevere una nuova prova.

Interruttore Previeni l'uso improprio delle prove nella scheda delle impostazioni delle Subscriptions

Abilitalo dalla scheda Subscriptions in Impostazioni. Dopo l’abilitazione:

I clienti vengono associati tramite email normalizzata, rimuovendo gli alias con il simbolo +; quindi user+trial@example.com e user@example.com vengono considerati la stessa persona.
Le registrazioni vengono effettuate all’attivazione della prova, quindi un cliente che annulla nello stesso giorno ha comunque consumato la prova.
I clienti esistenti vengono recuperati in base alle prove storiche tramite email, per riconoscere immediatamente gli utenti che hanno usufruito di prove in passato.

L’impostazione è disattivata per impostazione predefinita. Consulta Impostazioni delle Subscriptions per l’elenco completo dei controlli delle subscription a livello di attività.

Rilevare lo stato della prova

Al momento non esiste un campo diretto per rilevare lo stato della prova. La soluzione alternativa seguente richiede l’interrogazione dei pagamenti, che è inefficiente. Stiamo lavorando a una soluzione più efficiente.

Per determinare se una subscription con prova gratuita è in prova, recupera l’elenco dei pagamenti della subscription. Se esiste esattamente un pagamento con importo 0, la subscription si trova nel periodo di prova:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Questo controllo dell’importo zero funziona solo per le prove gratuite. Per una prova a pagamento, il primo pagamento è uguale all’importo della prova, non a 0. Confronta invece il primo pagamento con trial_amount della subscription, oppure verifica se next_billing_date rientra ancora nel periodo di prova.

Aggiornare il periodo di prova

Estendi la prova aggiornando next_billing_date:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

Non puoi impostare next_billing_date su un momento passato. La data deve essere futura.

Modifiche al piano della subscription

Le modifiche al piano consentono di effettuare upgrade o downgrade delle subscription, modificare le quantità o migrare a prodotti diversi. A seconda della modalità di proratazione selezionata, una modifica può generare un addebito immediato, creare un credito oppure non applicare alcun adeguamento di fatturazione.

Puoi modificare i piani delle subscription e aggiornare la data della fatturazione successiva direttamente dalla dashboard di Dodo Payments. In questo modo puoi adeguare rapidamente le subscription per richieste all’assistenza clienti, upgrade promozionali o migrazioni di piano senza effettuare chiamate API.

Abilita le modifiche al piano self-service: vuoi consentire ai clienti di effettuare autonomamente upgrade o downgrade delle proprie subscription tramite il Customer Portal? Aggiungi i prodotti in subscription a una Product Collection e abilita “Allow Subscription Updates” nelle impostazioni della subscription.

Product Collections

Raggruppa i prodotti correlati in raccolte per abilitare percorsi fluidi di upgrade e downgrade nel Customer Portal.

Modalità di proratazione

Scegli come addebitare i clienti quando modificano il piano:

Confronto rapido delle quattro modalità di proratazione:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Upgrade	Addebito proporzionato per i giorni restanti	Addebito della differenza di prezzo completa	Addebito del prezzo completo del nuovo piano	Nessun addebito — cambio immediato
Downgrade	Credito proporzionato per i giorni restanti	Differenza di prezzo completa come credito	Nessun credito, addebito completo	Nessun credito — cambio immediato
Ciclo di fatturazione	Si reimposta a oggi	Si reimposta a oggi	Si reimposta a oggi	Rimane invariato
Ideale per	Fatturazione equa basata sul tempo	Semplici modifiche di livello	Reimpostazione del ciclo di fatturazione	Migrazioni gratuite o cambi omaggio

`prorated_immediately`

Addebita un importo proporzionato in base al tempo rimanente nel ciclo di fatturazione corrente. Ideale per una fatturazione equa che tenga conto del tempo non utilizzato.

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

`difference_immediately`

Addebita immediatamente la differenza di prezzo (upgrade) oppure aggiunge un credito per i rinnovi futuri (downgrade). Ideale per semplici scenari di upgrade e downgrade.

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

I crediti derivanti dai downgrade che usano difference_immediately sono associati alla subscription e vengono applicati automaticamente ai rinnovi futuri. Sono distinti dai vantaggi di Credit-Based Billing.

Quando un cliente effettua un downgrade con difference_immediately, il valore non utilizzato diventa un credito associato alla subscription, che compensa automaticamente i rinnovi futuri:

`full_immediately`

Addebita immediatamente l’intero importo del nuovo piano, ignorando il tempo rimanente. Ideale per reimpostare i cicli di fatturazione.

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

`do_not_bill`

Passa al nuovo piano senza alcun adeguamento di fatturazione. Nessun addebito di proratazione e nessun credito: il cliente passa semplicemente al nuovo piano. Ideale per migrazioni omaggio, cambi a piani gratuiti o scenari in cui vuoi assorbire la differenza di costo.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

Scenario: un cliente con Basic (

30/mese) effettua l'upgrade a Pro (

80/mese) il giorno 16 di un ciclo di 30 giorni usando prorated_immediately.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Il rinnovo successivo è il 15 febbraio (16 gennaio + 30 giorni): $80.00/mese.

Per esempi di calcolo e casi limite più dettagliati, consulta la Guida completa a upgrade e downgrade.

Example: Downgrade credit calculation

Scenario: un cliente con Pro (

80/mese) effettua il downgrade a Starter (

20/mese) usando difference_immediately.

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

Il credito di $60 viene applicato automaticamente ai rinnovi futuri:

Rinnovo 1: $20 −$ 20 (credito) = ** $0.00** (credito residuo:$ 40)
Rinnovo 2: $20 −$ 20 (credito) = ** $0.00** (credito residuo:$ 20)
Rinnovo 3: $20 −$ 20 (credito) = $0.00 (credito esaurito)
Rinnovo 4: $20.00 (prezzo completo)

Scopri di più sulla gestione dei crediti nella Guida a upgrade e downgrade.

Modificare i piani con gli add-on

Modifica gli add-on quando cambi piano. Gli add-on sono inclusi nei calcoli della proratazione:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

Le modifiche al piano generano addebiti immediati. Gli addebiti non riusciti possono spostare la subscription nello stato on_hold. Tieni traccia delle modifiche tramite gli eventi webhook subscription.plan_changed.

Visualizzare in anteprima le modifiche al piano

Prima di confermare una modifica al piano, visualizza in anteprima l’addebito esatto e la subscription risultante:

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

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

Visualizza in anteprima le modifiche al piano prima di confermarle.

Stati della subscription

Nel corso della sua durata, una subscription attraversa un insieme definito di stati. Questa tabella è il riferimento per ogni stato, per le cause che lo determinano e per le modalità di recupero, quando disponibili.

Stato	Significato	Recuperabile?	Procedura di recupero / passaggio successivo
`pending`	La subscription è in fase di creazione o elaborazione	—	Attendi `subscription.active` (o `subscription.failed`)
`active`	La subscription è attiva e si rinnoverà automaticamente	—	Nessuna azione necessaria
`on_hold`	Un pagamento di rinnovo (o un addebito per modifica del piano) non è riuscito; la subscription è sospesa	Sì	Aggiorna il metodo di pagamento per riattivarla — automaticamente tramite Payment Retries e Dunning, oppure manualmente tramite l’API Update Payment Method
`cancelled`	La subscription è stata annullata e non verrà rinnovata	Solo nuovo acquisto	Il cliente deve avviare una nuova subscription; Dunning può sollecitare un nuovo acquisto
`failed`	La creazione della subscription non è riuscita (il mandato iniziale o il pagamento non è andato a buon fine)	No — terminale	Il cliente deve creare una nuova subscription con un metodo di pagamento funzionante
`expired`	La subscription ha raggiunto la fine del suo periodo	—	Il cliente deve avviare una nuova subscription, se lo desidera

on_hold e failed vengono spesso confusi. on_hold è uno stato recuperabile per una subscription già attiva il cui rinnovo non è riuscito. failed è uno stato terminale che si verifica solo quando non riesce la creazione iniziale della subscription: non può essere riattivato.

Macchina a stati

Stato On Hold

Una subscription entra nello stato on_hold quando:

Un pagamento di rinnovo non riesce (fondi insufficienti, carta scaduta e così via)
Un addebito per modifica del piano non riesce
L’autorizzazione del metodo di pagamento non riesce

Quando una subscription si trova nello stato on_hold, non si rinnoverà automaticamente. Devi aggiornare il metodo di pagamento per riattivarla.

Riattivare una subscription dallo stato On Hold

Per riattivare una subscription dallo stato on_hold, aggiorna il metodo di pagamento. Questa operazione automaticamente:

Crea un addebito per gli importi ancora dovuti
Genera una fattura
Elabora il pagamento usando il nuovo metodo di pagamento
Riattiva la subscription allo stato active dopo il pagamento riuscito

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

Dopo aver aggiornato correttamente il metodo di pagamento per una subscription on_hold, riceverai gli eventi webhook payment.succeeded seguiti da subscription.active.

Eventi webhook per transizione

Ogni transizione genera un webhook, così puoi gestire la logica dei diritti senza eseguire polling:

Transizione	Evento
Subscription attivata	`subscription.active`
Rinnovo riuscito	`subscription.renewed`
Rinnovo non riuscito → sospesa	`subscription.on_hold`
Creazione non riuscita	`subscription.failed`
Piano aggiornato o retrocesso	`subscription.plan_changed`
Annullata	`subscription.cancelled`
Periodo terminato	`subscription.expired`
Qualsiasi modifica ai campi	`subscription.updated`

Subscription Webhook Payloads

Visualizza lo schema completo del payload per gli eventi del ciclo di vita della subscription.

Gestione tramite API

Create subscriptions

Usa POST /subscriptions per creare programmaticamente subscription a partire dai prodotti, con prove e add-on facoltativi.

API Reference

Visualizza l’API per la creazione di una subscription.

Update subscriptions

Usa PATCH /subscriptions/{id} per aggiornare le quantità, annullare alla data della fatturazione successiva o modificare i metadati.

API Reference

Scopri come aggiornare i dettagli della subscription.

Change plans (proration)

Modifica il prodotto attivo e le quantità con i controlli di proratazione.

API Reference

Esamina le opzioni di modifica del piano.

On‑demand charges

Per le subscription on-demand, addebita importi specifici su richiesta.

API Reference

Addebita una subscription on-demand.

List and retrieve

Usa GET /subscriptions per elencare tutte le subscription e GET /subscriptions/{id} per recuperarne una.

API Reference

Consulta le API per l’elenco e il recupero.

Usage history

Recupera l’utilizzo registrato per i modelli di prezzo basati sull’utilizzo o ibridi.

API Reference

Consulta l’API della cronologia di utilizzo.

Update payment method

Aggiorna il metodo di pagamento per una subscription. Per le subscription attive, questa operazione aggiorna il metodo di pagamento per i rinnovi futuri. Per le subscription nello stato on_hold, riattiva la subscription creando un addebito per gli importi ancora dovuti.Quando generi un nuovo link per il metodo di pagamento (il tipo di richiesta New), puoi passare allowed_payment_method_types per limitare i metodi di pagamento visualizzati dal cliente in quella pagina. I clienti non vedranno mai un metodo che non è incluso nell’elenco, anche se includere un metodo non ne garantisce la visualizzazione (la disponibilità dipende comunque da fattori quali la posizione del cliente e le impostazioni della tua attività).

API Reference

Scopri come aggiornare i metodi di pagamento e riattivare le subscription.

Casi d’uso comuni

SaaS e API: accesso a livelli con add-on per postazioni o utilizzo
Contenuti e media: accesso mensile con prove introduttive
Piani di assistenza B2B: contratti annuali con add-on di assistenza premium
Strumenti e plugin: chiavi di licenza e versioni rilasciate

Esempi di integrazione

Sessioni di checkout (subscription)

Quando crei sessioni di checkout, includi il prodotto in subscription e gli eventuali add-on:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

Modifiche al piano con proratazione

Effettua l’upgrade o il downgrade di una subscription e controlla il comportamento della proratazione:

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

Annullamento alla data della fatturazione successiva

Pianifica un annullamento che abbia effetto al termine del periodo di fatturazione corrente:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

Estendere il periodo della subscription

Estendi la durata di una subscription passando un nuovo subscription_period_count e subscription_period_interval a PATCH /subscriptions/{id}. La scadenza della subscription viene ricalcolata in base al nuovo conteggio e intervallo; ad esempio, per concedere a un cliente tempo aggiuntivo sul piano corrente:

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

Il periodo di una subscription può essere aumentato, ma mai abbreviato.

Subscription on-demand

Crea una subscription on-demand e addebita in seguito quando necessario:

const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

Aggiornare il metodo di pagamento per una subscription attiva

Aggiorna il metodo di pagamento per una subscription attiva:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

Riattivare una subscription dallo stato on_hold

Riattiva una subscription sospesa a causa di un pagamento non riuscito:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Subscription con mandati conformi alle norme RBI

Le subscription UPI e con carte indiane operano secondo le normative RBI (Reserve Bank of India), con requisiti specifici per i mandati:

Limiti dei mandati

Il tipo e l’importo del mandato dipendono dall’addebito ricorrente della subscription:

Addebiti inferiori alla soglia del mandato (₹15,000 per impostazione predefinita): creiamo un mandato on-demand per l’importo della soglia. L’importo della subscription viene addebitato periodicamente in base alla frequenza della subscription, fino al limite del mandato.
Addebiti pari o superiori alla soglia del mandato: creiamo un mandato per subscription (o un mandato on-demand) per l’importo esatto della subscription.

La soglia del mandato è configurabile per merchant o per richiesta tramite mandate_min_amount_inr_paise (paise INR). L’importo registrato presso la banca è max(mandate_floor, billing_amount); pertanto, quando la fatturazione è inferiore, la soglia diventa di fatto il limite massimo di autorizzazione mostrato al cliente. Per informazioni dettagliate sui mandati conformi alle norme RBI e sulla soglia configurabile dei mandati per i metodi di pagamento indiani, consulta la pagina Metodi di pagamento in India.

Considerazioni su upgrade e downgrade

Importante: quando effettui l’upgrade o il downgrade delle subscription, considera attentamente i limiti dei mandati:

Se un upgrade o downgrade genera un importo superiore a Rs 15,000 e oltrepassa il limite di pagamento on-demand esistente, l’addebito della transazione potrebbe non riuscire.
In questi casi, il cliente potrebbe dover aggiornare il metodo di pagamento o modificare nuovamente la subscription per stabilire un nuovo mandato con il limite corretto.

Autorizzazione per addebiti di importo elevato

Per addebiti della subscription pari o superiori a Rs 15,000:

La banca chiederà al cliente di autorizzare la transazione.
Se il cliente non autorizza la transazione, questa non andrà a buon fine e la subscription verrà sospesa.

Ritardo di elaborazione di 48 ore

Tempistiche di elaborazione: gli addebiti ricorrenti sulle carte indiane e sulle subscription UPI seguono un modello di elaborazione particolare:

Gli addebiti vengono avviati nella data pianificata, in base alla frequenza della subscription.
La detrazione effettiva dall’account del cliente avviene solo dopo 48 ore dall’avvio del pagamento.
Questa finestra di 48 ore può estendersi fino a 2-3 ore aggiuntive, a seconda delle risposte delle API bancarie.

Finestra per l’annullamento del mandato

Durante la finestra di elaborazione di 48 ore:

I clienti possono annullare il mandato tramite le proprie app bancarie.
Se un cliente annulla il mandato durante questo periodo, la subscription rimarrà attiva (si tratta di un caso limite specifico delle subscription AutoPay con carte indiane e UPI).
Tuttavia, la detrazione effettiva potrebbe non riuscire e, in tal caso, metteremo la subscription in sospeso.

Gestione dei casi limite: se fornisci immediatamente ai clienti vantaggi, crediti o utilizzo della subscription all’avvio dell’addebito, devi gestire correttamente questa finestra di 48 ore nella tua applicazione. Considera di:

Ritardare l’attivazione dei vantaggi fino alla conferma del pagamento
Implementare periodi di tolleranza o accesso temporaneo
Monitorare lo stato della subscription per rilevare gli annullamenti dei mandati
Gestire gli stati sospesi della subscription nella logica dell’applicazione

Monitora i webhook della subscription per tenere traccia delle modifiche allo stato del pagamento e gestire i casi limite in cui i mandati vengono annullati durante la finestra di 48 ore.

Best practice

Inizia con livelli chiari: 2–3 piani con differenze evidenti
Comunica i prezzi: mostra totali, proratazione e prossimo rinnovo
Usa le prove con criterio: converti con l’onboarding, non solo con il tempo
Sfrutta gli add-on: mantieni semplici i piani di base e proponi gli extra
Testa le modifiche: convalida le modifiche ai piani e la proratazione in modalità di test

Le subscription sono una base flessibile per i ricavi ricorrenti. Inizia in modo semplice, testa accuratamente e migliora in base alle metriche di adozione, abbandono ed espansione.

Ultima modifica il 31 luglio 2026

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​Cosa sono gli abbonamenti?

​Vantaggi principali

​Creazione degli abbonamenti

​Creazione di un prodotto in abbonamento

​Dettagli del prodotto

​Prezzi

​Impostazioni avanzate

​Periodi di prova degli abbonamenti

​Configurazione dei periodi di prova

​Prove a pagamento

​Prevenire l’uso improprio delle prove

​Rilevare lo stato della prova

​Aggiornare il periodo di prova

​Modifiche al piano della subscription

Product Collections

​Modalità di proratazione

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Modificare i piani con gli add-on

​Visualizzare in anteprima le modifiche al piano

Preview Change Plan API

​Stati della subscription

​Macchina a stati

​Stato On Hold

​Riattivare una subscription dallo stato On Hold

​Eventi webhook per transizione

Subscription Webhook Payloads

​Gestione tramite API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Casi d’uso comuni

​Esempi di integrazione

​Sessioni di checkout (subscription)

​Modifiche al piano con proratazione

​Annullamento alla data della fatturazione successiva

​Estendere il periodo della subscription

​Subscription on-demand

​Aggiornare il metodo di pagamento per una subscription attiva

​Riattivare una subscription dallo stato on_hold

​Subscription con mandati conformi alle norme RBI

​Limiti dei mandati

​Considerazioni su upgrade e downgrade

​Autorizzazione per addebiti di importo elevato

​Ritardo di elaborazione di 48 ore

​Finestra per l’annullamento del mandato

​Best practice

Cosa sono gli abbonamenti?

Vantaggi principali

Creazione degli abbonamenti

Creazione di un prodotto in abbonamento

Dettagli del prodotto

Prezzi

Impostazioni avanzate

Periodi di prova degli abbonamenti

Configurazione dei periodi di prova

Prove a pagamento

Prevenire l’uso improprio delle prove

Rilevare lo stato della prova

Aggiornare il periodo di prova

Modifiche al piano della subscription

Modalità di proratazione

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Modificare i piani con gli add-on

Visualizzare in anteprima le modifiche al piano

Stati della subscription

Macchina a stati

Stato On Hold

Riattivare una subscription dallo stato On Hold

Eventi webhook per transizione

Gestione tramite API

Casi d’uso comuni

Esempi di integrazione

Sessioni di checkout (subscription)

Modifiche al piano con proratazione

Annullamento alla data della fatturazione successiva

Estendere il periodo della subscription

Subscription on-demand

Aggiornare il metodo di pagamento per una subscription attiva

Riattivare una subscription dallo stato on_hold

Subscription con mandati conformi alle norme RBI

Limiti dei mandati

Considerazioni su upgrade e downgrade

Autorizzazione per addebiti di importo elevato

Ritardo di elaborazione di 48 ore

Finestra per l’annullamento del mandato

Best practice