Flexible catalog, from product to subscription.
Product → Price → Plan → Subscription. Multiple prices per product (cycle, currency, scheme), fixed or metered add-ons, percentage/fixed coupons, promotional credits.
Feature
4
hierarchy levels
∞
prices per product
4
product types
metered
natively supported
Levels modeled in Prisma
Product
What you sell. ProductType: base, addon_fixed, addon_quantity, metered. Links to ServiceItem for correct taxation.
- Unique slug per organization
- Parent/child hierarchy
- ProductGroup for organization
- selfServiceEditable in portal
Price
How much it costs in one cycle. A product can have N prices (monthly, annual, promotional, by currency).
- BillingScheme: per_unit, tiered, volume, package
- UsageType: licensed | metered
- RecurringInterval: month | year
- unitAmountSubcents (÷10000)
Plan
Combination of products + prices offered to the customer. Plan → N PlanItems → Product + Price.
- Trial in days per plan
- Available BillingCycles configurable
- Visibility: public | private
- PlanGroup for landing
Subscription
Customer's contract of the plan. Generates SubscriptionItems mirroring PlanItems but editable.
- Quantity override per item
- Optional add-ons
- History in SubscriptionVersion
What you can do
Multi-Product Catalog
Unlimited products organized in groups. Each product with multiple prices per cycle or currency.
- ProductGroup for landing pages
- ProductType: base, addon (fixed/quantity), metered
- Unique slug + customMetadata
Prices by Cycle
Same product with different prices per cycle. Incentivize longer cycles with progressive discounts.
- Monthly, quarterly, semi-annual, annual
- Optional setup fee (setupAmountSubcents)
- Excess amount for metered overage
Tiered Pricing
BillingScheme tiered, volume, package. Support for progressive tiers and volume discounts.
- JSON tiers: up to X = R$ Y, then Z
- Mode graduated or volume
- Package: charges per package of N units
Metered Billing
UsageType metered + UsageRecord records consumption. Usage-sync worker (every hour) consolidates external metrics.
- UsageRecord with idempotency key
- Daily and monthly snapshots
- Billing at end of cycle
Promotional Coupons
Coupon with DiscountType percentage or fixed_amount. Usage limits, validity, restrictions per product/plan.
- Global usageLimit + usageLimitPerUser
- minPurchaseCents + maxDiscountCents
- Validity validFrom / validUntil
- AppliesTo / Excludes JSON
Credit System
CreditType: promotional, adjustment, refund, manual. CreditApplication tracked per invoice. Automatic application on next invoice.
- amountRemainingCents controls balance
- Optional ExpiresAt
- Monthly credit-expiration worker
Discount Codes
DiscountCode separate from Coupon. Duration once, repeating, forever. Useful for promotions by shareable code.
- percentOff or amountOffCents
- durationInMonths for repeating
- maxRedemptions + timesRedeemed
Plan Change with Rules
PlanChangeRule per origin → destination pair. Defines proration method, timing, bonus discount, bonus days.
- ChangeType: upgrade, downgrade, lateral
- Priority + isActive
- Custom message shown in portal
Create a plan via 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": "Pro Plan",
"slug": "pro-plan",
"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": "Pro Plan",
"slug": "pro-plan",
"status": "active",
"default_billing_cycle": "monthly",
"available_billing_cycles": ["monthly", "annual"]
}
}