Credit-Based Billing - Dodo Payments Documentation

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

Peristiwa Saldo Rendah (credit.balance_low)

Peristiwa credit.balance_low menggunakan payload berbeda (CreditBalanceLowPayload) yang difokuskan pada pemberitahuan ambang batas:

{
  "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

Pelanggan yang saldo kreditnya memicu peringatan.

subscription_id

string

Langganan yang terkait dengan hak kredit ini.

credit_entitlement_id

string

Hak kredit yang memiliki saldo rendah.

credit_entitlement_name

string

Nama tampilan dari hak kredit.

available_balance

string

Saldo kredit saat ini pada saat peringatan.

subscription_credits_amount

string

Total kredit yang diterbitkan per siklus penagihan untuk langganan ini.

threshold_percent

integer

Persentase ambang batas saldo rendah yang dikonfigurasi.

threshold_amount

string

Jumlah kredit absolut yang menjadi acuan ambang batas.

Menggunakan `credit.balance_low` untuk Peringatan Proaktif

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

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 });
});

Berlangganan ke credit.balance_low untuk memberi peringatan proaktif kepada pelanggan sebelum kredit mereka habis. Padukan dengan credit.deducted untuk melacak pola konsumsi waktu nyata.

Get Customer Balance

Periksa saldo pelanggan saat ini melalui API.

Create Ledger Entry

Secara manual memberi kredit atau debit ke saldo pelanggan.

Skema Payload Webhook

Response for a ledger entry

amount

string

wajib

balance_after

string

wajib

balance_before

string

wajib

business_id

string

wajib

created_at

string<date-time>

wajib

credit_entitlement_id

string

wajib

customer_id

string

wajib

string

wajib

is_credit

boolean

wajib

overage_after

string

wajib

overage_before

string

wajib

transaction_type

enum<string>

wajib

Opsi yang tersedia:

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

Documentation Index

​Event Webhook Penagihan Berbasis Kredit

​Peristiwa Buku Besar

​Peristiwa Saldo Rendah (credit.balance_low)

​Menggunakan credit.balance_low untuk Peringatan Proaktif

Get Customer Balance

Create Ledger Entry

​Skema Payload Webhook

Event Webhook Penagihan Berbasis Kredit

Peristiwa Buku Besar

Peristiwa Saldo Rendah (credit.balance_low)

Menggunakan `credit.balance_low` untuk Peringatan Proaktif

Skema Payload Webhook