Como acrescentar um fluxo de cancelamento ao Maxio

Um fluxo de cancelamento fica entre o botão “Cancelar” e o cancelamento: pergunta porquê, faz uma oferta adequada ao motivo e cancela de forma limpa se o cliente ainda quiser sair. O Maxio Advanced Billing (antigo Chargify) já tem várias das peças: cancelamento diferido, códigos de motivo de churn, holds e mudanças de produto agendadas. Este guia explica como funcionam e como juntá-las num fluxo.

Limita-se à documentação do próprio Maxio: cancelar subscrições, agendar o cancelamento de uma subscrição, gerir subscrições no Billing Portal, configurar as funcionalidades do Billing Portal, códigos de motivo de churn, cenários de hold e retoma, aplicar cupões a subscrições, as referências da API update subscription e initiate delayed cancellation, e exemplos de payloads de webhooks (todos consultados em novembro de 2026). Alguns dos exemplos da API do Maxio ainda usam URLs antigos do Chargify; verifique os endpoints do seu site.

Como funciona o cancelamento no Maxio

O Maxio oferece três momentos (cancelar subscrições):

Momento	O que acontece
Imediatamente	A subscrição é cancelada já
No fim do período	Continua durante o período pago num estado Pending Cancellation e depois é cancelada
Numa data agendada	É cancelada numa data futura escolhida por si ou pelo cliente (exige a funcionalidade de agendamento)

Em todos os casos, o Maxio não reembolsa nem faz proporcionalidade automaticamente. Para um cliente que decidiu sair, o fim do período é a opção justa por defeito: fica com aquilo que pagou.

Um cancelamento pendente pode ser anulado: o guia do Maxio para construir o seu próprio Billing Portal indica um endpoint separado para isso. Pela API, um cancelamento diferido aceita um código de motivo e o indicador cancel_at_end_of_period; agendar uma data exige que a funcionalidade Schedule Subscription Cancellation esteja ativada no seu site.

Algumas subscrições não podem ter o cancelamento agendado. Segundo o Maxio, as subscrições pré-pagas são sempre canceladas de imediato, e as subscrições em estados como Past Due, Expired ou Paused não podem ser agendadas (agendar um cancelamento). O seu fluxo tem de tratar esses casos.

Códigos de motivo de churn

O Maxio tem códigos de motivo de churn nativos. Cria, edita, ordena e apaga-os nas definições do seu site, e aparecem quando alguém cancela a partir do resumo da subscrição. A partir do momento em que o seu site tem códigos configurados, é preciso escolher um motivo antes de confirmar um cancelamento. Quando os códigos estão em uso, as análises de churn do Maxio mostram o motivo de cada evento de churn. Use-os mesmo que construa o seu próprio fluxo: envie o código de motivo com o cancelamento, para que os relatórios do Maxio e os seus estejam de acordo.

O Billing Portal

O Billing Portal alojado do Maxio permite aos clientes cancelar a partir de Plan Details, escolhendo entre cancelamento imediato e no fim do período (subscrições no Billing Portal). Controla-o com interruptores separados nas funcionalidades do Billing Portal:

• Allow Immediate Cancellations
• Allow Delayed Cancellations (at end of period)
• Allow Scheduling Cancellations, para que os clientes possam escolher uma data futura
• Display Churn Reason Codes, para que os clientes escolham um motivo ao cancelar

O portal pede uma confirmação, e o Maxio nota que depois desse passo não há como desfazer. O que o portal não faz é uma oferta: regista um motivo e cancela. Se quer um passo de retenção, ponha-o na sua app antes de o cliente chegar ao portal, ou desative o cancelamento no portal e trate dele você mesmo. Se mantiver o cancelamento no portal, ativar apenas o cancelamento diferido é uma escolha sensata.

As ofertas que o Maxio suporta

Hold (pausa)

O Maxio chama a uma pausa um hold (cenários de hold e retoma). Durante o hold, não há renovações. Um hold pode ter uma data de retoma, e a subscrição retoma então sozinha (o objeto subscription tem um campo automatically_resume_at). Só uma subscrição Active pode ser posta em hold. Um detalhe importa para os fluxos de cancelamento: uma subscrição marcada para cancelar no fim do período não é cancelada enquanto está em hold; é cancelada depois de retomar.

O guia do Maxio indica endpoints de hold e de retoma, mas as suas próprias páginas mostram-nos com duas formas de caminho (com e sem /subscriptions/:id), por isso verifique a referência atual da API antes de construir sobre eles.

Cupão

Os cupões do Maxio podem ser acrescentados a uma subscrição existente (aplicar cupões). Duas regras da documentação:

• A duração do cupão conta a partir da próxima renovação da subscrição, não da inscrição.
• Um cupão só se aplica a planos da mesma família de produtos.

As páginas que encontrámos descrevem como acrescentar um cupão na interface de administração; verifique na referência da API do Maxio a chamada que vai usar a partir da sua app.

Mudança de produto

Para “demasiado caro”, um plano mais barato é muitas vezes melhor do que um desconto. O Maxio suporta uma mudança de produto diferida (update subscription): defina product_handle com o novo produto e product_change_delayed a true, e a mudança acontece na próxima renovação, sem proporcionalidade. Enviar um próximo produto vazio cancela uma mudança agendada. Os cupões da subscrição só passam para o novo plano se estiverem restritos ao novo plano ou não tiverem restrições.

Construir o fluxo

1. Envie o “Cancelar” da sua app para o seu fluxo. Decida o que o Billing Portal permite, para que os clientes não cheguem a duas experiências de cancelamento diferentes.
2. Verifique o que é possível para esta subscrição. As subscrições pré-pagas são canceladas de imediato; as Past Due e Paused não podem ser agendadas. Um hold exige uma subscrição Active.
3. Pergunte porquê, usando a mesma lista que os seus códigos de motivo de churn no Maxio.
4. Mostre uma oferta adequada. “Demasiado caro”: uma mudança de produto diferida ou um cupão. “Não o uso neste momento”: um hold com data de retoma. “Falta uma funcionalidade”: uma resposta de uma pessoa.
5. Mantenha “Cancelar agora” visível em todos os passos. Um clique conclui o cancelamento, sem aceitar nenhuma oferta.
6. Aplique o resultado. Cancelamento diferido com o código de motivo e cancel_at_end_of_period; ou o hold, o cupão ou a mudança de produto.
7. Confirme a data a partir da subscrição que o Maxio devolve, e ofereça a anulação de um cancelamento pendente até ele produzir efeito.

Webhooks a ouvir

A partir dos exemplos de payloads e dos eventos de webhooks do Maxio:

• subscription_state_change traz state e previous_state: use-o para ver uma subscrição passar a cancelada, em hold ou de volta a ativa.
• pending_cancellation_change tem um payload de exemplo com cancel_at_end_of_period e delayed_cancel_at. As páginas do Maxio que encontrámos não dizem exatamente quando dispara, por isso teste-o no seu site.

O Maxio diz que os webhooks são assíncronos e aconselha a verificar se previous_state corresponde ao que tem antes de atualizar os seus registos, e a obter a subscrição pela API em caso de dúvida.

Fazer isto com a NoChurn

A NoChurn liga-se ao Maxio com uma chave de API, importa clientes e subscrições e acompanha os webhooks do Maxio. Acrescenta um fluxo de cancelamento com motivos, ofertas que se tornam um cupão ou uma mudança de produto na subscrição Maxio, e um cancelamento num clique sempre visível, alojado ou headless através da API. Envia também emails de reconquista aos dias 30, 60 e 90 com base no motivo do cancelamento e calcula um churn score de 0 a 100. A faturação, os impostos, os seus produtos e a cobrança ficam no Maxio e no seu gateway. A NoChurn é gratuita abaixo de 300 $ de MRR. Veja NoChurn + Maxio.