Vai al contenuto principale

​
Eventi webhook per la fatturazione basata sui crediti

Sono disponibili i seguenti eventi webhook per monitorare i cambiamenti del ciclo di vita della fatturazione basata sui crediti. Questi eventi si applicano ai crediti virtuali (chiamate API, token, ore di calcolo), non ai Customer Wallets (saldi monetari).
EventDescription
credit.addedI crediti vengono concessi a un cliente (tramite abbonamento, acquisto una tantum, componente aggiuntivo o API)
credit.deductedI crediti vengono consumati tramite utilizzo o addebito manuale
credit.expiredI crediti inutilizzati scadono dopo il periodo di scadenza configurato
credit.rolled_overI crediti inutilizzati vengono riportati su una nuova concessione alla fine del ciclo
credit.rollover_forfeitedCrediti annullati perché è stato raggiunto il numero massimo di rollover
credit.overage_chargedAddebiti per consumo eccessivo applicati quando l’utilizzo prosegue oltre il saldo zero
credit.manual_adjustmentRegolazione manuale di credito o addebito effettuata tramite dashboard o API
credit.balance_lowIl saldo dei crediti scende al di sotto della soglia di basso saldo configurata

​
Eventi del registro contabile

Tutti gli eventi del registro contabile (credit.added fino a credit.manual_adjustment) condividono lo stesso payload CreditLedgerEntryResponse documentato nello schema sottostante.

​
Evento di basso saldo (credit.balance_low)

L’evento credit.balance_low utilizza un payload diverso (CreditBalanceLowPayload) incentrato sugli avvisi di soglia: 
{
  "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
Il cliente il cui saldo crediti ha attivato l’avviso.
​
subscription_id
string
L’abbonamento associato a questo diritto ai crediti.
​
credit_entitlement_id
string
Il diritto ai crediti che presenta un saldo basso.
​
credit_entitlement_name
string
Nome visualizzato del diritto ai crediti.
​
available_balance
string
Saldo crediti corrente al momento dell’avviso.
​
subscription_credits_amount
string
Totale dei crediti concessi per ciclo di fatturazione per questo abbonamento.
​
threshold_percent
integer
La percentuale configurata della soglia di basso saldo.
​
threshold_amount
string
L’importo assoluto di crediti a cui corrisponde la soglia.

​
Uso di credit.balance_low per avvisi proattivi

Usa il webhook credit.balance_low per avvisare i clienti prima che esauriscano i crediti: 
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 });
});
Iscriviti a credit.balance_low per avvisare proattivamente i clienti prima che esauriscano i propri crediti. Combinalo con credit.deducted per monitorare in tempo reale i modelli di consumo.

Get Customer Balance

Verifica il saldo attuale di un cliente tramite API.

Create Ledger Entry

Accredita o addebita manualmente il saldo di un cliente.

​
Schema del payload del webhook

Response for a ledger entry

​
amount
string
obbligatorio
​
balance_after
string
obbligatorio
​
balance_before
string
obbligatorio
​
business_id
string
obbligatorio
​
created_at
string<date-time>
obbligatorio
​
credit_entitlement_id
string
obbligatorio
​
customer_id
string
obbligatorio
​
id
string
obbligatorio
​
is_credit
boolean
obbligatorio
​
overage_after
string
obbligatorio
​
overage_before
string
obbligatorio
​
transaction_type
enum<string>
obbligatorio
Opzioni disponibili:
credit_added,
credit_deducted,
credit_expired,
credit_rolled_over,
rollover_forfeited,
overage_charged,
auto_top_up,
manual_adjustment,
refund
​
description
string | null
​
grant_id
string | null
​
reference_id
string | null
​
reference_type
string | null