> ## 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.

# Credit-Based Billing

> Payload yang dikirim ke endpoint webhook Anda saat terjadi peristiwa penagihan berbasis kredit — kredit virtual (panggilan API, token, jam komputasi) diberikan, digunakan, kedaluwarsa, dilanjutkan, atau peringatan saldo. Webhook ini tidak terkait dengan [Customer Wallets](/features/customer-wallet) (saldo moneter).

## Event Webhook Penagihan Berbasis Kredit

Peristiwa webhook berikut tersedia untuk melacak perubahan siklus hidup penagihan berbasis kredit. Peristiwa ini berlaku untuk hak kredit virtual (panggilan API, token, jam komputasi), bukan untuk [Customer Wallets](/features/customer-wallet) (saldo moneter).

| Event                       | Description                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `credit.added`              | Kredit diberikan kepada pelanggan (melalui langganan, pembelian satu kali, tambahan, atau API) |
| `credit.deducted`           | Kredit digunakan melalui pemakaian atau debit manual                                           |
| `credit.expired`            | Kredit yang tidak digunakan kedaluwarsa setelah periode kedaluwarsa yang dikonfigurasi         |
| `credit.rolled_over`        | Kredit yang tidak digunakan dibawa ke pemberian baru pada akhir siklus                         |
| `credit.rollover_forfeited` | Kredit hangus karena jumlah rollover maksimum tercapai                                         |
| `credit.overage_charged`    | Biaya kelebihan diterapkan ketika pemakaian berlanjut melebihi saldo nol                       |
| `credit.manual_adjustment`  | Penyesuaian kredit atau debit manual dilakukan melalui dasbor atau API                         |
| `credit.balance_low`        | Saldo kredit turun di bawah ambang batas saldo rendah yang dikonfigurasi                       |

### Peristiwa Buku Besar

Semua peristiwa buku besar (`credit.added` hingga `credit.manual_adjustment`) memiliki payload `CreditLedgerEntryResponse` yang sama, seperti yang didokumentasikan dalam skema berikut.

Payload mencakup field `metadata` yang diambil dari **sumber** pemberian kredit — langganan atau pembayaran yang dibuat saat checkout. Ini memungkinkan Anda mengaitkan kredit dompet dengan checkout Anda sendiri `metadata` (misalnya, sebuah `orgId`) daripada yang dikeluarkan oleh Dodo `customer_id`: pemberian yang bersumber dari langganan menampilkan `metadata` langganan dan pemberian yang bersumber dari pembayaran menampilkan `metadata` pembayaran. Field ini kosong ketika pemberian tidak memiliki sumber yang dapat diselesaikan (misalnya, kredit yang diberikan langsung melalui API).

### Acara Saldo Rendah (credit.balance\_low)

Acara `credit.balance_low` menggunakan payload berbeda (`CreditBalanceLowPayload`) yang fokus pada peringatan ambang batas:

```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">
  Pelanggan yang saldo kreditnya memicu peringatan.
</ParamField>

<ParamField body="subscription_id" type="string">
  Langganan yang terkait dengan hak kredit ini.
</ParamField>

<ParamField body="credit_entitlement_id" type="string">
  Hak kredit yang memiliki saldo rendah.
</ParamField>

<ParamField body="credit_entitlement_name" type="string">
  Nama tampilan dari hak kredit.
</ParamField>

<ParamField body="available_balance" type="string">
  Saldo kredit saat ini pada saat peringatan.
</ParamField>

<ParamField body="subscription_credits_amount" type="string">
  Total kredit yang diterbitkan per siklus penagihan untuk langganan ini.
</ParamField>

<ParamField body="threshold_percent" type="integer">
  Persentase ambang batas saldo rendah yang sudah dikonfigurasi.
</ParamField>

<ParamField body="threshold_amount" type="string">
  Jumlah kredit absolut yang sesuai dengan ambang tersebut.
</ParamField>

### Menggunakan `credit.balance_low` untuk Peringatan Proaktif

Gunakan webhook `credit.balance_low` untuk memberi tahu pelanggan sebelum mereka kehabisan kredit:

```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>
  Berlangganan ke `credit.balance_low` untuk memberi peringatan proaktif kepada pelanggan sebelum mereka kehabisan kredit. Gabungkan dengan `credit.deducted` untuk melacak pola konsumsi secara real-time.
</Tip>

<CardGroup cols={2}>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    Periksa saldo saat ini dari pelanggan melalui API.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    Kreditkan atau debit saldo pelanggan secara manual.
  </Card>
</CardGroup>

## Skema Payload Webhook