跳转到主要内容

​
基于信用的计费 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 负载。

​
余额偏低事件 (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
必填
​
business_id
string
必填
​
created_at
string<date-time>
必填
​
credit_entitlement_id
string
必填
​
customer_id
string
必填
​
id
string
必填
​
is_credit
boolean
必填
​
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
最后修改于 2026年3月2日