Skip to main content

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

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:
string
Il cliente il cui saldo di credito ha attivato l’allerta.
string
L’abbonamento associato a questa concessione di credito.
string
La concessione di credito che ha un saldo basso.
string
Nome visualizzato della concessione di credito.
string
Saldo attuale del credito al momento dell’avviso.
string
Crediti totali emessi per ciclo di fatturazione per questo abbonamento.
integer
La percentuale di soglia di saldo basso configurata.
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:
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
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