Ciclo de vida completo das assinaturas, com proration nativo.
7 estados, 4 ciclos, 3 métodos de cobrança. Trial, upgrade/downgrade, pausa, cancelamento agendado. Versionamento histórico em cada mudança.
Funcionalidade
7
estados de assinatura
4
ciclos de faturamento
24/7
processamento automático
100%
mudanças versionadas
Estados modelados em SubscriptionStatus
Cada transição é registrada como SubscriptionVersion (hybrid SCD type-2) para auditoria completa.
Draft
Criada via dashboard mas ainda não confirmada. Sem cobrança.
- Transições: → confirmed (confirmação manual)
Confirmed
Pronta para iniciar. Awaiting trial start ou primeira cobrança.
- Transições: → trialing (com trial) | → active (sem trial)
Trialing
Período gratuito antes da primeira cobrança. Trial sem cartão suportado.
- Transições: → active (fim do trial) | → canceled (cancelamento durante trial)
Active
Cobrança recorrente ativa. Worker subscription-renewal (diário 00:00 UTC) renova o ciclo.
- Transições: → past_due (pagamento falha) | → paused | → canceled
Past Due
Pagamento falhou. Worker payment-retry tenta a cada 6h. Worker suspension-check suspende após período de graça.
- Transições: → active (pagamento OK) | → canceled (todas tentativas falharam)
Paused
Pausa do cliente (pauseCollection armazena razão e timestamp). Sem cobrança até retomada.
- Transições: → active (cliente retoma)
Canceled
Encerrada. cancelAtPeriodEnd permite cancelamento agendado no fim do ciclo.
- Estado final
O que você pode fazer
Ciclos de Faturamento
Defina o ciclo por plano ou por assinatura. billing_cycle_anchor ancora a data de renovação.
- Mensal, trimestral, semestral, anual
- Anchor configurável (não precisa começar dia 1)
- current_period_start e current_period_end calculados
Trial Flexível
Trial em dias, com ou sem cartão. Notificação automática antes do fim via worker trial-ending (diário 09:00 UTC).
- trial_period_days por plano ou override por assinatura
- Conversão automática para active
- Cancelamento durante trial sem cobrança
Upgrade/Downgrade com Proration
3 comportamentos: create_prorations (default), none, always_invoice. Fórmula: (plan_value / days_in_cycle) × days_remaining.
- Preview antes de confirmar (sem efeito colateral)
- Upgrade imediato, downgrade end-of-period (configurável)
- Crédito gerado em downgrade (creditOnDowngrade)
Mudança de Itens (PlanChange)
Mudanças de plano são tracked como PlanChange + SubscriptionItemChange. Idempotência via Idempotency-Key header.
- Versionamento completo
- Regras por par de planos (PlanChangeRule)
- Promoção scheduled → done por worker dedicado
Pausa e Retomada
pauseCollection JSON armazena razão, data, regra de retomada. allowPause configurável por assinatura.
- Pausa indefinida ou com data de retomada
- Histórico completo no portal do cliente
- Webhook subscription.paused / subscription.resumed
Métodos de Cobrança
CollectionMethod controla geração e cobrança das faturas.
- charge_automatically: tudo automático (cartão)
- manual_charge: fatura automática, cobrança manual (boleto/PIX)
- manual_invoice: tudo manual (one-off)
Cancelamento Inteligente
cancel_at_period_end agenda cancelamento para fim do ciclo. canceled_at + cancellationReason registrados.
- Cancelamento imediato ou agendado
- Razão livre para análise de churn
- Webhook + AuditLog
Renovação Automática
renewalSettings JSON controla auto-renew, end_of_commitment ou prompt. Worker subscription-renewal processa diariamente.
- Renovação 100% automatizada
- Suporte a commitment (12 meses, 24 meses)
- Idempotência por subscription + period
Criar assinatura via API
bash
curl -X POST https://api.billing.kobana.com.br/v1/subscriptions \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"billing_account_id": "ba_abc123",
"plan_id": "plan_growth_monthly",
"trial_period_days": 14,
"collection_method": "charge_automatically",
"metadata": { "source": "checkout", "campaign": "q3-2026" }
}'response
{
"id": "sub_xyz789",
"status": "trialing",
"billing_cycle": "monthly",
"trial_end": "2026-06-20T00:00:00Z",
"current_period_start": "2026-06-06T00:00:00Z",
"current_period_end": "2026-07-06T00:00:00Z",
"recurring_amount_cents": 29900,
"items": [
{ "id": "si_1", "product_id": "prod_platform", "quantity": 1 }
]
}