메인 콘텐츠로 건너뛰기

​
신용 기반 청구 웹훅 이벤트

다음 웹훅 이벤트는 가상 크레딧 권한(API 호출, 토큰, 컴퓨트 시간)의 수명 주기 변화를 추적하는 데 사용됩니다. 이 이벤트는 Customer Wallets(금전적 잔액)과 관련이 없습니다.
EventDescription
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"
  }
}
​
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 웹훅을 사용하세요: 
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
필수
​
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,
overage_reset,
auto_top_up,
manual_adjustment,
refund
​
description
string | null
​
grant_id
string | null
​
reference_id
string | null
​
reference_type
string | null
마지막 수정일 2026년 3월 2일