> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancelamento Agendado

> Cancele assinaturas ao final do período atual com agendamento automático

# 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`:

```json theme={null}
{
  "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)

```mermaid theme={null}
flowchart TD
    A[Cancelamento Agendado Ativado] --> B{scheduledCancellationAt definido?}
    B -->|Sim| C[Usar scheduledCancellationAt]
    B -->|Não| D{Assinatura em trial?}
    D -->|Sim| E[Usar trialEnd]
    D -->|Não| F[Usar nextDueDate]
    C --> G[Data Efetiva de Cancelamento]
    E --> G
    F --> G
```

### 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`.

```mermaid theme={null}
stateDiagram-v2
    [*] --> active : Assinatura criada
    active --> active : cancelAtPeriodEnd = true
    active --> canceled : Data efetiva chegou (scheduler)
    trialing --> trialing : cancelAtPeriodEnd = true
    trialing --> canceled : Data efetiva chegou (scheduler)
```

## 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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

<Info>
  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.
</Info>

## 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](/documentations/more/recurrence/engine/webhooks#evento-subscriptioncancelation_scheduled).

### 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](/documentations/more/recurrence/engine/webhooks#evento-subscriptioncancelation_scheduled_removed).

### 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](/documentations/more/recurrence/engine/webhooks#evento-subscriptioncanceled).

## 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

| Status     | Pode Agendar Cancelamento | Comportamento                                             |
| ---------- | ------------------------- | --------------------------------------------------------- |
| `active`   | ✅ Sim                     | Cancelamento ocorre na data efetiva                       |
| `trialing` | ✅ Sim                     | Usa `trialEnd` se `scheduledCancellationAt` não fornecido |
| `created`  | ✅ Sim                     | Cancelamento ocorre antes da primeira cobrança            |
| `unpaid`   | ✅ Sim                     | Cancelamento ocorre na data efetiva                       |
| `paused`   | ❌ Não                     | Assinatura pausada não pode ter cancelamento agendado     |
| `canceled` | ❌ Não                     | Assinatura já cancelada                                   |
| `expired`  | ❌ Não                     | Assinatura 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

* [Gerenciando suas assinaturas](/documentations/more/recurrence/engine/managing) - Operações gerais de gerenciamento
* [Webhooks de Subscription](/documentations/more/recurrence/engine/webhooks) - Eventos e notificações
* [Atualizar Assinatura](/api-reference/subscriptions/atualizar-assinatura) - Referência de API para atualização
* [Cancelar Assinatura](/api-reference/subscriptions/cancelar-assinatura) - Referência de API para cancelamento imediato

## 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