Catálogo flexible, del producto a la suscripción.
Product → Price → Plan → Subscription. Múltiples precios por producto (ciclo, moneda, scheme), addons fijos o metered, cupones percentage/fixed, créditos promocionales.
Funcionalidad
4
niveles de jerarquía
∞
precios por producto
4
tipos de producto
metered
soportado nativamente
Niveles modelados en Prisma
Product
Lo que vendes. ProductType: base, addon_fixed, addon_quantity, metered. Vincula a ServiceItem para tributación correcta.
- Slug único por organización
- Jerarquía parent/child
- ProductGroup para organización
- selfServiceEditable en portal
Price
Cuánto cuesta en un ciclo. Un producto puede tener N precios (mensual, anual, promocional, por moneda).
- BillingScheme: per_unit, tiered, volume, package
- UsageType: licensed | metered
- RecurringInterval: month | year
- unitAmountSubcents (÷10000)
Plan
Combinación de productos + precios ofertada al cliente. Plan → N PlanItems → Product + Price.
- Trial en días por plan
- BillingCycles disponibles configurable
- Visibility: public | private
- PlanGroup para landing
Subscription
Contratación del plan por un cliente. Genera SubscriptionItems espejando PlanItems pero editables.
- Override de cantidad por ítem
- Addons opcionales
- Historial en SubscriptionVersion
Qué puedes hacer
Catálogo Multi-Producto
Productos ilimitados organizados en groups. Cada producto con varios precios por ciclo o moneda.
- ProductGroup para landing pages
- ProductType: base, addon (fijo/quantity), metered
- Slug único + customMetadata
Precios por Ciclo
Mismo producto con precios diferentes por ciclo. Incentiva ciclos largos con descuentos progresivos.
- Mensual, trimestral, semestral, anual
- Setup fee opcional (setupAmountSubcents)
- Excess amount para metered overage
Tiered Pricing
BillingScheme tiered, volume, package. Soporte a rangos progresivos y descuento por volumen.
- Tiers JSON: hasta X = R$ Y, después Z
- Mode graduated o volume
- Package: cobra por paquete de N unidades
Metered Billing
UsageType metered + UsageRecord registra consumo. Worker usage-sync (cada hora) consolida métricas externas.
- UsageRecord con idempotency key
- Snapshots diarios y mensuales
- Cobro al fin del ciclo
Cupones Promocionales
Coupon con DiscountType percentage o fixed_amount. Límites de uso, validez, restricciones por producto/plan.
- usageLimit global + usageLimitPerUser
- minPurchaseCents + maxDiscountCents
- Validez validFrom / validUntil
- AppliesTo / Excludes JSON
Sistema de Créditos
CreditType: promotional, adjustment, refund, manual. CreditApplication registrado por factura. Aplicación automática en la próxima factura.
- amountRemainingCents controla saldo
- ExpiresAt opcional
- Worker credit-expiration (mensual)
Discount Codes
DiscountCode separado de Coupon. Duration once, repeating, forever. Útil para promociones por código compartible.
- percentOff o amountOffCents
- durationInMonths para repeating
- maxRedemptions + timesRedeemed
Cambio de Plan con Reglas
PlanChangeRule por par origen → destino. Define proration method, timing, descuento bonus, bonus days.
- ChangeType: upgrade, downgrade, lateral
- Priority + isActive
- Mensaje personalizado mostrado en portal
Crear un plan vía API
bash
curl -X POST https://api.billing.kobana.com.br/v1/plans \
-H "Authorization: Bearer $KOBANA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Plan Pro",
"slug": "plan-pro",
"status": "active",
"trial_period_days": 14,
"default_billing_cycle": "monthly",
"available_billing_cycles": ["monthly", "annual"],
"items": [
{ "product_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "price_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e", "quantity": 1 }
]
}'response
{
"data": {
"id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"name": "Plan Pro",
"slug": "plan-pro",
"status": "active",
"default_billing_cycle": "monthly",
"available_billing_cycles": ["monthly", "annual"]
}
}