基于信用的计费

基于信用的计费 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",
    "brand_id": "brd_123",
    "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"
  }
}

string

此 credit entitlement 所属的品牌。

string

其 credit balance 触发此警报的客户。

string

与此 credit entitlement 关联的订阅。

string

余额较低的 credit entitlement。

string

credit entitlement 的显示名称。

string

触发警报时的当前 credit balance。

string

此订阅每个计费周期发放的 credits 总量。

integer

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

string

阈值对应的绝对 credit 数量。

使用 `credit.balance_low` 进行主动提醒

使用 credit.balance_low webhook，在客户 credits 用尽前通知他们：

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，以便在客户 credits 用尽前主动提醒他们。结合 credit.deducted，实时跟踪消耗模式。

Get Customer Balance

通过 API 查看客户的当前 balance。

Create Ledger Entry

手动为客户的 balance 充值或扣款。

Webhook Payload Schema

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

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous