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 producto con 2 precios
bash
curl -X POST https://api.billing.kobana.com.br/v1/products \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Plan Pro",
"slug": "plan-pro",
"product_type": "base",
"service_item_id": "svc_saas",
"prices": [
{
"name": "Pro Mensual",
"unit_amount_subcents": 7990000,
"recurring_interval": "month",
"interval_count": 1
},
{
"name": "Pro Anual",
"unit_amount_subcents": 79900000,
"recurring_interval": "year",
"interval_count": 1
}
]
}'response
{
"id": "prod_xyz789",
"name": "Plan Pro",
"prices": [
{ "id": "price_monthly", "unit_amount_subcents": 7990000, "recurring_interval": "month" },
{ "id": "price_annual", "unit_amount_subcents": 79900000, "recurring_interval": "year" }
]
}