credit-based-billing

仓库: dodopayments/skills
安装量: 38
排名: #18656

安装

npx skills add https://github.com/dodopayments/skills --skill credit-based-billing

Dodo Payments Credit-Based Billing Reference: docs.dodopayments.com/features/credit-based-billing Grant customers a balance of credits (API calls, tokens, compute units, or any custom metric) and deduct from that balance as they consume your service. Overview Credit-based billing lets you: Issue credits with subscriptions, one-time purchases, or via API Deduct automatically via usage meters or manually via API Configure rollover to carry unused credits forward Handle overage when credits run out mid-cycle Set expiration rules per credit entitlement Track everything via a full audit ledger Credits work across all product types: subscriptions, one-time purchases, and usage-based billing. Core Concepts Credit Types Type Description Best For Custom Unit Your own metric (tokens, API calls, compute hours) with configurable precision (0–3 decimals) API calls, AI tokens, compute hours, messages Fiat Credits Real currency value (USD, EUR, etc.) that depletes as customers use your service Prepaid balances, promotional credits, compensation Credit Lifecycle Credits Issued — Granted on purchase (subscription cycle or one-time) or via API Credits Consumed — Deducted via meter events or manual API calls Credits Expire or Roll Over — At cycle end, unused credits expire or carry forward Overage Handling — If balance hits zero, overage is forgiven, billed, or carried as deficit Grant Sources Source Description Subscription Credits issued each billing cycle One-Time Credits issued with a one-time payment API Credits granted manually via API or dashboard Rollover Credits carried over from a previous billing cycle Quick Start 1. Create a Credit Entitlement import DodoPayments from 'dodopayments' ; const client = new DodoPayments ( { bearerToken : process . env . DODO_PAYMENTS_API_KEY , } ) ; const credit = await client . creditEntitlements . create ( { name : 'API Credits' , credit_type : 'custom_unit' , unit_name : 'API Calls' , precision : 0 , expiry_duration : 30 , // days rollover_enabled : false , allow_overage : false , } ) ; 2. Attach Credits to a Product In Dashboard → Products → Create/Edit Product → Entitlements → Attach Credits: Select the credit entitlement Set credits issued per billing cycle (subscriptions) or total (one-time) Configure trial credits, proration, low balance threshold 3. Create Checkout with Credit Product const session = await client . checkoutSessions . create ( { product_cart : [ { product_id : 'prod_ai_pro_plan' , // Product with credits attached quantity : 1 , } ] , customer : { email : 'customer@example.com' } , return_url : 'https://yourapp.com/success' , } ) ; // Redirect to session.checkout_url 4. Deduct Credits via Usage Events // Meter linked to credit entitlement deducts automatically await client . usageEvents . ingest ( { events : [ { event_id : gen_ ${ Date . now ( ) } _ ${ crypto . randomUUID ( ) } , customer_id : 'cus_abc123' , event_name : 'ai.generation' , timestamp : new Date ( ) . toISOString ( ) , metadata : { model : 'gpt-4' , tokens : '1500' } } ] } ) ; 5. Check Balance const balance = await client . creditEntitlements . balances . get ( 'cent_credit_id' , 'cus_abc123' ) ; console . log ( Available: ${ balance . available_balance } ) ; console . log ( Overage: ${ balance . overage_balance } ) ; API Reference Credit Entitlement CRUD Operation Method Endpoint Create POST /credit-entitlements List GET /credit-entitlements Get GET /credit-entitlements/{id} Update PATCH /credit-entitlements/{id} Delete DELETE /credit-entitlements/{id} Undelete POST /credit-entitlements/{id}/undelete Balance & Ledger Operations Operation Method Endpoint List All Balances GET /credit-entitlements/{id}/balances Get Customer Balance GET /credit-entitlements/{id}/balances/{customer_id} Create Ledger Entry POST /credit-entitlements/{id}/balances/{customer_id}/ledger-entries List Customer Ledger GET /credit-entitlements/{id}/balances/{customer_id}/ledger List Customer Grants GET /credit-entitlements/{id}/balances/{customer_id}/grants Implementation Examples TypeScript/Node.js Create Credit Entitlement import DodoPayments from 'dodopayments' ; const client = new DodoPayments ( { bearerToken : process . env . DODO_PAYMENTS_API_KEY ! , } ) ; // Custom unit credit (AI tokens) const tokenCredit = await client . creditEntitlements . create ( { name : 'AI Tokens' , credit_type : 'custom_unit' , unit_name : 'tokens' , precision : 0 , expiry_duration : 30 , rollover_enabled : true , max_rollover_percentage : 25 , rollover_timeframe : 'month' , max_rollover_count : 3 , allow_overage : true , overage_limit : 50000 , price_per_unit : 0.001 , overage_behavior : 'bill_overage_at_billing' , } ) ; // Fiat credit (USD balance) const usdCredit = await client . creditEntitlements . create ( { name : 'Platform Credits' , credit_type : 'fiat' , unit_currency : 'USD' , expiry_duration : 90 , rollover_enabled : false , allow_overage : false , } ) ; Manual Credit/Debit via Ledger Entry // Grant credits manually (e.g., promotional bonus) await client . creditEntitlements . balances . createLedgerEntry ( 'cent_credit_id' , 'cus_abc123' , { type : 'credit' , amount : '500' , description : 'Welcome bonus - 500 free API credits' , idempotency_key : welcome_bonus_ ${ customerId } , } ) ; // Debit credits manually (e.g., service compensation deduction) await client . creditEntitlements . balances . createLedgerEntry ( 'cent_credit_id' , 'cus_abc123' , { type : 'debit' , amount : '100' , description : 'Manual deduction for premium support' , idempotency_key : support_deduction_ ${ Date . now ( ) } , } ) ; Query Customer Balance and Ledger // Get current balance const balance = await client . creditEntitlements . balances . get ( 'cent_credit_id' , 'cus_abc123' ) ; console . log ( Balance: ${ balance . available_balance } ) ; // List all balances for a credit entitlement const allBalances = await client . creditEntitlements . balances . list ( 'cent_credit_id' ) ; // Get full transaction history const ledger = await client . creditEntitlements . balances . listLedger ( 'cent_credit_id' , 'cus_abc123' ) ; for ( const entry of ledger . items ) { console . log ( ${ entry . type } : ${ entry . amount } | Balance: ${ entry . balance_after } ) ; } // List credit grants const grants = await client . creditEntitlements . balances . listGrants ( 'cent_credit_id' , 'cus_abc123' ) ; Update Credit Entitlement Settings await client . creditEntitlements . update ( 'cent_credit_id' , { rollover_enabled : true , max_rollover_percentage : 50 , allow_overage : true , overage_limit : 10000 , price_per_unit : 0.002 , overage_behavior : 'bill_overage_at_billing' , } ) ; Python from dodopayments import DodoPayments import os import uuid from datetime import datetime client = DodoPayments ( bearer_token = os . environ [ "DODO_PAYMENTS_API_KEY" ] )

Create credit entitlement

credit

client . credit_entitlements . create ( name = "AI Tokens" , credit_type = "custom_unit" , unit_name = "tokens" , precision = 0 , expiry_duration = 30 , rollover_enabled = True , max_rollover_percentage = 25 , allow_overage = True , overage_limit = 50000 , price_per_unit = 0.001 , overage_behavior = "bill_overage_at_billing" , )

Grant credits manually

client . credit_entitlements . balances . create_ledger_entry ( credit_entitlement_id = "cent_credit_id" , customer_id = "cus_abc123" , type = "credit" , amount = "500" , description = "Promotional bonus" , idempotency_key = f"promo_ { uuid . uuid4 ( ) } " , )

Check balance

balance

client . credit_entitlements . balances . get ( credit_entitlement_id = "cent_credit_id" , customer_id = "cus_abc123" , ) print ( f"Available: { balance . available_balance } " )

Send usage events that deduct credits

client
.
usage_events
.
ingest
(
events
=
[
{
"event_id"
:
f"api_
{
datetime
.
now
(
)
.
timestamp
(
)
}
_
{
uuid
.
uuid4
(
)
}
"
,
"customer_id"
:
"cus_abc123"
,
"event_name"
:
"ai.tokens"
,
"timestamp"
:
datetime
.
now
(
)
.
isoformat
(
)
,
"metadata"
:
{
"tokens"
:
"1500"
,
"model"
:
"gpt-4"
}
}
]
)
Go
package
main
import
(
"context"
"fmt"
"os"
"time"
"github.com/dodopayments/dodopayments-go"
"github.com/google/uuid"
)
func
main
(
)
{
client
:=
dodopayments
.
NewClient
(
option
.
WithBearerToken
(
os
.
Getenv
(
"DODO_PAYMENTS_API_KEY"
)
)
,
)
ctx
:=
context
.
Background
(
)
// Create credit entitlement
credit
,
err
:=
client
.
CreditEntitlements
.
Create
(
ctx
,
&
dodopayments
.
CreditEntitlementCreateParams
{
Name
:
"AI Tokens"
,
CreditType
:
"custom_unit"
,
UnitName
:
"tokens"
,
Precision
:
0
,
}
)
if
err
!=
nil
{
panic
(
err
)
}
// Get customer balance
balance
,
err
:=
client
.
CreditEntitlements
.
Balances
.
Get
(
ctx
,
credit
.
ID
,
"cus_abc123"
)
if
err
!=
nil
{
panic
(
err
)
}
fmt
.
Printf
(
"Balance: %s\n"
,
balance
.
AvailableBalance
)
// Send usage events
_
,
err
=
client
.
UsageEvents
.
Ingest
(
ctx
,
&
dodopayments
.
UsageEventIngestParams
{
Events
:
[
]
dodopayments
.
UsageEvent
{
{
EventID
:
fmt
.
Sprintf
(
"api_%d_%s"
,
time
.
Now
(
)
.
Unix
(
)
,
uuid
.
New
(
)
.
String
(
)
)
,
CustomerID
:
"cus_abc123"
,
EventName
:
"ai.tokens"
,
Timestamp
:
time
.
Now
(
)
.
Format
(
time
.
RFC3339
)
,
Metadata
:
map
[
string
]
string
{
"tokens"
:
"1500"
,
"model"
:
"gpt-4"
,
}
,
}
}
,
}
)
if
err
!=
nil
{
panic
(
err
)
}
}
Credit Settings
Rollover
Carry unused credits forward to the next billing cycle:
Setting
Description
Rollover Enabled
Toggle to allow unused credits to carry forward
Max Rollover Percentage
Limit how much carries over (0–100%)
Rollover Timeframe
How long rolled-over credits remain valid (day, week, month, year)
Max Rollover Count
Maximum consecutive rollovers before credits are forfeited
Example
200 unused credits at cycle end, 75% rollover → 150 credits carry forward, 50 forfeited. Overage Controls what happens when a customer's balance reaches zero mid-cycle: Setting Description Allow Overage Let customers continue past zero balance Overage Limit Max credits consumable beyond balance Price Per Unit Cost per additional credit (with currency) Overage Behavior How overage is handled at cycle end Overage Behaviors: Behavior Description Forgive overage at reset Overage tracked but not billed (default) Bill overage at billing Overage charged on next invoice Carry over deficit Negative balance carries into next cycle Carry over deficit (auto-repay) Deficit auto-repaid from new credits next cycle Expiration Setting Description Credit Expiry Duration after issuance: 7, 30, 60, 90, custom days, or never Trial Credits Expire After Trial Whether trial-specific credits expire when trial ends Webhook Events Credit-based billing fires these webhook events: Event Description credit.added Credits granted to a customer credit.deducted Credits consumed through usage or manual debit credit.expired Unused credits expired credit.rolled_over Credits carried forward to a new grant credit.rollover_forfeited Credits forfeited at max rollover count credit.overage_charged Overage charges applied credit.manual_adjustment Manual credit/debit adjustment made credit.balance_low Balance dropped below configured threshold Webhook Handler Example // app/api/webhooks/dodo/route.ts import { NextRequest , NextResponse } from 'next/server' ; export async function POST ( req : NextRequest ) { const event = await req . json ( ) ; switch ( event . type ) { case 'credit.added' : await handleCreditAdded ( event . data ) ; break ; case 'credit.deducted' : await handleCreditDeducted ( event . data ) ; break ; case 'credit.balance_low' : await handleBalanceLow ( event . data ) ; break ; case 'credit.expired' : await handleCreditExpired ( event . data ) ; break ; case 'credit.overage_charged' : await handleOverageCharged ( event . data ) ; break ; } return NextResponse . json ( { received : true } ) ; } async function handleCreditAdded ( data : any ) { const { customer_id , credit_entitlement_id , amount , balance_after } = data ; // Update internal records await prisma . creditBalance . upsert ( { where : { customerId_creditId : { customerId : customer_id , creditId : credit_entitlement_id } } , create : { customerId : customer_id , creditId : credit_entitlement_id , balance : balance_after } , update : { balance : balance_after } , } ) ; } async function handleCreditDeducted ( data : any ) { const { customer_id , credit_entitlement_id , amount , balance_after } = data ; await prisma . creditBalance . update ( { where : { customerId_creditId : { customerId : customer_id , creditId : credit_entitlement_id } } , data : { balance : balance_after } , } ) ; } async function handleBalanceLow ( data : any ) { const { customer_id , credit_entitlement_name , available_balance , threshold_percent , } = data ; // Notify the customer await sendEmail ( customer_id , { subject : Your ${ credit_entitlement_name } balance is running low , body : You have ${ available_balance } credits remaining ( ${ threshold_percent } % threshold reached). Consider upgrading your plan or purchasing additional credits. , } ) ; } async function handleCreditExpired ( data : any ) { const { customer_id , credit_entitlement_id , amount , balance_after } = data ; await prisma . creditBalance . update ( { where : { customerId_creditId : { customerId : customer_id , creditId : credit_entitlement_id } } , data : { balance : balance_after } , } ) ; // Optionally notify customer await sendCreditExpiryNotification ( customer_id , amount ) ; } async function handleOverageCharged ( data : any ) { const { customer_id , credit_entitlement_id , amount , overage_after } = data ; // Track overage for billing await prisma . overageRecord . create ( { data : { customerId : customer_id , creditId : credit_entitlement_id , amount , overageBalance : overage_after , } , } ) ; } Balance Low Payload The credit.balance_low event has a distinct payload: { "business_id" : "bus_xxxxx" , "type" : "credit.balance_low" , "timestamp" : "2025-08-04T06:15:00.000000Z" , "data" : { "payload_type" : "CreditBalanceLow" , "customer_id" : "cus_xxxxx" , "subscription_id" : "sub_xxxxx" , "credit_entitlement_id" : "cent_xxxxx" , "credit_entitlement_name" : "API Credits" , "available_balance" : "15" , "subscription_credits_amount" : "100" , "threshold_percent" : 20 , "threshold_amount" : "20" } } Usage Billing with Credits When credits are linked to usage meters, meter events automatically deduct credits. A background worker processes events every minute, converts meter units to credits using your configured rate, and deducts using FIFO ordering (oldest grants first). How It Works Your app sends usage events — Each event includes customer ID, event name, and metadata Meters aggregate events — Using Count, Sum, Max, Last, or Unique Count Credits are deducted automatically — Converted at your configured meter_units_per_credit rate Overage is tracked — If balance reaches zero and overage is enabled, usage continues Meter-Credit Configuration In Dashboard → Products → Usage-Based Product → Select Meter: Toggle Bill usage in Credits Select the credit entitlement Set Meter units per credit (e.g., 1000 API calls = 1 credit) Set Free Threshold (units free before credit deduction begins) AI Token Billing Example import DodoPayments from 'dodopayments' ; const client = new DodoPayments ( { bearerToken : process . env . DODO_PAYMENTS_API_KEY ! , } ) ; // Track AI token usage — meter auto-deducts credits async function trackAIUsage ( customerId : string , promptTokens : number , completionTokens : number , model : string ) { const totalTokens = promptTokens + completionTokens ; await client . usageEvents . ingest ( { events : [ { event_id : ai_ ${ Date . now ( ) } _ ${ crypto . randomUUID ( ) } , customer_id : customerId , event_name : 'ai.tokens' , timestamp : new Date ( ) . toISOString ( ) , metadata : { tokens : totalTokens . toString ( ) , prompt_tokens : promptTokens . toString ( ) , completion_tokens : completionTokens . toString ( ) , model , } } ] } ) ; } // After AI completion await trackAIUsage ( 'cus_abc123' , 500 , 1200 , 'gpt-4' ) ; API Rate Tracking Example // Middleware to track and deduct API credits async function trackAPICredit ( customerId : string , req : Request ) { await client . usageEvents . ingest ( { events : [ { event_id : api_ ${ Date . now ( ) } _ ${ crypto . randomUUID ( ) } , customer_id : customerId , event_name : 'api.call' , timestamp : new Date ( ) . toISOString ( ) , metadata : { endpoint : new URL ( req . url ) . pathname , method : req . method , } } ] } ) ; } Next.js Integration Credit Balance API Route // app/api/credits/balance/route.ts import { NextRequest , NextResponse } from 'next/server' ; import DodoPayments from 'dodopayments' ; const client = new DodoPayments ( { bearerToken : process . env . DODO_PAYMENTS_API_KEY ! , } ) ; export async function GET ( req : NextRequest ) { const customerId = req . nextUrl . searchParams . get ( 'customer_id' ) ; const creditId = req . nextUrl . searchParams . get ( 'credit_id' ) ; if ( ! customerId || ! creditId ) { return NextResponse . json ( { error : 'Missing parameters' } , { status : 400 } ) ; } try { const balance = await client . creditEntitlements . balances . get ( creditId , customerId ) ; return NextResponse . json ( { available : balance . available_balance , overage : balance . overage_balance , } ) ; } catch ( error : any ) { return NextResponse . json ( { error : error . message } , { status : 500 } ) ; } } Manual Credit Grant API Route // app/api/credits/grant/route.ts import { NextRequest , NextResponse } from 'next/server' ; import DodoPayments from 'dodopayments' ; const client = new DodoPayments ( { bearerToken : process . env . DODO_PAYMENTS_API_KEY ! , } ) ; export async function POST ( req : NextRequest ) { const { customerId , creditId , amount , description } = await req . json ( ) ; try { const entry = await client . creditEntitlements . balances . createLedgerEntry ( creditId , customerId , { type : 'credit' , amount : amount . toString ( ) , description , idempotency_key : grant_ ${ customerId } _ ${ Date . now ( ) } , } ) ; return NextResponse . json ( { success : true , balance_after : entry . balance_after } ) ; } catch ( error : any ) { return NextResponse . json ( { error : error . message } , { status : 500 } ) ; } } Credit Balance Hook // hooks/useCreditBalance.ts import useSWR from 'swr' ; const fetcher = ( url : string ) => fetch ( url ) . then ( r => r . json ( ) ) ; export function useCreditBalance ( customerId : string , creditId : string ) { const { data , error , mutate } = useSWR ( /api/credits/balance?customer_id= ${ customerId } &credit_id= ${ creditId } , fetcher , { refreshInterval : 30000 } // Refresh every 30s ) ; return { available : data ?. available , overage : data ?. overage , isLoading : ! error && ! data , isError : error , refresh : mutate , } ; } // Usage in component function CreditDisplay ( ) { const { available , isLoading } = useCreditBalance ( 'cus_abc123' , 'cent_xxxxx' ) ; if ( isLoading ) return < div

Loading ... < / div

; return ( < div

< h3

Credits Remaining < / h3

< p className = "text-3xl font-bold"

{ available } < / p

< / div

) ; } Common Patterns Credit Top-Up (One-Time Purchase) Sell credit packs as one-time products: // Product: "500 API Credit Pack" with 500 credits attached const session = await client . checkoutSessions . create ( { product_cart : [ { product_id : 'prod_credit_pack_500' , quantity : 1 } ] , customer : { email : 'customer@example.com' } , return_url : 'https://yourapp.com/credits/success' , } ) ; Subscription with Credits + Overage // Product: Pro Plan - $49/month, 10,000 tokens included, $0.002/token overage // Credits attached in dashboard with: // - Credits per cycle: 10000 // - Allow overage: true // - Price per unit: $0.002 // - Overage behavior: Bill overage at billing const session = await client . checkoutSessions . create ( { product_cart : [ { product_id : 'prod_pro_with_credits' , quantity : 1 } ] , subscription_data : { trial_period_days : 14 } , customer : { email : 'customer@example.com' } , return_url : 'https://yourapp.com/success' , } ) ; Access Control Based on Credits // Middleware to check credit balance before allowing API access async function requireCredits ( customerId : string , creditId : string ) : Promise < boolean

{ try { const balance = await client . creditEntitlements . balances . get ( creditId , customerId ) ; const available = parseFloat ( balance . available_balance ) ; return available

0 ; } catch { return false ; } } // Express middleware async function creditGate ( req : Request , res : Response , next : Function ) { const customerId = req . headers [ 'x-customer-id' ] as string ; const hasCredits = await requireCredits ( customerId , 'cent_api_credits' ) ; if ( ! hasCredits ) { return res . status ( 402 ) . json ( { error : 'Insufficient credits' , message : 'Your credit balance is exhausted. Please upgrade your plan or purchase more credits.' , } ) ; } next ( ) ; } Promotional Credit Grants // Grant promotional credits with idempotency async function grantPromoCredits ( customerId : string , creditId : string , amount : number , promoCode : string ) { await client . creditEntitlements . balances . createLedgerEntry ( creditId , customerId , { type : 'credit' , amount : amount . toString ( ) , description : Promotional credit: ${ promoCode } , idempotency_key : promo_ ${ promoCode } _ ${ customerId } , // Prevents double-granting } ) ; } Real-World Pricing Examples AI SaaS Platform Plan | Price | Credits/Month | Overage ----------|----------|----------------|---------- Starter | $29/mo | 10,000 tokens | $0.003/token Pro | $99/mo | 100,000 tokens | $0.002/token Enterprise| $499/mo | 1,000,000 tokens| $0.001/token Credit Config: Type: Custom Unit ("AI Tokens"), Precision: 0 Rollover: 25% max, 1-month timeframe Overage: Bill overage at billing Meter: ai.generation (Sum on tokens) API Gateway Plan | Price | Credits/Month | Overage ----------|----------|----------------|---------- Free | $0/mo | 1,000 calls | Blocked Developer | $19/mo | 50,000 calls | $0.001/call Business | $99/mo | 500,000 calls | $0.0005/call Credit Config: Type: Custom Unit ("API Calls"), Precision: 0 Rollover: Disabled Overage: Free=disabled, Dev+=forgive at reset Meter: api.request (Count) Cloud Storage Plan | Price | Credits/Month | Overage ----------|----------|----------------|---------- Personal | $9/mo | 100 GB-hours | $0.05/GB-hour Team | $49/mo | 1,000 GB-hours | $0.03/GB-hour Credit Config: Type: Custom Unit ("GB-hours"), Precision: 2 Rollover: 50% max, carries over once Overage: Enabled with 200% limit Meter: storage.usage (Sum) Credit Ledger Every credit operation is recorded with full audit trail: Transaction Type Description Credit Added Credits granted (subscription, one-time, or API) Credit Deducted Credits consumed through usage or manual debit Credit Expired Credits expired without rollover Credit Rolled Over Credits carried forward to the next period Rollover Forfeited Rolled credits forfeited after max count reached Overage Charged Usage beyond credit balance with overage enabled Auto Top-Up Automatic credit replenishment at low balance Manual Adjustment Credit or debit applied manually by merchant Refund Credits refunded Each ledger entry records balance before/after, overage before/after, description, and reference to the source. Best Practices 1. Start Simple Begin with a single credit type and no rollover. Add complexity based on customer usage patterns. 2. Use Meaningful Units Name credits after what they represent ("API Calls", "AI Tokens") not generic terms. 3. Set Low Balance Thresholds Configure thresholds and subscribe to credit.balance_low to alert customers before they run out. 4. Use Idempotency Keys Always include idempotency keys for manual ledger entries to prevent double-granting: idempotency_key : promo_ ${ promoCode } _ ${ customerId } 5. Configure Expiry Thoughtfully Short expiry (7 days) drives urgency but may frustrate. 30–90 days is customer-friendly for most SaaS. 6. Test the Full Cycle In test mode: create credits → attach to product → purchase → send usage events → verify deduction → test expiration and rollover. 7. Monitor Overage If using "Bill overage at billing", monitor overage amounts to avoid unexpected charges for customers. Resources Credit-Based Billing Guide Credit Entitlements API Credit Webhook Events Usage-Based Billing Subscription Integration

← 返回排行榜