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