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. Il payload include un campo metadata risolto dall’origine della concessione di credito — l’abbonamento o il pagamento creato al checkout. Questo ti consente di collegare i crediti del wallet al tuo stesso checkout metadata (ad esempio, un orgId) piuttosto che al customer_id emesso da Dodo: le concessioni derivate dall’abbonamento fanno emergere il metadata dell’abbonamento e quelle derivate dal pagamento fanno emergere il metadata del pagamento. Il campo è vuoto quando la concessione non ha un’origine risolvibile (ad esempio, crediti concessi direttamente tramite l’API).

​
Bilancio Basso Evento (credit.balance_low)

L’evento credit.balance_low utilizza un payload diverso (CreditBalanceLowPayload) incentrato sull’avviso 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 di credito ha attivato l’allerta.
​
subscription_id
string
L’abbonamento associato a questa concessione di credito.
​
credit_entitlement_id
string
La concessione di credito che ha un saldo basso.
​
credit_entitlement_name
string
Nome visualizzato della concessione di credito.
​
available_balance
string
Saldo attuale del credito al momento dell’avviso.
​
subscription_credits_amount
string
Crediti totali emessi per ciclo di fatturazione per questo abbonamento.
​
threshold_percent
integer
La percentuale di soglia di saldo basso configurata.
​
threshold_amount
string
L’importo assoluto del credito a cui corrisponde la soglia.

​
Utilizzo di credit.balance_low per Avvisi Proattivi

Utilizza il webhook credit.balance_low per notificare ai 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 loro crediti. Combina con credit.deducted per monitorare i modelli di consumo in tempo reale.

Get Customer Balance

Controlla il saldo attuale di un cliente tramite API.

Create Ledger Entry

Accredita o addebita manualmente il saldo di un cliente.

​
Schema del Payload Webhook

Response for a ledger entry

​
amount
string
obbligatorio
​
balance_after
string
obbligatorio
​
balance_before
string
obbligatorio
​
brand_id
string
obbligatorio

Brand id this credit ledger entry belongs to

​
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
​
metadata
object
obbligatorio

Metadata associated with the credit grant's source (the subscription or payment created at checkout). Empty when the grant has no resolvable source (e.g. credits granted directly via the API).

​
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,
overage_reset,
auto_top_up,
manual_adjustment,
refund
​
description
string | null
​
grant_id
string | null
​
reference_id
string | null
​
reference_type
string | null
Ultima modifica il 26 giugno 2026