Aggiungere un flusso di disdetta a Paddle Billing

Un flusso di disdetta è il breve passaggio tra «voglio disdire» e la disdetta vera e propria: chiedi perché, offri qualcosa che risponda al motivo e cancella in modo pulito se il cliente vuole comunque andarsene. Questa guida spiega come funziona la disdetta in Paddle Billing, cosa offre già Paddle in modo nativo e come costruire il tuo passo di retention sopra la sua API.

Si attiene alla documentazione per sviluppatori di Paddle: cancel a subscription, pause a subscription, resume a subscription, update a subscription, discounts, provisioning and webhooks, il customer portal e le Cancellation Flows (tutti consultati a novembre 2026). Si parla di Paddle Billing, non di Paddle Classic, che ha un’API diversa.

Paddle è il merchant of record

Una cosa da tenere a mente per tutta la guida: Paddle è il merchant of record delle tue vendite. Vende al tuo cliente, gestisce le imposte e, secondo Paddle, gestisce il supporto alla fatturazione e i chargeback. Questo significa che il rapporto di pagamento è tra il cliente e Paddle. Il tuo flusso di disdetta deve modificare gli abbonamenti solo tramite l’API di Paddle o gli strumenti di Paddle, mai cercando di bloccare i pagamenti in altro modo.

Come funziona la disdetta in Paddle Billing

Paddle ti offre tre punti in cui un abbonamento può essere cancellato.

1. L’API di cancellazione

Cancelli con POST /subscriptions/{subscription_id}/cancel. Il campo effective_from decide quando:

effective_from	Cosa succede
next_billing_period (predefinito, ed è anche ciò che fa un body vuoto)	Paddle aggiunge una scheduled_change con azione cancel. L’abbonamento resta attivo fino alla prossima data di fatturazione e next_billed_at diventa null
immediately	Lo stato passa subito a canceled e scatta subscription.canceled

Paddle documenta alcuni limiti nella pagina sulla cancellazione:

• Non puoi cancellare o mettere in pausa nei 30 minuti precedenti la prossima data di fatturazione.
• Una cancellazione programmata può essere rimossa aggiornando l’abbonamento con scheduled_change impostato a null. È così che «annulli» una disdetta prima che abbia effetto.
• Un abbonamento cancellato non può essere ripristinato. Un cliente che torna ha bisogno di un nuovo abbonamento, il che conta per il win-back.
• Un abbonamento in pausa può essere cancellato solo con effective_from: immediately.

2. Il customer portal

Il customer portal di Paddle permette ai clienti di disdire e aggiornare i dati di pagamento. La documentazione di Paddle dice che la pausa non è supportata nel portale, quindi un’offerta di pausa deve venire dalla tua app o dalle Cancellation Flows di Paddle.

3. Le Cancellation Flows di Paddle

Paddle ha una funzione nativa proprio per questo, parte di Paddle Retain. La configuri in Retain › Cancellation Flows (guida alla configurazione). Chiede un motivo di disdetta e può offrire una pausa, un cambio di piano, un contatto con il supporto o uno sconto a tempo. Secondo il changelog di gennaio 2026 di Paddle, una volta configurato il flusso parte automaticamente quando i clienti disdicono nel customer portal o tramite i link di disdetta nelle email di abbonamento di Paddle. Nella tua app lo avvii con Paddle.Retain.initCancellationFlow(), che restituisce uno stato come retained, aborted o chose_to_cancel. Un changelog di settembre 2026 aggiunge i test in sandbox tramite il customer portal, mentre i flussi avviati con initCancellationFlow() funzionano ancora solo sugli account live.

Per essere chiari: se ti servono solo un sondaggio sui motivi e un’offerta standard dentro Paddle, questa funzione nativa può bastare, e Paddle la indica senza costi aggiuntivi per i clienti Paddle Billing. Il resto di questa guida è per quando vuoi un flusso tuo, un design tuo od offerte che dipendono da dati che Paddle non ha.

Le offerte di retention supportate dall’API di Paddle

Pausa

POST /subscriptions/{subscription_id}/pause mette in pausa un abbonamento (guida). Accetta effective_from (next_billing_period o immediately) e una data resume_at facoltativa. Una pausa al prossimo periodo di fatturazione crea una modifica programmata; lo stato diventa paused quando ha effetto.

Per far tornare un cliente prima, POST /subscriptions/{subscription_id}/resume funziona solo sugli abbonamenti in pausa. Il campo on_resume decide la fatturazione: per impostazione predefinita Paddle avvia un nuovo periodo di fatturazione e addebita subito; continue_existing_billing_period mantiene invece il vecchio periodo. Paddle inoltre cancella le transazioni di rinnovo scadute quando un abbonamento viene messo in pausa, per evitare di addebitare due volte periodi sovrapposti.

Sconto

Crea lo sconto una volta con POST /discounts. Per un’offerta di retention come «50% di sconto per 3 mesi», imposta recur a true e maximum_recurring_intervals al numero di periodi di fatturazione. Poi applicalo all’abbonamento con PATCH /subscriptions/{subscription_id}, passando un oggetto discount con l’ID dello sconto e un effective_from pari a next_billing_period o immediately (update a subscription). Inviare discount: null lo rimuove. Paddle precisa che i rinnovi e le modifiche a metà ciclo non contano come nuovi utilizzi.

Cambio di piano

Anche un downgrade è un aggiornamento dell’abbonamento: sostituisci gli articoli con il prezzo più basso. Quando cambi gli articoli o la data di fatturazione, Paddle richiede proration_billing_mode. Usa l’endpoint di anteprima per mostrare al cliente quanto pagherà prima di confermare.

Costruire il tuo flusso di disdetta su Paddle

1. Metti il punto d’ingresso della disdetta nella tua app. Collega «Disdici abbonamento» al tuo flusso, non direttamente alla chiamata API. Lascia disponibile anche il customer portal; è il percorso di Paddle e i clienti potrebbero usarlo.
2. Fai una sola domanda: perché. Usa una breve lista di motivi più «Altro» con un campo di testo libero. Salva la risposta con l’ID dell’abbonamento.
3. Mostra una sola offerta adatta al motivo. «Troppo caro» si adatta a uno sconto o a un piano più economico. «Non lo uso in questo periodo» si adatta a una pausa con una data resume_at. «Manca una funzione» o «Troppo complesso» si adatta a una conversazione con il supporto. Non accumulare offerte.
4. Tieni «Disdici ora» visibile a ogni passo. Il cliente deve poter completare la disdetta in qualsiasi momento senza accettare un’offerta. È una questione di fiducia e, in diversi paesi, di legge.
5. Chiama Paddle per l’esito. Sconto: PATCH dell’abbonamento con lo sconto. Pausa: POST .../pause. Cambio di piano: PATCH degli articoli dopo un’anteprima. Disdetta: POST .../cancel con effective_from: next_billing_period, così il cliente mantiene ciò che ha pagato.
6. Conferma cosa succede dopo. Comunica al cliente la data in cui termina l’accesso o quella in cui finisce la pausa. Leggila dall’abbonamento restituito da Paddle invece di calcolarla tu.
7. Lasciagli cambiare idea. Finché la cancellazione programmata non ha effetto, un pulsante «Mantieni il mio abbonamento» può cancellare la scheduled_change.

Webhook da ascoltare

La guida al provisioning di Paddle consiglia subscription.created e subscription.updated come eventi principali, perché subscription.updated copre rinnovi, cambi di piano, pause, riprese e disdette. Alcuni eventi dedicati sono utili come segnali chiari:

Evento	Quando scatta
subscription.updated	Qualsiasi modifica, compresa la programmazione di una disdetta
subscription.canceled	Lo stato diventa canceled: subito, o alla data di fatturazione per una disdetta programmata
subscription.past_due	L’abbonamento diventa past due dopo un rinnovo fallito

Anche pause e riprese arrivano tramite subscription.updated, con lo stato che passa a o da paused; consulta il riferimento sui webhook di Paddle per gli eventi dedicati disponibili nella tua versione dell’API.

Due dettagli dalla documentazione di Paddle: per una disdetta programmata, mantieni l’accesso fino alla data di effetto della modifica programmata; e deduplica su event_id e confronta occurred_at, perché gli eventi possono arrivare in disordine. Il payload di subscription.canceled non include management_urls.

Dopo la disdetta: il win-back

Poiché Paddle non può ripristinare un abbonamento cancellato, un’offerta di win-back deve portare a un nuovo checkout. Conserva il motivo di disdetta raccolto, aspetta un tempo ragionevole e invia un’offerta che risponda a quel motivo: una nuova funzione per «mancano funzioni», un prezzo più basso per «troppo caro». Manda il cliente a un checkout con lo sconto già applicato.

Farlo con NoChurn

NoChurn legge abbonamenti ed eventi Paddle e aggiunge un flusso di disdetta con motivi, offerte (sconto, pausa, cambio di piano) e una disdetta in un clic che resta visibile a ogni passo, ospitato o headless tramite l’API. Le offerte accettate e le disdette vengono applicate in Paddle, e Paddle resta il merchant of record: mantiene checkout, pagamenti, recupero dei pagamenti, imposte e customer portal. Le contestazioni sono gestite da Paddle e mostrate in NoChurn in sola lettura. NoChurn invia anche email di win-back a 30, 60 e 90 giorni in base al motivo della disdetta, ed è gratuito sotto i 300 $ di MRR. Vedi NoChurn + Paddle.