Skip to main content

​
Resumo

O Sistema de Cancelamento Agendado permite que você agende o cancelamento de uma assinatura para ocorrer ao final do período atual, garantindo que o cliente tenha acesso completo até o fim do período já pago. Diferente do cancelamento imediato, o cancelamento agendado preserva o acesso do cliente até a data efetiva de cancelamento. Como usar? Atualize a assinatura com cancelAtPeriodEnd: true: 
{
  "cancelAtPeriodEnd": true,
  "scheduledCancellationAt": "2025-12-31",  // Opcional (YYYY-MM-DD)
  "scheduledCancellationReason": "Cliente solicitou cancelamento"  // Opcional
}

​
Visão Geral

O cancelamento agendado é uma funcionalidade que permite marcar uma assinatura para ser cancelada automaticamente em uma data futura, sem interromper o acesso imediato do cliente. Isso é especialmente útil para:
  • Manter a satisfação do cliente ao permitir que ele use o serviço até o fim do período pago
  • Reduzir solicitações de reembolso
  • Melhorar a experiência do usuário ao oferecer flexibilidade no cancelamento

​
Conceitos Principais

​
Cancelamento Agendado

O cancelamento agendado é ativado através dos campos cancelAtPeriodEnd, scheduledCancellationAt e scheduledCancellationReason no objeto de assinatura:
  • cancelAtPeriodEnd (boolean): Indica se a assinatura está agendada para cancelamento ao final do período atual
  • scheduledCancellationAt (date, opcional): Data específica agendada para o cancelamento (formato YYYY-MM-DD)
  • scheduledCancellationReason (string, opcional): Motivo do cancelamento agendado. Este campo permite armazenar uma descrição textual do motivo pelo qual o cancelamento foi agendado (ex.: “Cliente solicitou cancelamento”, “Mudança de plano”, etc.). É útil para auditoria e análise de cancelamentos.
Quando cancelAtPeriodEnd é definido como true, a assinatura continuará ativa até a data efetiva de cancelamento, que é calculada com base em uma priorização de datas.

​
Cálculo da Data de Cancelamento

A data efetiva de cancelamento é determinada pela seguinte ordem de prioridade:
  1. scheduledCancellationAt (se fornecido)
  2. trialEnd (se a assinatura estiver em trial)
  3. nextDueDate (próxima data de vencimento)

​
Estados da Subscription com Cancelamento Agendado

Quando uma assinatura tem cancelamento agendado, ela mantém seu status atual (active, trialing, etc.) até a data efetiva de cancelamento. Nesse momento, o scheduler processa o cancelamento e a assinatura muda para status canceled.

​
Cenários de Uso

​
Cenário 1: Cancelamento ao Final do Período Atual

O caso mais comum é agendar o cancelamento para o final do período atual, sem especificar uma data: 
{
  "cancelAtPeriodEnd": true,
  "scheduledCancellationReason": "Mudança de plano"  // Opcional
}
Neste caso, a data efetiva será calculada automaticamente usando a priorização de datas (trialEnd ou nextDueDate).

​
Cenário 2: Cancelamento em Data Específica

Para cancelar em uma data específica, forneça scheduledCancellationAt: 
{
  "cancelAtPeriodEnd": true,
  "scheduledCancellationAt": "2025-12-31",
  "scheduledCancellationReason": "Teste concluído"  // Opcional
}
A data fornecida terá prioridade sobre trialEnd e nextDueDate.

​
Cenário 3: Remover Agendamento

Para remover um cancelamento agendado e manter a assinatura ativa: 
{
  "cancelAtPeriodEnd": false
}
Quando o agendamento é removido, os campos scheduledCancellationAt e scheduledCancellationReason são limpos e as faturas da assinatura são restauradas ao valor original.

​
Regras de Negócio

​
Elegibilidade para Cancelamento Agendado

Uma assinatura pode ter cancelamento agendado quando:
  • Status é active, trialing, created ou unpaid
  • A assinatura não está já cancelada (canceled) ou expirada (expired)
  • A data de cancelamento (se especificada) é futura

​
Validações Implementadas

  • scheduledCancellationAt deve ser data futura: Se fornecido, deve ser uma data posterior à data atual
  • cancelAtPeriodEnd obrigatório com scheduledCancellationAt: Se scheduledCancellationAt for fornecido, cancelAtPeriodEnd deve ser true
  • Status elegível: A assinatura deve estar em um status que permita cancelamento agendado

​
Priorização de Datas

A priorização scheduledCancellationAt > trialEnd > nextDueDate garante comportamento previsível:
  • Assinatura em trial com data específica: Se scheduledCancellationAt for anterior a trialEnd, o cancelamento ocorrerá na data especificada (antes do fim do trial)
  • Assinatura sem trial: Se não houver trialEnd, usa nextDueDate
  • Data específica após próxima fatura: Se scheduledCancellationAt for após nextDueDate, o cancelamento ocorrerá na data especificada (pode incluir mais uma fatura)

​
Processamento Automático

O sistema processa automaticamente cancelamentos agendados diariamente. Quando a data efetiva de cancelamento chega, a assinatura é cancelada automaticamente e você receberá um webhook subscription.canceled notificando o cancelamento.
O processamento automático já está configurado e ativo em ambientes gerenciados pela Malga. Você pode monitorar os cancelamentos através dos webhooks subscription.canceled que são disparados quando cancelamentos agendados são efetivados.

​
Webhooks e Eventos

​
Evento: subscription.cancelation_scheduled

Disparado quando um cancelamento agendado é criado ou quando a data de cancelamento é atualizada. Veja a documentação completa em Webhooks de Subscription.

​
Evento: subscription.cancelation_scheduled_removed

Disparado quando um agendamento de cancelamento é removido (quando cancelAtPeriodEnd é definido como false). Veja a documentação completa em Webhooks de Subscription.

​
Evento: subscription.canceled

Disparado quando uma assinatura é cancelada, seja manualmente ou automaticamente pelo scheduler. Quando o cancelamento vem de um agendamento, o campo cancelAtPeriodEnd estará presente e definido como true no payload. Veja a documentação completa em Webhooks de Subscription.

​
Casos Especiais

​
Assinatura Vitalícia

Para assinaturas vitalícias (sem limite de faturas), o cancelamento agendado funciona normalmente:
  • O cancelamento ocorrerá na data efetiva calculada
  • Após cancelamento, a assinatura não gerará mais faturas

​
Assinatura com Número Limitado de Faturas

Para assinaturas com número limitado de faturas:
  • O campo cycles pode ser ajustado para refletir o número de faturas restantes até o cancelamento
  • Ao remover o agendamento (cancelAtPeriodEnd: false), o valor de cycles é restaurado

​
Assinatura em Trial

Assinaturas em trial podem ter cancelamento agendado:
  • Se scheduledCancellationAt não for fornecido, usa trialEnd como data efetiva
  • Se scheduledCancellationAt for fornecido, tem prioridade sobre trialEnd
  • O cancelamento pode ocorrer antes ou depois do fim do trial, dependendo da data especificada

​
Assinatura Unpaid com Retries

Assinaturas com status unpaid podem ter cancelamento agendado:
  • O cancelamento ocorrerá na data efetiva, mesmo que a assinatura esteja inadimplente
  • Se a assinatura for paga antes da data de cancelamento, o agendamento permanece ativo
  • Para remover o agendamento após pagamento, defina cancelAtPeriodEnd: false

​
Comportamento por Status

StatusPode Agendar CancelamentoComportamento
active✅ SimCancelamento ocorre na data efetiva
trialing✅ SimUsa trialEnd se scheduledCancellationAt não fornecido
created✅ SimCancelamento ocorre antes da primeira cobrança
unpaid✅ SimCancelamento ocorre na data efetiva
paused❌ NãoAssinatura pausada não pode ter cancelamento agendado
canceled❌ NãoAssinatura já cancelada
expired❌ NãoAssinatura já expirada

​
Faturas Pendentes

Quando uma assinatura tem cancelamento agendado e ainda possui faturas pendentes:
  • Faturas já agendadas (scheduled, pending, retrying) continuam sendo processadas normalmente
  • Faturas futuras após a data de cancelamento não serão geradas
  • A última fatura processada antes da data de cancelamento será a última fatura da assinatura

​
Integração com Outros Sistemas

​
Geração de Faturas

O sistema de geração de faturas respeita o cancelamento agendado:
  • Faturas são geradas normalmente até a data efetiva de cancelamento
  • Após a data efetiva, nenhuma nova fatura é gerada
  • Faturas pendentes na data de cancelamento são marcadas como canceled

​
Processamento de Pagamentos

Pagamentos continuam sendo processados normalmente até a data de cancelamento:
  • Cobranças agendadas antes da data de cancelamento são processadas
  • Cobranças agendadas após a data de cancelamento não são criadas
  • Se uma cobrança falhar antes da data de cancelamento, as retentativas continuam normalmente

​
Documentação Relacionada

​
Dicas Importantes

  • Use cancelamento agendado para melhorar a experiência do cliente: Permite que o cliente use o serviço até o fim do período pago
  • Monitore através de webhooks: Configure webhooks para receber notificações sobre agendamentos e cancelamentos
  • Verifique a data efetiva: Use a priorização de datas para entender quando o cancelamento ocorrerá
  • Remova agendamentos quando necessário: Se o cliente mudar de ideia, defina cancelAtPeriodEnd: false para remover o agendamento