Credit-Based Billing

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

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

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）を使用します：

{
  "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"
  }
}

string

アラートをトリガーしたクレジット残高のある顧客。

string

このクレジット権利に関連付けられたサブスクリプション。

string

低残高のクレジット権利。

string

クレジット権利の表示名。

string

アラート時点での現在のクレジット残高。

string

このサブスクリプションにおける請求サイクルごとの発行済み総クレジット。

integer

設定された低残高しきい値の割合。

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

必須

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

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

レジャーイベント

残高低下イベント（credit.balance_low）

プロアクティブアラートのための`credit.balance_low`の使用

Get Customer Balance

Create Ledger Entry

Webhook ペイロードスキーマ

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

​レジャーイベント

​残高低下イベント（credit.balance_low）

​プロアクティブアラートのためのcredit.balance_lowの使用

Get Customer Balance

Create Ledger Entry

​Webhook ペイロードスキーマ

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

レジャーイベント

残高低下イベント（credit.balance_low）

プロアクティブアラートのための`credit.balance_low`の使用

Webhook ペイロードスキーマ