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

# Fatturazione basata sui crediti

> Il payload inviato al tuo endpoint webhook quando si verificano eventi di fatturazione basata sui crediti — crediti virtuali (chiamate API, token, ore di calcolo) concessi, consumati, scaduti, trasferiti o avvisi sul saldo. Questi webhook non sono correlati ai [Customer Wallets](/features/customer-wallet) (saldi monetari).

## 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](/features/customer-wallet) (saldi monetari).

| Event                       | Description                                                                                                     |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `credit.added`              | I crediti vengono concessi a un cliente (tramite abbonamento, acquisto una tantum, componente aggiuntivo o API) |
| `credit.deducted`           | I crediti vengono consumati tramite utilizzo o addebito manuale                                                 |
| `credit.expired`            | I crediti inutilizzati scadono dopo il periodo di scadenza configurato                                          |
| `credit.rolled_over`        | I crediti inutilizzati vengono riportati su una nuova concessione alla fine del ciclo                           |
| `credit.rollover_forfeited` | Crediti annullati perché è stato raggiunto il numero massimo di rollover                                        |
| `credit.overage_charged`    | Addebiti per consumo eccessivo applicati quando l'utilizzo prosegue oltre il saldo zero                         |
| `credit.manual_adjustment`  | Regolazione manuale di credito o addebito effettuata tramite dashboard o API                                    |
| `credit.balance_low`        | Il 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:

```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">
  Il cliente il cui saldo di credito ha attivato l'allerta.
</ParamField>

<ParamField body="subscription_id" type="string">
  L'abbonamento associato a questa concessione di credito.
</ParamField>

<ParamField body="credit_entitlement_id" type="string">
  La concessione di credito che ha un saldo basso.
</ParamField>

<ParamField body="credit_entitlement_name" type="string">
  Nome visualizzato della concessione di credito.
</ParamField>

<ParamField body="available_balance" type="string">
  Saldo attuale del credito al momento dell'avviso.
</ParamField>

<ParamField body="subscription_credits_amount" type="string">
  Crediti totali emessi per ciclo di fatturazione per questo abbonamento.
</ParamField>

<ParamField body="threshold_percent" type="integer">
  La percentuale di soglia di saldo basso configurata.
</ParamField>

<ParamField body="threshold_amount" type="string">
  L'importo assoluto del credito a cui corrisponde la soglia.
</ParamField>

### Utilizzo di `credit.balance_low` per Avvisi Proattivi

Utilizza il webhook `credit.balance_low` per notificare ai clienti prima che esauriscano i crediti:

```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>
  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.
</Tip>

<CardGroup cols={2}>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    Controlla il saldo attuale di un cliente tramite API.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    Accredita o addebita manualmente il saldo di un cliente.
  </Card>
</CardGroup>

## Schema del Payload Webhook