Hybrid billing with Entitlements
Entitlements are currently in preview. Please contact our support team for access.
Combine traditional fixed-fee pricing with bundled credit entitlements to mix recurring revenue with usage-based overages seamlessly.
Hybrid billing lets you charge a monthly subscription fee while granting customers a fixed credit allowance each billing cycle. When customers exceed their included credits, they pay for additional usage at your defined overage rates.
This model works for AI products where you want predictable recurring revenue while maintaining the flexibility of usage-based pricing.
When hybrid billing fits
Hybrid billing works when:
- You want predictable monthly revenue from subscriptions
- Customers need a base credit allowance included with their plan
- You charge for usage beyond the included allowance
- Different plan tiers provide different credit allocations
Common examples include SaaS products with tiered plans ($20/month with 1,000 credits included), developer tools with base usage quotas, and AI platforms with plan-based credit allowances.
How entitlements work
Entitlements are "right-to-use" grants that decouple service access from direct credit purchases. While a commitment represents pre-funded balance intended for consumption, an entitlement represents a bundled allocation granted at the product level.
When you subscribe a customer to a product with entitlements, Credyt automatically:
- Grants the specified credit amount to the customer's wallet
- Refreshes this allowance according to your defined schedule (daily, monthly, etc.)
- Tracks consumption against the entitlement balance
- Charges overage fees when credits are exhausted
Entitlement types
Entitlements are categorized by their accounting purpose, which dictates how Credyt handles revenue recognition and cost tracking.
Bundled entitlements
Credits included as a feature of a fixed-fee plan. The subscription fee is recognized ratably over the billing cycle, while the credit value is generally assigned a revenue basis of $0 (the value is captured by the recurring fee).
Example: "$20/month includes 1,000 credits"
Promotional entitlements
Free credits granted to incentivize signups, login streaks, or referrals. No revenue is recognized. These track a cost basis to record marketing expense when consumed.
Example: "$2 free daily credits for new users"
Creating a hybrid billing product
Entitlements can grant credits in either fiat currency or custom assets, for example credits, tokens or minutes. To use custom assets, first create the asset and define the buy rate, then create a product that uses the asset.
Step 1: Create a custom credit asset
Before creating your product, define a custom asset for your credits. This asset has a buy rate that determines how much customers pay when purchasing additional credits.
In this example, we create a CREDIT asset where each credit costs $0.05 (or inversely, $1.00 buys 20 credits).
{
"code": "CREDIT",
"name": "Credits",
"precision": 0,
"symbol": "⭐",
"label": "CR",
"rates": [
{
"source": "USD",
"rate": 0.05
}
]
}
Step 2: Create the product with entitlements
Now create a product that grants bundled credits and charges for actual usage, for example "AI Image Generations".
Example: monthly subscription with bundled credits
This example creates a Premium Plan that costs $20/month and includes 1,000 credits that refresh monthly. The product charges 10 credits per image generation. When customers run out of bundled credits, they can purchase more at the $0.05 rate defined in the asset.
{
"name": "Premium Plan",
"code": "premium_monthly_01",
"description": "Standard monthly subscription with included credit allowance.",
"entitlements": [
{
"name": "Monthly Credit Allowance",
"asset": "CREDIT",
"amount": 1000,
"purpose": "bundled",
"refresh": {
"interval": "month",
"strategy": "expire_and_replace"
},
"accounting": {
"revenue_basis": 0,
"cost_basis": "auto"
}
}
],
"prices": [
{
"name": "Monthly Subscription Fee",
"type": "fixed",
"billing_model": {
"type": "recurring",
"recurring": {
"interval": "month"
}
},
"pricing": [
{
"asset": "USD",
"values": [
{
"unit_price": 20
}
]
}
]
},
{
"name": "Image Generation",
"type": "usage_based",
"billing_model": {
"type": "real_time"
},
"usage_calculation": {
"event_type": "image_generated",
"usage_type": "unit"
},
"pricing": [
{
"asset": "CREDIT",
"values": [
{
"unit_price": 10
}
]
}
]
}
],
"publish": true
}
With this configuration:
- Customer pays $20/month for the subscription
- Receives 1,000 credits each month
- Each image generation costs 10 credits
- When credits are exhausted, customer can purchase more at $0.05/credit
- Customer can generate 100 images with their included credits
Example: free tier with promotional credits
This example models a Free Plan that costs $0 but includes a recurring daily entitlement of 50 credits. Each image generation costs 5 credits.
{
"name": "Free Tier Product",
"code": "free_tier_01",
"entitlements": [
{
"name": "Daily Reward",
"asset": "CREDIT",
"amount": 50,
"purpose": "promotion",
"refresh": {
"interval": "day",
"strategy": "expire_and_replace"
},
"accounting": {
"revenue_basis": 0.0,
"cost_basis": "auto"
}
}
],
"prices": [
{
"name": "Image Generation",
"type": "usage_based",
"billing_model": {
"type": "real_time"
},
"usage_calculation": {
"event_type": "image_generated",
"usage_type": "unit"
},
"pricing": [
{
"asset": "CREDIT",
"values": [
{
"unit_price": 5
}
]
}
]
}
],
"publish": true
}
With this configuration:
- No monthly fee
- Customer receives 50 free credits daily
- Each image generation costs 5 credits
- Customer can generate 10 images per day with free credits
- When credits are exhausted, customer can purchase more at $0.05/credit
Entitlement configuration
| Field | Type | Description |
|---|---|---|
purpose | Enum | Defines the accounting track: bundled or promotion |
revenue_basis | Decimal | Amount of revenue earned per unit used. Defaults to 0.00 for bundled/promotional grants |
cost_basis | Decimal | Internal cost to expense per unit used. Defaults to auto to follow the usage price |
refresh | Object | Defines the refresh lifecycle (e.g. refresh daily and do not rollover unused credits) |
priority_score | Integer | Dictates consumption order. Lower scores are burned first |
Refresh strategies
The refresh object controls how entitlements replenish:
interval: How often credits refresh (day,month, etc.)strategy: What happens to unused creditsexpire_and_replace: Unused credits expire, new allocation grantedrollover: Unused credits carry forward (up to defined limits)
Consumption and priority rules
By default, Credyt consumes grants in the order they expire (FIFO). However, you can assign a higher priority_score to promotional grants to ensure free credits are exhausted before customers touch bundled or paid balances.
Example consumption order
- Promotional credits (highest priority)
- Bundled subscription credits
- Purchased credits or pay-as-you-go
This ensures customers use their free promotional credits first, then their included subscription credits, before incurring overage charges.
Revenue recognition
When a bundled entitlement has a revenue_basis > 0, Credyt manages revenue recognition:
- Usage: Revenue is recognized unit-by-unit as consumed
- Expiry: Remaining balance at period end moves from contract liability to revenue as breakage
For bundled entitlements with revenue_basis: 0.00, the subscription fee is recognized ratably over the billing cycle regardless of credit consumption.
Subscribing customers
Once you've created your hybrid product, subscribe customers by referencing the product code when creating the customer:
{
"name": "John Doe",
"external_id": "18991",
"email": "j.doe@gmail.com",
"subscriptions": [
{
"products": [
{
"code": "premium_monthly_01"
}
]
}
]
}
When the subscription activates, Credyt automatically grants the entitlement credits to the customer's wallet and begins tracking consumption.