Como adicionar um fluxo de cancelamento ao Paddle Billing

Um fluxo de cancelamento é o passo curto entre “quero cancelar” e o próprio cancelamento: perguntar porquê, oferecer algo adequado ao motivo e cancelar sem complicações se o cliente continuar a querer sair. Este guia explica como funciona o cancelamento no Paddle Billing, o que o Paddle já oferece de forma nativa e como construir o seu próprio passo de retenção sobre a API.

Baseia-se na documentação para programadores do Paddle: cancel a subscription, pause a subscription, resume a subscription, update a subscription, discounts, provisioning and webhooks, o customer portal e Cancellation Flows (todos consultados em novembro de 2026). Trata do Paddle Billing, não do Paddle Classic, cuja API é diferente.

O Paddle é o merchant of record

Uma coisa a ter sempre presente: o Paddle é o merchant of record das suas vendas. Vende ao seu cliente, trata dos impostos e, segundo o Paddle, trata do suporte de faturação e dos chargebacks. Isto quer dizer que a relação de pagamento é entre o cliente e o Paddle. O seu fluxo de cancelamento só deve alterar subscrições através da API do Paddle ou das ferramentas do próprio Paddle, nunca tentando travar pagamentos de outra forma.

Como funciona o cancelamento no Paddle Billing

O Paddle oferece três sítios onde uma subscrição pode ser cancelada.

1. A API de cancelamento

Cancela com POST /subscriptions/{subscription_id}/cancel. O campo effective_from decide quando:

effective_from	O que acontece
next_billing_period (por omissão, e também o que faz um corpo vazio)	O Paddle acrescenta um scheduled_change com a ação cancel. A subscrição continua ativa até à próxima data de faturação e next_billed_at passa a null
immediately	O estado passa logo a canceled e dispara subscription.canceled

O Paddle documenta alguns limites na página de cancelamento:

• Não pode cancelar nem pausar nos 30 minutos anteriores à próxima data de faturação.
• Um cancelamento agendado pode ser removido atualizando a subscrição com scheduled_change a null. É assim que se “desfaz” um cancelamento antes de produzir efeito.
• Uma subscrição cancelada não pode ser reposta. Um cliente que regressa precisa de uma nova subscrição, o que conta para a reconquista.
• Uma subscrição pausada só pode ser cancelada com effective_from: immediately.

2. O customer portal

O customer portal do Paddle permite aos clientes cancelar e atualizar os dados de pagamento. A documentação do Paddle diz que a pausa não é suportada no portal, por isso uma oferta de pausa tem de vir da sua app ou das Cancellation Flows do Paddle.

3. As Cancellation Flows do próprio Paddle

O Paddle tem uma funcionalidade nativa exatamente para isto, parte do Paddle Retain. Configura-se em Retain › Cancellation Flows (guia de configuração). Pede um motivo de cancelamento e pode oferecer uma pausa, uma mudança de plano, um contacto com o suporte ou um desconto por tempo limitado. Segundo o changelog de janeiro de 2026 do Paddle, depois de configurado, o fluxo corre automaticamente quando os clientes cancelam no customer portal ou através dos links de cancelamento nos emails de subscrição do Paddle. Na sua própria app, inicia-o com Paddle.Retain.initCancellationFlow(), que devolve um estado como retained, aborted ou chose_to_cancel. Um changelog de setembro de 2026 acrescenta testes em sandbox através do customer portal, enquanto os fluxos iniciados com initCancellationFlow() continuam a correr apenas em contas live.

Para ser claro: se só precisa de um inquérito de motivos e de uma oferta padrão dentro do Paddle, esta funcionalidade nativa pode bastar, e o Paddle indica-a sem custo adicional para os clientes do Paddle Billing. O resto deste guia é para quando quer o seu próprio fluxo, o seu próprio design ou ofertas que dependem de dados que o Paddle não tem.

As ofertas de retenção que a API do Paddle suporta

Pausa

POST /subscriptions/{subscription_id}/pause pausa uma subscrição (guia). Aceita effective_from (next_billing_period ou immediately) e uma data resume_at opcional. Uma pausa no próximo período de faturação cria uma alteração agendada; o estado passa a paused quando produz efeito.

Para trazer um cliente de volta mais cedo, POST /subscriptions/{subscription_id}/resume só funciona em subscrições pausadas. O campo on_resume decide a faturação: por omissão, o Paddle começa um novo período de faturação e cobra de imediato; continue_existing_billing_period mantém o período anterior. O Paddle também cancela as transações de renovação em atraso quando uma subscrição é pausada, para evitar cobrar duas vezes períodos sobrepostos.

Desconto

Crie o desconto uma vez com POST /discounts. Para uma oferta de retenção como “50% de desconto durante 3 meses”, defina recur como true e maximum_recurring_intervals como o número de períodos de faturação. Depois aplique-o à subscrição com PATCH /subscriptions/{subscription_id}, passando um objeto discount com o ID do desconto e um effective_from de next_billing_period ou immediately (update a subscription). Enviar discount: null remove-o. O Paddle indica que as renovações e as alterações a meio do ciclo não contam como novas utilizações.

Mudança de plano

Um downgrade é também uma atualização da subscrição: substitua os itens pelo preço mais barato. Quando altera os itens ou a data de faturação, o Paddle exige proration_billing_mode. Use o endpoint de pré-visualização para mostrar ao cliente quanto vai pagar antes de confirmar.

Construir o seu próprio fluxo de cancelamento no Paddle

1. Ponha o ponto de entrada do cancelamento na sua app. Ligue “Cancelar subscrição” ao seu fluxo, não diretamente à chamada à API. Mantenha também o customer portal disponível; é o caminho do próprio Paddle e os clientes podem usá-lo.
2. Faça uma pergunta: porquê. Use uma lista curta de motivos mais “Outro” com um campo de texto livre. Guarde a resposta com o ID da subscrição.
3. Mostre uma oferta adequada ao motivo. “Demasiado caro” pede um desconto ou um plano mais barato. “Não o uso neste momento” pede uma pausa com uma data resume_at. “Falta uma funcionalidade” ou “Demasiado complexo” pede uma conversa com o suporte. Não acumule ofertas.
4. Mantenha “Cancelar agora” visível em todos os passos. O cliente deve poder concluir o cancelamento a qualquer momento sem aceitar uma oferta. É uma questão de confiança e, em vários sítios, de lei.
5. Chame o Paddle para o resultado. Desconto: PATCH da subscrição com o desconto. Pausa: POST .../pause. Mudança de plano: PATCH dos itens após uma pré-visualização. Cancelamento: POST .../cancel com effective_from: next_billing_period, para que o cliente mantenha aquilo por que pagou.
6. Confirme o que acontece a seguir. Diga ao cliente a data em que o acesso termina ou a data em que a pausa acaba. Leia-a da subscrição devolvida pelo Paddle em vez de a calcular você mesmo.
7. Deixe-o mudar de ideias. Até o cancelamento agendado produzir efeito, um botão “Manter a minha subscrição” pode limpar o scheduled_change.

Webhooks a ouvir

O guia de provisioning do Paddle recomenda subscription.created e subscription.updated como eventos principais, porque subscription.updated cobre renovações, mudanças de plano, pausas, retomas e cancelamentos. Alguns eventos dedicados são úteis como sinais claros:

Evento	Quando dispara
subscription.updated	Qualquer alteração, incluindo um cancelamento a ser agendado
subscription.canceled	O estado passa a canceled: de imediato, ou na data de faturação num cancelamento agendado
subscription.past_due	A subscrição fica em atraso após uma renovação falhada

As pausas e as retomas também chegam por subscription.updated, com o estado a passar para ou a sair de paused; consulte a referência de webhooks do Paddle para os eventos dedicados disponíveis na sua versão da API.

Dois pormenores da documentação do Paddle: num cancelamento agendado, mantenha o acesso até à data efetiva da alteração agendada; e elimine duplicados pelo event_id e compare occurred_at, porque os eventos podem chegar fora de ordem. O payload de subscription.canceled não inclui management_urls.

Depois do cancelamento: reconquista

Como o Paddle não pode repor uma subscrição cancelada, uma oferta de reconquista tem de levar a um novo checkout. Guarde o motivo de cancelamento que recolheu, espere um tempo razoável e envie uma oferta que responda a esse motivo: uma nova funcionalidade para “faltam funcionalidades”, um preço mais baixo para “demasiado caro”. Envie o cliente para um checkout com o desconto já aplicado.

Fazer isto com o NoChurn

O NoChurn lê as suas subscrições e eventos do Paddle e acrescenta um fluxo de cancelamento com motivos, ofertas (desconto, pausa, mudança de plano) e um cancelamento num clique que fica visível em todos os passos, alojado ou em headless através da API. As ofertas aceites e os cancelamentos são aplicados no Paddle, e o Paddle continua a ser o merchant of record: fica com o checkout, os pagamentos, a recuperação de pagamentos, os impostos e o customer portal. As disputas são geridas pelo Paddle e mostradas no NoChurn em modo só de leitura. O NoChurn envia também emails de reconquista aos dias 30, 60 e 90 com base no motivo do cancelamento, e é grátis abaixo de 300 $ de MRR. Veja NoChurn + Paddle.