> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 신용 기반 청구

> 신용 기반 청구 이벤트가 발생할 때 가상 크레딧(API 호출, 토큰, 컴퓨트 시간)의 부여, 소비, 만료, 이월 또는 잔액 알림 등 웹훅 엔드포인트로 전송되는 페이로드입니다. 이 웹훅은 [Customer Wallets](/features/customer-wallet)(금전적 잔액)과 관련이 없습니다.

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

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

| 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`)를 사용합니다:

```json theme={null}
{
  "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"
  }
}
```

<ParamField body="customer_id" type="string">
  크레딧 잔액으로 인해 알림이 발생한 고객입니다.
</ParamField>

<ParamField body="subscription_id" type="string">
  이 크레딧 권한과 연결된 구독입니다.
</ParamField>

<ParamField body="credit_entitlement_id" type="string">
  잔액이 낮은 크레딧 권한입니다.
</ParamField>

<ParamField body="credit_entitlement_name" type="string">
  크레딧 권한의 표시 이름입니다.
</ParamField>

<ParamField body="available_balance" type="string">
  알림 발생 시점의 현재 크레딧 잔액입니다.
</ParamField>

<ParamField body="subscription_credits_amount" type="string">
  이 구독의 청구 주기마다 발행되는 전체 크레딧입니다.
</ParamField>

<ParamField body="threshold_percent" type="integer">
  설정된 저잔액 임계값 백분율입니다.
</ParamField>

<ParamField body="threshold_amount" type="string">
  임계값에 해당하는 절대 크레딧 금액입니다.
</ParamField>

### 사전 알림을 위한 `credit.balance_low` 사용

고객이 크레딧이 소진되기 전에 알림을 보내려면 `credit.balance_low` 웹훅을 사용하세요:

```javascript theme={null}
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 });
});
```

<Tip>
  고객이 크레딧을 모두 소비하기 전에 사전 알림을 보내려면 `credit.balance_low`을 구독하세요. 실시간 소비 패턴을 추적하려면 `credit.deducted`와 함께 사용하세요.
</Tip>

<CardGroup cols={2}>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    API를 통해 고객의 현재 잔액을 확인하세요.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    고객 잔액을 수동으로 충전하거나 차감하세요.
  </Card>
</CardGroup>

## 웹훅 페이로드 스키마