Ciclo de vida completo de las suscripciones, con prorrateo nativo.
7 estados, 4 ciclos, 3 métodos de cobro. Trial, upgrade/downgrade, pausa, cancelación programada. Versionado histórico en cada cambio.
Funcionalidad
7
estados de suscripción
4
ciclos de facturación
24/7
procesamiento automático
100%
cambios versionados
Estados modelados en SubscriptionStatus
Cada transición se registra como SubscriptionVersion (hybrid SCD type-2) para auditoría completa.
Draft
Creada vía dashboard pero aún no confirmada. Sin cobro.
- Transiciones: → confirmed (confirmación manual)
Confirmed
Lista para iniciar. Awaiting trial start o primer cobro.
- Transiciones: → trialing (con trial) | → active (sin trial)
Trialing
Período gratuito antes del primer cobro. Trial sin tarjeta soportado.
- Transiciones: → active (fin del trial) | → canceled (cancelación durante trial)
Active
Cobro recurrente activo. Worker subscription-renewal (diario 00:00 UTC) renueva el ciclo.
- Transiciones: → past_due (pago falla) | → paused | → canceled
Past Due
El pago falló. Worker payment-retry reintenta cada 6h. Worker suspension-check suspende después del período de gracia.
- Transiciones: → active (pago OK) | → canceled (todos los intentos fallaron)
Paused
Pausa del cliente (pauseCollection almacena razón y timestamp). Sin cobro hasta reanudación.
- Transiciones: → active (cliente reanuda)
Canceled
Finalizada. cancelAtPeriodEnd permite cancelación programada al fin del ciclo.
- Estado final
Qué puedes hacer
Ciclos de Facturación
Define el ciclo por plan o por suscripción. billing_cycle_anchor ancla la fecha de renovación.
- Mensual, trimestral, semestral, anual
- Anchor configurable (no necesita empezar el día 1)
- current_period_start y current_period_end calculados
Trial Flexible
Trial en días, con o sin tarjeta. Notificación automática antes del fin vía worker trial-ending (diario 09:00 UTC).
- trial_period_days por plan o override por suscripción
- Conversión automática a active
- Cancelación durante trial sin cobro
Upgrade/Downgrade con Prorrateo
3 comportamientos: create_prorations (default), none, always_invoice. Fórmula: (plan_value / days_in_cycle) × days_remaining.
- Vista previa antes de confirmar (sin efecto colateral)
- Upgrade inmediato, downgrade end-of-period (configurable)
- Crédito generado en downgrade (creditOnDowngrade)
Cambio de Ítems (PlanChange)
Los cambios de plan se registran como PlanChange + SubscriptionItemChange. Idempotencia vía Idempotency-Key header.
- Versionado completo
- Reglas por par de planes (PlanChangeRule)
- Promoción scheduled → done por worker dedicado
Pausa y Reanudación
pauseCollection JSON almacena razón, fecha, regla de reanudación. allowPause configurable por suscripción.
- Pausa indefinida o con fecha de reanudación
- Historial completo en el portal del cliente
- Webhook subscription.paused / subscription.resumed
Métodos de Cobro
CollectionMethod controla la generación y cobro de las facturas.
- charge_automatically: todo automático (tarjeta)
- manual_charge: factura automática, cobro manual (boleto/PIX)
- manual_invoice: todo manual (one-off)
Cancelación Inteligente
cancel_at_period_end programa la cancelación para fin del ciclo. canceled_at + cancellationReason registrados.
- Cancelación inmediata o programada
- Razón libre para análisis de churn
- Webhook + AuditLog
Renovación Automática
renewalSettings JSON controla auto-renew, end_of_commitment o prompt. Worker subscription-renewal procesa diariamente.
- Renovación 100% automatizada
- Soporte a commitment (12 meses, 24 meses)
- Idempotencia por subscription + period
Crear suscripción vía 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 }
]
}