基于信用的计费 - Dodo Payments Documentation

基于信用的计费 Webhook 事件

以下 webhook 事件可用于跟踪基于信用的计费生命周期的变化。这些事件适用于虚拟信用权益（API 调用、令牌、计算小时），而非客户钱包（货币余额）。

事件	说明
`credit.added`	通过订阅、一次性购买、附加组件或 API 向客户授予积分
`credit.deducted`	通过使用或手动扣款消耗积分
`credit.expired`	未使用的积分在配置的到期周期后过期
`credit.rolled_over`	未使用的积分在周期结束时结转到新的发放
`credit.rollover_forfeited`	由于达到最大结转次数而没收积分
`credit.overage_charged`	在使用量超过零余额时收取超额费用
`credit.manual_adjustment`	通过控制面板或 API 进行的手动记入或扣减调整
`credit.balance_low`	信用余额低于配置的低余额阈值

分类账事件

所有分类账事件（credit.added 至 credit.manual_adjustment）使用下方模式中记录的相同 CreditLedgerEntryResponse 负载。有效负载包括从信用授权的来源解析出的metadata字段——即在结账时创建的订阅或付款。这使您可以根据自己的结账流程键入钱包积分metadata（例如，一个orgId），而不是Dodo发出的customer_id：订阅来源的授权会显示订阅的metadata，付款来源的授权会显示付款的metadata。当授权没有可解析来源时（例如，通过API直接授予的信用），该字段为空。

余额低事件 (credit.balance_low)

credit.balance_low事件使用不同的有效负载(CreditBalanceLowPayload)，专注于阈值警报：

{
  "business_id": "bus_H4ekzPSlcg",
  "type": "credit.balance_low",
  "timestamp": "2025-08-04T06:15:00.000000Z",
  "data": {
    "payload_type": "CreditBalanceLow",
    "customer_id": "cus_8VbC6JDZzPEqfBPUdpj0K",
    "subscription_id": "sub_7EeHq2ewQuadropD2ra",
    "credit_entitlement_id": "cent_9xY2bKwQn5MjRpL8d",
    "credit_entitlement_name": "API Credits",
    "available_balance": "15",
    "subscription_credits_amount": "100",
    "threshold_percent": 20,
    "threshold_amount": "20"
  }
}

customer_id

string

触发警报的客户信用余额。

subscription_id

string

与此信用授权相关的订阅。

credit_entitlement_id

string

余额低的信用授权。

credit_entitlement_name

string

信用授权的显示名称。

available_balance

string

警报时的当前信用余额。

subscription_credits_amount

string

此订阅每个计费周期发放的总信用。

threshold_percent

integer

配置的低余额阈值百分比。

threshold_amount

string

阈值对应的绝对信用金额。

使用`credit.balance_low`进行主动警报

使用credit.balance_low webhook在客户用完信用之前通知他们：

app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'credit.balance_low') {
    const data = event.data;
    
    // Notify the customer their credits are running low
    await sendEmail(data.customer_id, {
      subject: `Your ${data.credit_entitlement_name} balance is running low`,
      body: `You have ${data.available_balance} credits remaining ` +
            `(${data.threshold_percent}% threshold reached). ` +
            `Consider upgrading your plan or purchasing additional credits.`
    });
    
    console.log(`Low balance alert for customer ${data.customer_id}`);
  }
  
  res.json({ received: true });
});

订阅credit.balance_low以在客户耗尽其信用之前主动警示他们。结合credit.deducted以跟踪实时消费模式。

Get Customer Balance

通过API检查客户的当前余额。

Create Ledger Entry

手动增减客户的余额。

Webhook有效负载架构

Response for a ledger entry

amount

string

必填

balance_after

string

必填

balance_before

string

必填

brand_id

string

必填

Brand id this credit ledger entry belongs to

business_id

string

必填

created_at

string<date-time>

必填

credit_entitlement_id

string

必填

customer_id

string

必填

string

必填

is_credit

boolean

必填

metadata

object

必填

Metadata associated with the credit grant's source (the subscription or payment created at checkout). Empty when the grant has no resolvable source (e.g. credits granted directly via the API).

Show child attributes

overage_after

string

必填

overage_before

string

必填

transaction_type

enum<string>

必填

可用选项:

credit_added,

credit_deducted,

credit_expired,

credit_rolled_over,

rollover_forfeited,

overage_charged,

overage_reset,

auto_top_up,

manual_adjustment,

refund

description

string | null

grant_id

string | null

reference_id

string | null

reference_type

string | null

​基于信用的计费 Webhook 事件

​分类账事件

​余额低事件 (credit.balance_low)

​使用credit.balance_low进行主动警报

Get Customer Balance

Create Ledger Entry

​Webhook有效负载架构

基于信用的计费 Webhook 事件

分类账事件

余额低事件 (credit.balance_low)

使用`credit.balance_low`进行主动警报

Webhook有效负载架构