> ## 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.

# Credit-Based Billing

> The payload sent to your webhook endpoint when credit-based billing events occur — virtual credits (API calls, tokens, compute hours) granted, consumed, expired, rolled over, or balance alerts. These webhooks are not related to Customer Wallets (monetary balances).

## クレジットベース請求のWebhookイベント

以下のWebhookイベントにより、クレジットベースの請求ライフサイクルの変更を追跡できます。これらのイベントは仮想クレジットの権利（APIコール、トークン、コンピュート時間）に適用され、[Customer Wallets](/features/customer-wallet)（通貨残高）には関係ありません。

| Event                       | Description                                 |
| --------------------------- | ------------------------------------------- |
| `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` ペイロードを共有します。

ペイロードには、クレジット付与の**source**（チェックアウトで作成されたサブスクリプションまたは支払い）から解決された`metadata`フィールドが含まれています。これにより、Dodoが発行する`customer_id`ではなく、自分のチェックアウト`metadata`（たとえば、`orgId`）を元にウォレットクレジットをキー付けすることができます。サブスクリプションソースの付与はサブスクリプションの`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 ペイロードスキーマ