Catálogo flexível, do produto à assinatura.
Product → Price → Plan → Subscription. Múltiplos preços por produto (ciclo, moeda, scheme), addons fixos ou metered, cupons percentage/fixed, créditos promocionais.
Funcionalidade
4
níveis de hierarquia
∞
preços por produto
4
tipos de produto
metered
suportado nativamente
Níveis modelados em Prisma
Product
O que você vende. ProductType: base, addon_fixed, addon_quantity, metered. Vincula a ServiceItem para tributação correta.
- Slug único por organização
- Hierarquia parent/child
- ProductGroup para organização
- selfServiceEditable no portal
Price
Quanto custa em um ciclo. Um produto pode ter N preços (mensal, anual, promocional, por moeda).
- BillingScheme: per_unit, tiered, volume, package
- UsageType: licensed | metered
- RecurringInterval: month | year
- unitAmountSubcents (÷10000)
Plan
Combinação de produtos + preços ofertada ao cliente. Plan → N PlanItems → Product + Price.
- Trial em dias por plano
- BillingCycles disponíveis configurável
- Visibility: public | private
- PlanGroup para landing
Subscription
Contratação do plano por um cliente. Gera SubscriptionItems espelhando PlanItems mas editáveis.
- Override de quantidade por item
- Addons opcionais
- Histórico em SubscriptionVersion
O que você pode fazer
Catálogo Multi-Produto
Produtos ilimitados organizados em groups. Cada produto com vários preços por ciclo ou moeda.
- ProductGroup para landing pages
- ProductType: base, addon (fixo/quantity), metered
- Slug único + customMetadata
Preços por Ciclo
Mesmo produto com preços diferentes por ciclo. Incentive ciclos longos com descontos progressivos.
- Mensal, trimestral, semestral, anual
- Setup fee opcional (setupAmountSubcents)
- Excess amount para metered overage
Tiered Pricing
BillingScheme tiered, volume, package. Suporte a faixas progressivas e desconto por volume.
- Tiers JSON: até X = R$ Y, depois Z
- Mode graduated ou volume
- Package: cobra por pacote de N unidades
Metered Billing
UsageType metered + UsageRecord registra consumo. Worker usage-sync (a cada hora) consolida métricas externas.
- UsageRecord com idempotency key
- Snapshots diários e mensais
- Cobrança no fim do ciclo
Cupons Promocionais
Coupon com DiscountType percentage ou fixed_amount. Limites de uso, validade, restrições por produto/plano.
- usageLimit global + usageLimitPerUser
- minPurchaseCents + maxDiscountCents
- Validade validFrom / validUntil
- AppliesTo / Excludes JSON
Sistema de Créditos
CreditType: promotional, adjustment, refund, manual. CreditApplication tracked por fatura. Aplicação automática na próxima fatura.
- amountRemainingCents controla saldo
- ExpiresAt opcional
- Worker credit-expiration (mensal)
Discount Codes
DiscountCode separado de Coupon. Duration once, repeating, forever. Útil para promoções por código compartilhável.
- percentOff ou amountOffCents
- durationInMonths para repeating
- maxRedemptions + timesRedeemed
Mudança de Plano com Regras
PlanChangeRule por par origem → destino. Define proration method, timing, desconto bônus, bonus days.
- ChangeType: upgrade, downgrade, lateral
- Priority + isActive
- Mensagem customizada exibida no portal
Criar produto com 2 preços
bash
curl -X POST https://api.billing.kobana.com.br/v1/products \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Plano Pro",
"slug": "plano-pro",
"product_type": "base",
"service_item_id": "svc_saas",
"prices": [
{
"name": "Pro Mensal",
"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": "Plano Pro",
"prices": [
{ "id": "price_monthly", "unit_amount_subcents": 7990000, "recurring_interval": "month" },
{ "id": "price_annual", "unit_amount_subcents": 79900000, "recurring_interval": "year" }
]
}