メインコンテンツへスキップ

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

以下のWebhookイベントにより、クレジットベースの請求ライフサイクルの変更を追跡できます。これらのイベントは仮想クレジットの権利（APIコール、トークン、コンピュート時間）に適用され、Customer Wallets（通貨残高）には関係ありません。
EventDescription
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,
auto_top_up,
manual_adjustment,
refund
​
description
string | null
​
grant_id
string | null
​
reference_id
string | null
​
reference_type
string | null