Como o Lemon Squeezy trata os pagamentos de subscrição falhados

Quando a renovação de uma subscrição falha no Lemon Squeezy, acontece muita coisa sem que tenha de fazer nada: a cobrança é tentada de novo, o cliente recebe emails e a subscrição passa por alguns estados antes de terminar. Saber exatamente o que o Lemon Squeezy faz, e o que deixa a seu cargo, é a diferença entre um cliente que desaparece em silêncio e um que atualiza o cartão.

Este guia percorre esse ciclo passo a passo e depois dá conselhos práticos que pode aplicar na sua própria app. Limita-se à documentação do próprio Lemon Squeezy: a página de ajuda Recovery and Dunning, a referência do objeto Subscription, os tipos de eventos de webhook e a página de ajuda Subscriptions (todos consultados em novembro de 2026). Quando a documentação não diz alguma coisa, dizemo-lo.

O ciclo de um pagamento falhado no Lemon Squeezy

O Lemon Squeezy é um merchant of record: cobra o cliente, faz as novas tentativas e envia os emails de faturação. O seu trabalho é sobretudo reagir às mudanças de estado na sua app.

Passo 1: a renovação falha e a subscrição passa a past_due

Segundo a referência do objeto Subscription, quando um pagamento de renovação falha o estado da subscrição passa a past_due. A subscrição passa então por 4 novas tentativas de pagamento ao longo de 2 semanas. Se uma dessas tentativas resultar, o estado volta a active.

A página Recovery and Dunning acrescenta dois detalhes:

• Durante as novas tentativas, a subscrição continua a contar como ativa do ponto de vista do acesso: o cliente continua a usar o seu produto.
• Cada tentativa falhada desencadeia um email que pede ao cliente para atualizar os dados de faturação.

Passo 2: as tentativas esgotam-se e a subscrição passa a unpaid

Se todas as novas tentativas falharem, o estado passa a unpaid. É aqui que começa o dunning do Lemon Squeezy. Segundo a página Recovery and Dunning, os emails de recuperação são enviados durante um período definido, e cada um remete para uma página onde o cliente pode atualizar os dados de pagamento e reativar a subscrição.

Passo 3: o dunning termina, ou a subscrição fica unpaid

O que acontece a seguir depende das suas definições de Recovery:

• Pode definir um prazo ao fim do qual a subscrição é cancelada automaticamente. A partir daí, o cliente já não a pode reativar.
• Pode deixar a subscrição unpaid, o que permite ao cliente reativá-la a qualquer momento.
• Se desativar o dunning, o estado fica simplesmente unpaid, e cabe-lhe decidir o que isso significa para o acesso.

Quando o dunning termina, o Lemon Squeezy envia subscription_expired, que a sua página de tipos de eventos descreve como disparando “quando o dunning foi concluído para subscrições past_due”.

O PayPal é diferente

A página Recovery nota que as subscrições PayPal seguem outro ritmo de novas tentativas, com tentativas a cada 5 dias. Se uma parte significativa dos seus clientes paga com PayPal, não parta do princípio de que o calendário dos cartões se aplica a eles.

Os estados num relance

Estado	O que significa	O cliente deve ter acesso?
active	Pago e em dia	Sim
past_due	Renovação falhada, novas tentativas em curso (4 em cerca de 2 semanas)	Sim, segundo o Lemon Squeezy
unpaid	Tentativas esgotadas, dunning em curso ou desativado	Decisão sua; a documentação do ciclo do Lemon Squeezy diz que o acesso só deve terminar em expired
cancelled	Cancelada, no período de tolerância até ends_at	Sim, até ends_at
expired	Terminada	Não

A página de ajuda Subscriptions diz que os clientes devem manter o acesso em todos os estados exceto expired. Algumas equipas preferem restringir funcionalidades enquanto unpaid; se o fizer, diga-o claramente na sua app para que o cliente saiba porquê.

Os webhooks de que precisa

A página de tipos de eventos lista os eventos de subscrição. Para os pagamentos falhados, importam estes cinco:

Evento	Quando dispara	Conteúdo
subscription_payment_failed	Um pagamento de renovação falha (não o primeiro pagamento)	Objeto subscription invoice
subscription_payment_recovered	Um pagamento resulta depois de uma falha	Objeto subscription invoice
subscription_payment_success	Qualquer pagamento bem-sucedido; sempre enviado juntamente com subscription_payment_recovered	Objeto subscription invoice
subscription_updated	Qualquer alteração à subscrição, incluindo mudanças de estado	Objeto subscription
subscription_expired	Depois de uma subscrição cancelada terminar, ou quando o dunning é concluído	Objeto subscription

Duas coisas a notar. Primeiro, subscription_payment_failed traz um objeto subscription invoice, não a subscrição em si, por isso normalmente terá de obter a subscrição para ler o estado. Segundo, o Lemon Squeezy diz que subscription_updated dispara em cada alteração depois do pagamento inicial, por isso para muitas apps basta ouvi-lo e ler status.

A documentação que usámos não descreve, nestes eventos, nenhum campo de motivo de recusa comparável aos códigos de recusa das redes de cartões, por isso não construa lógica que dependa de um sem verificar os seus próprios payloads.

O link para atualizar o pagamento

Cada objeto de subscrição tem um atributo urls com um link update_payment_method: um URL pré-assinado onde o cliente pode mudar o cartão. A referência do objeto Subscription diz que estes URLs assinados são válidos durante 24 horas, e o guia de gestão de subscrições diz o mesmo para os links de recuperação: obtenha de novo a subscrição para ter um link novo em vez de o guardar.

Isso tem uma consequência prática. Se envia os seus próprios emails, não cole um link guardado num email que pode ser aberto três dias depois. Remeta para uma página da sua app que obtém um URL novo e redireciona.

Configurar as definições de Recovery

Os emails de recuperação do Lemon Squeezy configuram-se na página de definições Recovery da sua loja. A página Recovery and Dunning diz que pode ativar ou desativar o dunning e editar os emails, os assuntos, o conteúdo e o calendário de envio, com valores predefinidos.

Uma configuração sensata:

1. Mantenha o dunning ativo. Não custa nada e chega aos clientes que nunca abrem a sua app.
2. Reescreva o texto predefinido com a sua voz. Diga o que é o produto, o que acontece se o cartão não for atualizado, e mantenha um único botão claro.
3. Decida deliberadamente sobre o cancelamento automático. Deixar as subscrições unpaid mantém a porta aberta à reativação. Cancelar automaticamente dá-lhe uma data de fim clara. Escolha uma opção e faça corresponder as regras de acesso da sua app.
4. Teste. O modo de teste do Lemon Squeezy permite simular eventos de webhook, para verificar a reação da sua app a past_due, unpaid e expired antes de um cliente real passar por eles.

Conselhos práticos que pode aplicar hoje

O comportamento nativo do Lemon Squeezy é uma boa base. As lacunas estão sobretudo do seu lado da integração.

1. Mostrar o problema dentro da sua app

Os emails de faturação ficam retidos em filtros. Quando uma subscrição está past_due ou unpaid, mostre um banner na sua app com um botão para a sua rota “atualizar cartão”. É muitas vezes o momento em que o cliente tem mais probabilidade de agir, porque já está a usar o produto.

2. Tratar os estados de forma explícita

Associe cada estado a uma regra de acesso num único sítio do seu código. Um bug comum é tratar tudo o que não é active como “sem acesso”, o que bloqueia clientes past_due e cancelled que pagaram o período atual.

3. Verificar e eliminar duplicados nos webhooks

O Lemon Squeezy assina cada pedido com um HMAC no cabeçalho X-Signature (assinatura dos pedidos) e volta a tentar as respostas que não são 200 até mais três vezes com espera exponencial (pedidos de webhook). Verifique a assinatura sobre o corpo bruto e faça com que o seu handler possa correr duas vezes sem problema.

4. Enviar uma mensagem humana

Os emails automáticos cobrem a mecânica. Uma mensagem curta e simples de uma pessoa real (“O seu cartão não passou, aqui está o link, responda se houver algum problema”) é muitas vezes recebida de outra forma. Envie-a uma vez, por volta do momento em que a subscrição passa a unpaid, não em cada tentativa falhada.

5. Acompanhar a recuperação

Conte os eventos subscription_payment_failed e subscription_payment_recovered por mês. A relação entre os dois é a sua própria taxa de recuperação, medida nos seus dados. Se mexer depois de uma mudança de texto, sabe que a mudança importou.

Fazer isto com a NoChurn

O Lemon Squeezy continua a tratar do pagamento, das novas tentativas e dos seus próprios emails de recuperação; a NoChurn não substitui isso. A NoChurn lê os seus webhooks do Lemon Squeezy, põe cada pagamento falhado numa única cronologia e pode acrescentar emails de recuperação escritos por IA que revê antes de serem enviados. Dá também a cada cliente um churn score de 0 a 100, e as disputas, que o Lemon Squeezy trata enquanto merchant of record, aparecem só em leitura. A NoChurn é gratuita abaixo de 300 $ de MRR, com todas as funcionalidades em todos os planos (o seu próprio domínio de email a partir de 9 $). Veja NoChurn + Lemon Squeezy.