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",
    "brand_id": "brd_123",
    "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

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

string

このサブスクリプションに対して、請求サイクルごとに発行されるクレジットの合計。

integer

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

string

しきい値に対応するクレジットの絶対額。

Proactive Alerts に `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 Payload Schema

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）

Proactive Alerts に `credit.balance_low` を使用する

Get Customer Balance

Create Ledger Entry

Webhook Payload Schema

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

​レジャーイベント

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

​Proactive Alerts に credit.balance_low を使用する

Get Customer Balance

Create Ledger Entry

​Webhook Payload Schema

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

レジャーイベント

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

Proactive Alerts に `credit.balance_low` を使用する

Webhook Payload Schema