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

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

​
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
最終更新日 2026年6月26日