신용 기반 청구

신용 기반 청구 웹훅 이벤트

다음 웹훅 이벤트는 가상 크레딧 권한(API 호출, 토큰, 컴퓨트 시간)의 수명 주기 변화를 추적하는 데 사용됩니다. 이 이벤트는 Customer Wallets(금전적 잔액)과 관련이 없습니다.

Event	Description
`credit.added`	구독, 일회성 구매, 애드온 또는 API를 통해 고객에게 크레딧이 부여됩니다.
`credit.deducted`	사용량 또는 수동 차감으로 크레딧이 소비됩니다.
`credit.expired`	사용되지 않은 크레딧은 설정된 만료 기간 이후 만료됩니다.
`credit.rolled_over`	사용되지 않은 크레딧은 주기 종료 시 새로운 부여로 이월됩니다.
`credit.rollover_forfeited`	최대 이월 횟수에 도달하여 크레딧이 몰수됩니다.
`credit.overage_charged`	잔액이 0 이하로 계속 사용할 경우 초과 요금이 적용됩니다.
`credit.manual_adjustment`	대시보드 또는 API를 통해 수동으로 크레딧 또는 차감이 조정됩니다.
`credit.balance_low`	크레딧 잔액이 설정된 저잔액 임계값 아래로 떨어집니다.

원장 이벤트

모든 원장 이벤트(credit.added부터 credit.manual_adjustment까지)는 아래 스키마에 문서화된 동일한 CreditLedgerEntryResponse 페이로드를 공유합니다.

저잔액 이벤트 (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 웹훅을 사용하세요:

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

고객 잔액을 수동으로 충전하거나 차감하세요.

웹훅 페이로드 스키마

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