Ciclo de Vida da Assinatura

Estados

draft → confirmed → trialing → active ↔ past_due → canceled
                                  ↕
                               paused

Estado	Descrição
draft	Rascunho. Pode ser editada livremente antes de ser confirmada
confirmed	Confirmada, aguardando ativação
trialing	Em período de trial gratuito
active	Ativa, gerando cobranças recorrentes
past_due	Com pagamento atrasado
paused	Pausada temporariamente (sem cobranças)
canceled	Cancelada (estado terminal)

Criando uma Assinatura

Para criar uma assinatura, informe:

Campo	Obrigatório	Descrição
Conta de cobrança	Sim	A conta do cliente que será cobrada
Plano	Não	Plano pré-configurado (ou itens avulsos)
Ciclo de cobrança	Sim	monthly, quarterly, semiannual ou annual
Método de cobrança	Sim	charge_automatically, manual_charge ou manual_invoice
Período de trial	Não	0 a 90 dias de teste gratuito
Código de desconto	Não	Desconto a ser aplicado
Itens	Não	Produtos, preços e quantidades (se não usar plano)
Empresa	Não	Empresa emissora (para multi-empresa)

Fluxo de Criação

1. A assinatura é criada no status draft
2. Os itens são criados a partir dos itens fornecidos ou dos itens do plano
3. O uso do código de desconto é incrementado (se fornecido)
4. Um evento subscription.db.created é emitido

Confirmação e Ativação

Confirmar (draft → confirmed)

Confirma a assinatura, opcionalmente criando a primeira fatura.

Ativar (draft/confirmed → trialing/active)

• Se tiver período de trial: status muda para trialing, com trial_start e trial_end definidos
• Se não tiver trial: status muda diretamente para active
• Define as datas do período de cobrança (current_period_start, current_period_end)

Preview da Ativação

Antes de ativar, é possível visualizar:

• Data de início, se haverá trial, duração do trial
• Datas do período de cobrança
• Data da primeira fatura
• Totais de setup e recorrentes

Renovação

A renovação é automática via worker diário (00:00 UTC):

1. Busca assinaturas ativas com currentPeriodEnd ≤ agora
2. Se cancelAtPeriodEnd = true: cancela a assinatura
3. Caso contrário: avança para o próximo período de cobrança
4. Usa lock otimista para prevenir renovações duplicadas

Cálculo dos Períodos

Ciclo	Duração
monthly	+1 mês
quarterly	+3 meses
semiannual	+6 meses
annual	+1 ano

Cancelamento

Cancelar no Fim do Período (cancelAtPeriodEnd: true)

• Define a flag cancel_at_period_end
• A assinatura continua ativa até o fim do período atual
• Na renovação, o status muda para canceled
• Pode ser revertido antes da data de cancelamento

Cancelar Imediatamente (cancelAtPeriodEnd: false)

• Status muda para canceled imediatamente
• A data de cancelamento é registrada
• O motivo do cancelamento é armazenado

Reverter para Confirmado

Assinaturas ativas podem ser revertidas para confirmed para permitir edição antes de reativar. Útil para corrigir erros antes da próxima renovação.

Deleção

Apenas assinaturas em draft, confirmed ou canceled podem ser deletadas, e somente se não houver faturas com pagamentos.

Cálculo do MRR

O MRR (Monthly Recurring Revenue) é calculado normalizando o valor total para mensal:

Ciclo	Fórmula
monthly	Total dos itens
quarterly	Total ÷ 3
semiannual	Total ÷ 6
annual	Total ÷ 12

Eventos Emitidos

Evento	Quando
subscription.db.created	Assinatura criada
subscription.confirmed	Confirmada
subscription.activated	Ativada
subscription.renewed	Renovada
subscription.paused	Pausada
subscription.resumed	Retomada
subscription.canceled	Cancelada
subscription.pending_cancellation	Marcada para cancelar no fim do período
subscription.plan_changed	Plano alterado
subscription_status_changed	Qualquer mudança de status