Come Lemon Squeezy gestisce i pagamenti falliti degli abbonamenti

Quando il rinnovo di un abbonamento fallisce su Lemon Squeezy, molte cose avvengono senza che tu faccia nulla: l’addebito viene ritentato, il cliente riceve delle email e l’abbonamento passa per alcuni stati prima di terminare. Sapere esattamente cosa fa Lemon Squeezy, e cosa lascia a te, fa la differenza tra un cliente che sparisce in silenzio e uno che aggiorna la sua carta.

Questa guida percorre quel ciclo passo per passo, poi dà consigli pratici da applicare nella tua app. Si attiene alla documentazione di Lemon Squeezy: la pagina di aiuto Recovery and Dunning, il riferimento dell’oggetto Subscription, i tipi di evento webhook e la pagina di aiuto Subscriptions (tutti consultati a novembre 2026). Dove la documentazione non dice qualcosa, lo segnaliamo.

Il ciclo di vita di un pagamento fallito su Lemon Squeezy

Lemon Squeezy è un merchant of record: addebita il cliente, gestisce i tentativi e invia le email di fatturazione. Il tuo compito è soprattutto reagire ai cambi di stato nella tua app.

Passo 1: il rinnovo fallisce e l’abbonamento passa a past_due

Secondo il riferimento dell’oggetto Subscription, quando un pagamento di rinnovo fallisce lo stato dell’abbonamento diventa past_due. L’abbonamento passa poi per 4 tentativi di pagamento nell’arco di 2 settimane. Se uno di quei tentativi riesce, lo stato torna active.

La pagina Recovery and Dunning aggiunge due dettagli:

• Durante i tentativi, l’abbonamento conta ancora come attivo dal punto di vista dell’accesso: il cliente continua a usare il tuo prodotto.
• Ogni tentativo fallito fa partire un’email che chiede al cliente di aggiornare i suoi dati di fatturazione.

Passo 2: i tentativi si esauriscono e l’abbonamento diventa unpaid

Se tutti i tentativi falliscono, lo stato passa a unpaid. È qui che inizia il dunning di Lemon Squeezy. Secondo la pagina Recovery and Dunning, le email di sollecito vengono inviate in un periodo prestabilito, e ognuna rimanda a una pagina dove il cliente può aggiornare i suoi dati di pagamento e riattivare l’abbonamento.

Passo 3: il dunning termina, o l’abbonamento resta unpaid

Cosa succede dopo dipende dalle tue impostazioni di Recovery:

• Puoi impostare un ritardo dopo il quale l’abbonamento viene annullato automaticamente. Una volta avvenuto, il cliente non può più riattivarlo.
• Puoi lasciare l’abbonamento unpaid, il che permette al cliente di riattivarlo in qualsiasi momento.
• Se disattivi il dunning, lo stato resta semplicemente unpaid, e sta a te decidere cosa significa per l’accesso.

Quando il dunning si conclude, Lemon Squeezy invia subscription_expired, che la sua pagina dei tipi di evento descrive come inviato “una volta completato il dunning per gli abbonamenti past_due”.

PayPal è diverso

La pagina Recovery segnala che gli abbonamenti PayPal seguono un ritmo di tentativi diverso, con un tentativo ogni 5 giorni. Se una quota significativa dei tuoi clienti paga con PayPal, non dare per scontato che valga per loro la cronologia delle carte.

Gli stati in sintesi

Stato	Cosa significa	Il cliente deve avere accesso?
active	Pagato e in regola	Sì
past_due	Rinnovo fallito, tentativi in corso (4 in circa 2 settimane)	Sì, secondo Lemon Squeezy
unpaid	Tentativi esauriti, dunning in corso o disattivato	Decidi tu; la documentazione di Lemon Squeezy sul ciclo di vita dice che l’accesso dovrebbe terminare solo a expired
cancelled	Annullato, nel periodo di tolleranza fino a ends_at	Sì, fino a ends_at
expired	Terminato	No

La pagina di aiuto Subscriptions dice che i clienti dovrebbero mantenere l’accesso in tutti gli stati tranne expired. Alcuni team preferiscono limitare le funzioni durante unpaid; se lo fai, dillo chiaramente nella tua app perché il cliente sappia perché.

I webhook che ti servono

La pagina dei tipi di evento elenca gli eventi degli abbonamenti. Per i pagamenti falliti, contano questi cinque:

Evento	Quando viene inviato	Payload
subscription_payment_failed	Un pagamento di rinnovo fallisce (non il primo pagamento)	Oggetto subscription invoice
subscription_payment_recovered	Un pagamento riesce dopo un fallimento	Oggetto subscription invoice
subscription_payment_success	Qualsiasi pagamento riuscito; sempre inviato insieme a subscription_payment_recovered	Oggetto subscription invoice
subscription_updated	Qualsiasi modifica all’abbonamento, compresi i cambi di stato	Oggetto subscription
subscription_expired	Dopo che un abbonamento annullato termina, o una volta completato il dunning	Oggetto subscription

Due cose da notare. Primo, subscription_payment_failed contiene un oggetto subscription invoice, non l’abbonamento stesso, quindi di solito recupererai l’abbonamento per leggerne lo stato. Secondo, Lemon Squeezy dice che subscription_updated viene inviato a ogni modifica dopo il pagamento iniziale, quindi per molte app basta ascoltare quello e leggere status.

La documentazione che abbiamo usato non descrive su questi eventi un campo con il motivo del rifiuto paragonabile ai codici di rifiuto dei circuiti, quindi non costruire una logica che dipenda da uno senza controllare i tuoi payload.

Il link per aggiornare il pagamento

Ogni oggetto subscription ha un attributo urls con un link update_payment_method: un URL pre-firmato dove il cliente può cambiare la sua carta. Il riferimento dell’oggetto Subscription dice che questi URL firmati sono validi per 24 ore, e la guida alla gestione degli abbonamenti dice lo stesso per i link di recupero: recupera di nuovo l’abbonamento per ottenerne uno nuovo invece di salvarlo.

Questo ha una conseguenza pratica. Se invii email tue, non incollare un link salvato in un’email che potrebbe essere aperta tre giorni dopo. Rimanda a una pagina della tua app che recupera un URL nuovo e reindirizza.

Configurare le impostazioni di Recovery

Le email di sollecito di Lemon Squeezy si configurano nella pagina delle impostazioni Recovery del tuo store. La pagina Recovery and Dunning dice che puoi attivare o disattivare il dunning e modificare le email, gli oggetti, i contenuti e il calendario di invio, con valori predefiniti forniti.

Una configurazione sensata:

1. Tieni attivo il dunning. Non costa nulla e raggiunge i clienti che non aprono mai la tua app.
2. Riscrivi il testo predefinito con la tua voce. Di’ cos’è il prodotto, cosa succede se la carta non viene aggiornata, e tieni un solo pulsante chiaro.
3. Decidi deliberatamente sull’annullamento automatico. Lasciare gli abbonamenti unpaid tiene aperta la porta alla riattivazione. L’annullamento automatico ti dà una data di fine netta. Scegline uno e fai corrispondere le regole di accesso della tua app.
4. Provalo. La modalità test di Lemon Squeezy ti permette di simulare gli eventi webhook, così puoi verificare la reazione della tua app a past_due, unpaid ed expired prima che ci arrivi un cliente reale.

Consigli pratici da applicare oggi

Il comportamento integrato di Lemon Squeezy è una buona base. Le lacune sono soprattutto dal tuo lato dell’integrazione.

1. Mostrare il problema dentro la tua app

Le email di fatturazione vengono filtrate. Quando un abbonamento è past_due o unpaid, mostra un banner nella tua app con un pulsante verso la tua pagina “aggiorna la carta”. Spesso è il momento in cui il cliente è più propenso ad agire, perché sta già usando il prodotto.

2. Gestire gli stati in modo esplicito

Associa ogni stato a una regola di accesso in un unico punto del tuo codice. Un bug comune è trattare tutto ciò che non è active come “nessun accesso”, il che blocca i clienti past_due e cancelled che hanno pagato il periodo in corso.

3. Verificare e deduplicare i webhook

Lemon Squeezy firma ogni richiesta con un HMAC nell’header X-Signature (firma delle richieste) e ritenta le risposte diverse da 200 fino ad altre tre volte con backoff esponenziale (richieste webhook). Verifica la firma sul corpo grezzo e rendi il tuo handler sicuro da eseguire due volte.

4. Inviare un messaggio umano

Le email automatiche coprono la meccanica. Un messaggio breve e semplice da una persona reale (“La tua carta non è passata, ecco il link, rispondi se c’è qualcosa che non va”) spesso viene recepito diversamente. Invialo una volta, intorno al momento in cui l’abbonamento diventa unpaid, non a ogni tentativo fallito.

5. Misurare il recupero

Conta gli eventi subscription_payment_failed e subscription_payment_recovered ogni mese. Il rapporto è il tuo tasso di recupero, misurato sui tuoi dati. Se cambia dopo una modifica dei testi, sai che la modifica ha contato.

Farlo con NoChurn

Lemon Squeezy continua a gestire il pagamento, i tentativi e le proprie email di sollecito; NoChurn non lo sostituisce. NoChurn legge i tuoi webhook Lemon Squeezy, mette ogni pagamento fallito in un’unica cronologia e può aggiungere email di recupero scritte dall’IA che rivedi prima dell’invio. Assegna anche a ogni cliente un churn score da 0 a 100, e le contestazioni, che Lemon Squeezy gestisce come merchant of record, compaiono in sola lettura. NoChurn è gratuito sotto i 300 $ di MRR, con tutte le funzioni in ogni piano (il tuo dominio email da 9 $). Vedi NoChurn + Lemon Squeezy.