> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 基于信用的计费

> 当基于信用的计费事件发生时发送到你 webhook 端点的负载 —— 虚拟积分（API 调用、令牌、计算小时）被授予、消耗、过期、结转或触发余额警报。这些 webhook 与[客户钱包](/features/customer-wallet)（货币余额）无关。

## 基于信用的计费 Webhook 事件

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

| 事件                          | 说明                           |
| --------------------------- | ---------------------------- |
| `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`)，专注于阈值警报：

```json theme={null}
{
  "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"
  }
}
```

<ParamField body="customer_id" type="string">
  触发警报的客户信用余额。
</ParamField>

<ParamField body="subscription_id" type="string">
  与此信用授权相关的订阅。
</ParamField>

<ParamField body="credit_entitlement_id" type="string">
  余额低的信用授权。
</ParamField>

<ParamField body="credit_entitlement_name" type="string">
  信用授权的显示名称。
</ParamField>

<ParamField body="available_balance" type="string">
  警报时的当前信用余额。
</ParamField>

<ParamField body="subscription_credits_amount" type="string">
  此订阅每个计费周期发放的总信用。
</ParamField>

<ParamField body="threshold_percent" type="integer">
  配置的低余额阈值百分比。
</ParamField>

<ParamField body="threshold_amount" type="string">
  阈值对应的绝对信用金额。
</ParamField>

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

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

```javascript theme={null}
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 });
});
```

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

<CardGroup cols={2}>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    通过API检查客户的当前余额。
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    手动增减客户的余额。
  </Card>
</CardGroup>

## Webhook有效负载架构