基于信用的计费

基于信用的计费 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

必填

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,

auto_top_up,

manual_adjustment,

refund

description

string | null

grant_id

string | null

reference_id

string | null

reference_type

string | null

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous