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

> Emetti, gestisci e monitora i diritti di credito tra abbonamenti, prodotti a pagamento singolo e fatturazione basata sull’utilizzo con controlli su rollover, overage e scadenza.

<Frame>
  <iframe className="w-full aspect-video rounded-md" src="https://www.youtube.com/embed/4RR3Yj3Qeuw" title="Credit-Based Billing Tutorial" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</Frame>

<Info>
  La Fatturazione Basata su Crediti ti permette di concedere ai clienti un saldo di crediti - chiamate API, token, unità di calcolo o qualsiasi metrica personalizzata - e di detrarre da quel saldo man mano che consumano il tuo servizio. I crediti funzionano su tutti i tipi di prodotto: abbonamenti, acquisti una tantum e fatturazione basata sull'uso.
</Info>

## Che cos'è la Fatturazione Basata su Crediti?

La Fatturazione Basata su Crediti ti offre un sistema flessibile per emettere diritti di credito ai clienti come parte dei tuoi prodotti. Invece di addebitare per utilizzo o limitare l'accesso tramite flag di funzionalità, puoi allocare un pool di crediti da cui i clienti attingono mentre utilizzano il tuo servizio.

I crediti sono ideali per:

* **Piattaforme AI e LLM**: Concedi token o crediti di generazione per livello di piano
* **Servizi API**: Allocca crediti di chiamata API con prezzi di eccedenza
* **Piattaforme di infrastruttura**: Emetti ore di calcolo o crediti di archiviazione
* **Servizi di comunicazione**: Fornisci crediti di messaggio o minuti per abbonamento
* **SaaS con livelli di consumo**: Includi il consumo incluso in pool di crediti

<Frame caption="Credits appear as entitlements on your products and show in checkout, customer portal, and subscription details.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Checkout.png?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=21880df0e4b0b1a3cb8593dbeb8ae343" alt="Procedura di acquisto che mostra crediti inclusi con l'acquisto del prodotto" width="1440" height="960" data-path="images/CBB/Checkout.png" />
</Frame>

## Concetti di Base

### Tipi di Credito

Quando crei un credito, scegli tra due tipi:

<Tabs>
  <Tab title="Custom Unit">
    Definisci i crediti nella tua unità - token, chiamate API, ore di calcolo o qualsiasi metrica significativa per il tuo prodotto. Le unità personalizzate utilizzano la precisione che imposti (da 0 a 3 decimali).

    **Ideale per**: chiamate API, token AI, ore di calcolo, unità di archiviazione, messaggi
  </Tab>

  <Tab title="Fiat Credits">
    I crediti rappresentano il valore effettivo della valuta (ad esempio, USD, EUR). I clienti ricevono un saldo di credito monetario che si esaurisce man mano che utilizzano il tuo servizio secondo il tuo prezzo definito.

    **Ideale per**: saldi prepagati, crediti promozionali, compensazione di servizio
  </Tab>
</Tabs>

### Ciclo di Vita dei Crediti

I crediti seguono un ciclo di vita chiaro dall'emissione al consumo:

<Steps>
  <Step title="Credits Issued">
    I crediti vengono concessi quando un cliente acquista un prodotto (abbonamento o una tantum) con diritti di credito allegati. Per gli abbonamenti, i crediti vengono ri-emessi ad ogni ciclo di fatturazione.
  </Step>

  <Step title="Credits Consumed">
    Man mano che i clienti utilizzano il tuo servizio, i crediti vengono detratti. Per i prodotti basati sull'uso, i metri detrarre automaticamente i crediti in base a eventi in tempo reale. Puoi anche detrarre crediti manualmente tramite la dashboard o API.
  </Step>

  <Step title="Credits Expire or Roll Over">
    Alla fine del ciclo di fatturazione (o dopo il periodo di scadenza configurato), i crediti non utilizzati scadono o passano al periodo successivo in base alle tue impostazioni.
  </Step>

  <Step title="Overage Handling">
    Se i crediti si esauriscono a metà ciclo, puoi consentire l'eccedenza (continuare l'uso oltre il saldo) e scegliere come gestire l'eccedenza: perdonarla, fatturarla o trasportarla come deficit.
  </Step>
</Steps>

### Fonti di Concessione

I crediti possono essere concessi da più fonti:

| Fonte           | Descrizione                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| **Abbonamento** | Crediti emessi con acquisto di abbonamento, ri-emessi ogni ciclo di fatturazione |
| **Una Tantum**  | Crediti emessi con un prodotto di pagamento una tantum                           |
| **API**         | Crediti concessi manualmente tramite API o dashboard                             |
| **Rollover**    | Crediti trasportati da un precedente ciclo di fatturazione                       |

***

## Creazione di Crediti

Crea diritti di credito nella sezione **Prodotti → Crediti** della tua dashboard. Ogni credito definisce l'unità, la precisione, le regole di scadenza e il comportamento del ciclo di vita.

<Frame caption="The Credits tab under Products shows all your credit entitlements.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Entitlements%20%20-%20Credits.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=f9f30f473d342657d3f0f857e53b2e85" alt="Pagina elenco crediti che mostra i diritti di credito creati" width="3354" height="2004" data-path="images/CBB/Desktop - Entitlements  - Credits.jpg" />
</Frame>

<Steps>
  <Step title="Navigate to Credits">
    Vai a **Prodotti** nella tua dashboard e seleziona la scheda **Crediti**. Fai clic su **Crea Credito** per iniziare.
  </Step>

  <Step title="Configure Basic Information">
    Inserisci un **Nome del Credito** - questo è il tuo identificativo interno per il credito.

    <Frame caption="The credit creation form with all configuration sections.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Create%20Credit.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=0c59e6b6eb4cfd76a545b39fb1f5c19e" alt="Modulo di creazione del credito che mostra informazioni di base, impostazioni generali e impostazioni dell'abbonamento" width="1919" height="954" data-path="images/CBB/Desktop - Create Credit.jpg" />
    </Frame>
  </Step>

  <Step title="Set General Settings">
    Configura il tipo di credito e le proprietà di visualizzazione:

    <ParamField path="Credit Type" type="string" required>
      Scegli **Unità personalizzata** o **Crediti Fiat**.

      * **Unità personalizzata** - Definisci la tua metrica (token, chiamate API, ore di calcolo). Richiede un **Nome dell'Unità** (ad es., "Token della piattaforma") e un'impostazione di **Precisione**.
      * **Crediti Fiat** - I crediti rappresentano il valore reale della valuta. Richiede una selezione di **Valuta dell'Unità** (USD, EUR, GBP, INR, ecc.).
    </ParamField>

    <ParamField path="Unit Name" type="string">
      Solo per crediti di Unità Personalizzata. L'etichetta che i clienti vedranno per questo credito (es., "Token AI", "Chiamate API"). Mostrato in checkout e nel portale clienti.
    </ParamField>

    <ParamField path="Precision" type="number">
      Solo per crediti di Unità Personalizzata. Numero di decimali consentiti:

      * `0` - Numeri interi (ideale per articoli contabilizzabili come chiamate API)
      * `1` - Un decimale (0.0)
      * `2` - Due decimali (0.00) - **predefinito**
      * `3` - Tre decimali (0.000)

      <Warning>
        La precisione non può essere modificata dopo la creazione del credito.
      </Warning>
    </ParamField>

    <ParamField path="Credit Expiry" type="string">
      Quanto a lungo i crediti rimangono validi dopo l'emissione:

      * **7 giorni**, **30 giorni** (predefinito), **60 giorni**, **90 giorni**, **Personalizzato**, o **Mai**

      Seleziona **Personalizzato** per specificare un numero personalizzato di giorni (minimo 1).
    </ParamField>
  </Step>

  <Step title="Configure Subscription Settings (Optional)">
    Queste impostazioni controllano il comportamento dei crediti negli abbonamenti ricorrenti:

    <ParamField path="Rollover" type="boolean">
      Permetti ai crediti non utilizzati di essere trasferiti al ciclo di fatturazione successivo. Quando abilitato, configuralo:

      * **Percentuale Massima di Rollover** (0–100%) - Limita quanto viene trasferito
      * **Periodo di Validità del Rollover** - Quanto tempo i crediti trasferiti rimangono validi (ad es., 1 Mese)
      * **Conteggio Massimo di Rollover** - Massimo di rollover consecutivi prima che i crediti vengano persi
    </ParamField>

    **Quando i Crediti Terminano o l'Abbonamento Scade:**

    <ParamField path="Allow Overage" type="boolean">
      Permetti ai clienti di continuare a utilizzare il tuo servizio dopo che il loro saldo di crediti raggiunge zero. Quando abilitato, configuralo:

      * **Limite di Eccedenza** - Massimi crediti che i clienti possono consumare oltre il loro saldo
      * **Prezzo Per Unità** - Costo per credito aggiuntivo quando l'eccedenza è abilitata (con selettore di valuta)
    </ParamField>

    <ParamField path="Overage Behavior" type="string" required>
      Controlla come viene gestita l'eccedenza alla fine del ciclo di fatturazione:

      * **Perdona l'eccedenza al reset** (predefinito) - L'uso oltre il limite di credito è tracciato ma non fatturato. Il saldo si resetta ad ogni ciclo.
      * **Fattura l'eccedenza alla fatturazione** - L'uso oltre il limite di credito è addebitato sulla prossima fattura, poi il saldo si resetta.
      * **Trasporta il deficit** - L'uso oltre il limite di credito viene portato avanti come saldo negativo nel ciclo successivo.
      * **Trasporta il deficit (ripaga automaticamente)** - Il deficit viene portato avanti ed è automaticamente rimborsato con nuovi crediti nel ciclo successivo.
    </ParamField>
  </Step>

  <Step title="Create Credit">
    Fai clic su **Crea Credito** per salvare. Il credito è ora disponibile per essere allegato a qualsiasi prodotto.

    <Check>
      Il tuo diritto di credito è pronto. Allega ai prodotti per iniziare a emettere crediti ai clienti.
    </Check>
  </Step>
</Steps>

<Tip>
  Inizia con impostazioni semplici - niente rollover, nessuna eccedenza - e aggiungi complessità man mano che impari come i clienti usano i crediti. La maggior parte delle impostazioni può essere aggiornata in qualsiasi momento senza influire sulle concessioni esistenti. Nota che **la precisione non può essere cambiata** dopo la creazione di un credito.
</Tip>

***

## Allegare Crediti ai Prodotti

I crediti sono allegati ai prodotti come **diritti** nel flusso di creazione o modifica del prodotto. Puoi allegare fino a **5 crediti per prodotto**. I crediti funzionano con tutti e tre i tipi di prezzo.

### Prodotti in Abbonamento

Per gli abbonamenti, i crediti vengono emessi **per ciclo di fatturazione** e possono essere configurati con ripartizione, crediti di prova e impostazioni specifiche per il ciclo.

<Steps>
  <Step title="Create or Edit a Subscription Product">
    Vai a **Prodotti → Crea Prodotto** o modifica un prodotto esistente. Seleziona **Abbonamento** come tipo di prezzo e configura il tuo prezzo ricorrente.
  </Step>

  <Step title="Open Entitlements Section">
    Espandi la sezione **Diritti** e fai clic sul pulsante **Allegare** accanto a **Crediti**.

    <Frame caption="The Entitlements section in the product form with Credits, License Key, and Digital Product Delivery options.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20Subscription.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=fb404b5c706ae200079742965a176605" alt="Sezione di diritti del prodotto che mostra il pulsante Allega Crediti" width="2880" height="1920" data-path="images/CBB/Desktop - Attach Credit - Subscription.jpg" />
    </Frame>
  </Step>

  <Step title="Select Credits to Attach">
    Si apre un pannello **Aggiungi Crediti**. Puoi selezionare un credito esistente dal menu a discesa o fare clic su **Crea nuovo credito** per definirne uno sul posto.

    <Frame caption="The Add Credits panel lets you select existing credits or create new ones.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20Subscription-2.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=d67a2a18c7a550c8cf1e8378bd5514dc" alt="Pannello Aggiungi Crediti con selezione a discesa dei crediti" width="2880" height="1920" data-path="images/CBB/Desktop - Attach Credit - Subscription-2.jpg" />
    </Frame>

    <Info>
      Puoi allegare fino a 5 crediti per prodotto. Ogni credito può avere la propria configurazione.
    </Info>
  </Step>

  <Step title="Configure Credit Settings">
    Configura per ciascun credito allegato:

    <ParamField path="Credits issued per billing cycle" type="number" required>
      Il numero di crediti concessi al cliente ogni periodo di fatturazione.
    </ParamField>

    <ParamField path="Low Balance Threshold" type="number">
      Notifica quando i crediti scendono al di sotto di questa quantità. Utile per avvisare i clienti prima che esauriscano.
    </ParamField>

    <ParamField path="Credits During Free Trial" type="number">
      Imposta una differente quantità di credito per i periodi di prova. Abilita **Scadenza dei crediti di prova al termine della prova** per revocare i crediti di prova non utilizzati quando la prova si converte in un abbonamento a pagamento.
    </ParamField>

    <ParamField path="Allow Proration" type="boolean">
      Proteggi i crediti rimanenti quando un cliente aggiorna o degrada il suo piano di abbonamento.
    </ParamField>

    <ParamField path="Import Default Credit Settings" type="boolean">
      Usa le impostazioni predefinite di rollover, eccedenza e scadenza dal diritto di credito. Disattiva questa opzione per personalizzare le impostazioni specificamente per questo prodotto.
    </ParamField>

    <Frame caption="Credit configuration showing per-cycle amount, trial credits, proration, and custom settings.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20Subscription-4.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=68e212dddbec73131cf9f75bf5b55408" alt="Modulo di configurazione del credito con ciclo di fatturazione, prova e impostazioni di ripartizione" width="1800" height="1842" data-path="images/CBB/Desktop - Attach Credit - Subscription-4.jpg" />
    </Frame>
  </Step>

  <Step title="Review and Add">
    Rivedi il credito allegato che mostra nome, quantità e scadenza. Fai clic su **Aggiungi all'Abbonamento** per confermare.

    <Frame caption="Review attached credits before adding them to the subscription.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20Subscription-5.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=7d8a21560061c15cc8544831a59793e2" alt="Pannello Aggiungi Crediti che mostra il credito selezionato con dettagli" width="2880" height="1920" data-path="images/CBB/Desktop - Attach Credit - Subscription-5.jpg" />
    </Frame>
  </Step>
</Steps>

### Prodotti a Pagamento Unico

Per i pagamenti una tantum, i crediti vengono emessi **una volta sola** al momento dell'acquisto.

<Steps>
  <Step title="Create a One-Time Product">
    Crea un prodotto con il tipo di prezzo **Pagamento Singolo**.

    <Frame caption="Single Payment pricing selected for a one-time credit product.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20OTP.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=1743cb3e515952f9d4b1b2782cebac8b" alt="Sezione di prezzo del prodotto con Pagamento Singolo selezionato" width="2880" height="1920" data-path="images/CBB/Desktop - Attach Credit - OTP.jpg" />
    </Frame>
  </Step>

  <Step title="Attach Credits">
    Apri la sezione **Diritti** e allega i crediti. Configura il **numero di crediti emessi** (concessione totale una tantum) all'acquisto.
  </Step>
</Steps>

<Tip>
  I prodotti di credito una tantum sono ideali per pacchetti di ricarica, pacchetti promozionali o acquisti di credito prepagati.
</Tip>

### Prodotti con Fatturazione Basata sull'Uso

Per i prodotti basati sull'uso, i crediti sono **collegati ai metri** e dedotti automaticamente in base agli eventi di consumo in tempo reale.

<Steps>
  <Step title="Create a Usage-Based Product">
    Seleziona **Fatturazione Basata sull'Uso** come tipo di prezzo. Configura il prezzo base e la frequenza di fatturazione.

    <Frame caption="Usage Based Billing pricing type with meter configuration.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20UBB.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=41b2862c12d126e7843098307e27e137" alt="Configurazione del prezzo per Fatturazione Basata sull'Uso" width="2880" height="1920" data-path="images/CBB/Desktop - Attach Credit - UBB.jpg" />
    </Frame>
  </Step>

  <Step title="Add a Meter">
    Fai clic sul pulsante **+** nella sezione **Seleziona metro** per aggiungere un metro. Un abbonamento può avere fino a **3 metri**.

    <Frame caption="The Select Meter panel with meter configuration and credit toggle.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20UBB-3.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=3f677352783684107eaa7e568d9352e2" alt="Pannello Seleziona Metro che mostra soglia gratuita e toggle dei crediti" width="2880" height="1920" data-path="images/CBB/Desktop - Attach Credit - UBB-3.jpg" />
    </Frame>
  </Step>

  <Step title="Enable Credit Billing on the Meter">
    Attiva **Fattura l'uso in Crediti** per allegare un credito al metro. Seleziona il diritto di credito dal menu a discesa.

    <ParamField path="Free Threshold" type="number" required>
      Il numero di unità che sono gratuite prima che inizi la detrazione dei crediti.
    </ParamField>

    <ParamField path="Bill usage in Credits" type="boolean">
      Quando abilitato, l'uso del metro detrae dal saldo dei crediti del cliente invece di addebitare per unità.
    </ParamField>

    <ParamField path="Meter units per credit" type="number" required>
      Il numero di unità di uso necessarie per detrarre 1 credito. Ad esempio, se impostato su `1000`, allora 1.000 chiamate API consumano 1 credito.
    </ParamField>

    <Frame caption="Credit attached to a meter with per-unit conversion rate.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20UBB-5.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=b4ef2fe5079cbf3bb39eb3814f101cbd" alt="Configurazione del metro con selezione dei crediti e unità del metro per credito" width="2880" height="2282" data-path="images/CBB/Desktop - Attach Credit - UBB-5.jpg" />
    </Frame>
  </Step>

  <Step title="Configure Credit Issuance">
    Imposta il numero di crediti emessi e personalizza opzionalmente le impostazioni del credito per questo prodotto.

    <Frame caption="Configure how many credits to issue and whether to use default settings.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20UBB-6.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=22e99c54f11305a24d63c77e09a4650c" alt="Configurazione del credito per prodotto UBB" width="2880" height="1920" data-path="images/CBB/Desktop - Attach Credit - UBB-6.jpg" />
    </Frame>
  </Step>

  <Step title="Verify Attachment">
    Una volta configurato, il metro mostra il nome del credito allegato, il prezzo per unità e la soglia gratuita.

    <Frame caption="Meter with credit attached showing price, threshold, and credit name.">
      <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Attach%20Credit%20-%20UBB-1.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=d1a68ef9f07872b1dc9d2b2a655df0a4" alt="Metro configurato che mostra i dettagli dell'allegato di credito" width="3220" height="1830" data-path="images/CBB/Desktop - Attach Credit - UBB-1.jpg" />
    </Frame>
  </Step>
</Steps>

<Info>
  Quando i crediti sono collegati ai metri, il sistema detrae automaticamente i crediti in base a eventi di consumo acquisiti. Un lavoratore in background elabora eventi ogni minuto, li aggrega secondo la configurazione del metro e applica FIFO (primo ingresso, primo esaurimento) deduzione dai concessioni dei clienti più vecchi non scaduti.
</Info>

***

## Impostazioni del Credito

### Rollover

Il rollover consente ai crediti non utilizzati di essere trasportati al ciclo di fatturazione successivo invece di scadere.

| Impostazione                         | Descrizione                                                                                                                              |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Rollover Abilitato**               | Attiva per consentire ai crediti non utilizzati di essere trasportati                                                                    |
| **Percentuale Massima di Rollover**  | Limita quanto viene trasportato (0–100%). Al 50%, solo la metà dei crediti non utilizzati viene trasportata                              |
| **Periodo di Validità del Rollover** | Quanto tempo i crediti trasportati rimangono validi (giorno, settimana, mese, anno)                                                      |
| **Conteggio Massimo di Rollover**    | Numero massimo di volte che i crediti possono essere trasportati consecutivamente. Dopo questo limite, i crediti rimanenti vengono persi |

**Esempio**: Un cliente ha 200 crediti non utilizzati alla fine del ciclo. Con un rollover del 75%, 150 crediti vengono trasportati e 50 vengono persi.

### Eccedenza

L'eccedenza controlla cosa succede quando il saldo di crediti di un cliente raggiunge zero a metà ciclo.

| Impostazione                     | Descrizione                                                                                            |
| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Consenti Eccedenza**           | Attiva per consentire ai clienti di continuare a utilizzare il servizio oltre il loro saldo di crediti |
| **Limite di Eccedenza**          | Massimi crediti che i clienti possono consumare oltre il loro saldo                                    |
| **Prezzo Per Unità**             | Costo per credito aggiuntivo consumato come eccedenza (con valuta)                                     |
| **Comportamento dell'Eccedenza** | Controlla cosa succede all'eccedenza alla fine del ciclo di fatturazione (vedi sotto)                  |

**Opzioni di Comportamento dell'Eccedenza:**

| Comportamento                                     | Descrizione                                                                                           |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Perdona l'eccedenza al reset**                  | L'uso oltre il limite di credito è tracciato ma non fatturato. Il saldo si resetta ad ogni ciclo      |
| **Fattura l'eccedenza alla fatturazione**         | L'uso oltre il limite di credito è addebitato sulla prossima fattura, poi il saldo si resetta         |
| **Trasporta il deficit**                          | L'eccedenza viene portata avanti come saldo negativo nel ciclo successivo                             |
| **Trasporta il deficit (ripaga automaticamente)** | Il deficit viene portato avanti ed è automaticamente rimborsato da nuovi crediti nel ciclo successivo |

<Info>
  Quando l'eccedenza è disabilitata, i clienti non possono utilizzare il servizio una volta che il loro saldo di crediti raggiunge zero. Scegli un comportamento di eccedenza che corrisponda al tuo modello di fatturazione - **Perdona al reset** è l'opzione predefinita e più semplice.
</Info>

### Scadenza

| Impostazione                                    | Descrizione                                                                                     |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Scadenza dei Crediti**                        | Durata dopo l'emissione prima che i crediti scadano (7, 30, 60, 90 giorni personalizzati o mai) |
| **Scadenza dei Crediti di Prova Dopo la Prova** | Se i crediti specifici per la prova scadono quando il periodo di prova termina                  |

<Info>
  I crediti scaduti creano una voce di registro `CreditExpired`. Se il rollover è abilitato, la percentuale di rollover viene applicata prima della scadenza e solo il restante scade.
</Info>

***

## Fatturazione ad Uso con Crediti

Quando i crediti sono collegati ai metri di uso, il sistema crea un potente modello di fatturazione basato sul consumo. I clienti ricevono un'allocazione di crediti e gli eventi di utilizzo detraggono automaticamente dal loro saldo.

<Frame caption="The Usage Billing dashboard shows meter events with units consumed, credits consumed, and customer details.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Usage%20Billing.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=de8c5992d0ae59e74bbb8a840e07454f" alt="Dashboard di Fatturazione ad Uso che mostra tabella degli eventi con crediti consumati" width="2880" height="1920" data-path="images/CBB/Desktop - Usage Billing.jpg" />
</Frame>

### Come Funziona la Detrazione di Crediti Basata su Metro

1. **La tua applicazione invia eventi di utilizzo** - Ogni evento include un ID cliente, nome dell'evento e metadati
2. **I misuratori aggregano gli eventi** - Usando Count, Sum, Max, o Last come aggregazione
3. **I crediti vengono detratti automaticamente** - Un lavoratore in background elabora gli eventi ogni minuto, converte le unità del misuratore in crediti usando il tuo tasso configurato e detrae dal saldo del cliente usando l'ordinamento FIFO (prima i grant più vecchi)
4. **L'eccedenza viene monitorata** - Se il saldo del credito raggiunge zero e l'eccedenza è abilitata, il sistema monitora l'uso in eccedenza per la fatturazione di fine ciclo

### Pannello Metri

La dashboard di Fatturazione ad Uso include un pannello **Metri** che elenca tutti i metri definiti con il loro tipo di aggregazione:

| Aggregazione | Descrizione                 | Esempio                      |
| ------------ | --------------------------- | ---------------------------- |
| **Count**    | Numero totale di eventi     | Chiamate API                 |
| **Sum**      | Somma di un campo di valore | Totale byte trasferiti       |
| **Max**      | Valore più alto registrato  | Massimo utenti contemporanei |
| **Last**     | Valore più recente          | Memoria attuale utilizzata   |

***

## Esperienza del Cliente

### Checkout

Quando un cliente acquista un prodotto con crediti allegati, la pagina di checkout mostra i crediti inclusi come parte dell'offerta del prodotto.

<Frame caption="Checkout shows included credits with the product, making the value proposition clear.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Checkout.png?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=21880df0e4b0b1a3cb8593dbeb8ae343" alt="Pagina di checkout che mostra prodotto con crediti di chiamata inclusi" width="1440" height="960" data-path="images/CBB/Checkout.png" />
</Frame>

I crediti appaiono in una sezione **Inclusi** sotto la descrizione del prodotto, mostrando l'importo del credito e il tipo (ad esempio, "\$1000 chiamate API").

### Portale del Cliente

I clienti possono visualizzare e gestire i loro saldi di credito nel Portale Clienti sotto la sezione **Crediti**.

<Frame caption="The Customer Portal shows available balance and full transaction history.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Customer%20Portal.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=b8afe1f89242f9e347b26b990dd00fe8" alt="Visualizzazione dei crediti del Portale Clienti con saldo e cronologia delle transazioni" width="3016" height="2030" data-path="images/CBB/Customer Portal.jpg" />
</Frame>

Il portale visualizza:

* **Saldo Disponibile** - Saldo attuale di crediti visualizzato in modo prominente
* **Schede di Credito** - Cambia tra diversi tipi di credito (ad es., "Crediti OpenAI", "Token di Utilizzo")
* **Transazioni Recenti** - Cronologia completa con data, ID transazione, tipo, importo e saldo corrente

I tipi di transazione mostrati ai clienti includono:

| Tipo                        | Descrizione                                          | Importo   |
| --------------------------- | ---------------------------------------------------- | --------- |
| **Crediti con Abbonamento** | Crediti emessi con acquisto/rinnovo abbonamento      | Verde (+) |
| **Crediti Una Tantum**      | Crediti da acquisti una tantum o concessioni manuali | Verde (+) |
| **Detrazione Uso**          | Crediti consumati attraverso l'uso del servizio      | Rosso (-) |
| **Eccedenza**               | Uso oltre il saldo di credito                        | Rosso (-) |

### Dettagli dell'Abbonamento

La pagina dei dettagli dell'abbonamento mostra i diritti di credito accanto ad altre informazioni sul piano.

<Frame caption="Subscription details show credit allocation, remaining balance, and renewal date.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Subscription%20Details.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=059f57f8996c1f514b9d7eba1ef6e33a" alt="Pagina dei dettagli dell'abbonamento che mostra diritti e cronologia dell'uso" width="2880" height="1984" data-path="images/CBB/Desktop - Subscription Details.jpg" />
</Frame>

Informazioni chiave visualizzate:

* **Allocazione del credito** per ciclo di fatturazione (ad es., "1000 crediti per ciclo")
* **Saldo rimanente** (ad es., "7500 crediti rimanenti")
* **Data di rinnovo** per la prossima emissione di crediti
* **Cronologia dell'uso** tab con dettaglio per livello metro che mostra le unità consumate, soglie, prezzi unitari e costi totali

### Dettagli della Transazione

Le pagine delle transazioni di pagamento includono una sezione **Diritti** che mostra tutti i diritti consegnati con il pagamento, inclusi i crediti.

<Frame caption="Transaction details show credits alongside other entitlements like license keys and digital downloads.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Transactions%20-%20Payment%20Summary.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=dccb0ada7682ead4493baf71199a86fb" alt="Pagina dei dettagli della transazione che mostra diritti di credito" width="2880" height="2752" data-path="images/CBB/Desktop - Transactions - Payment Summary.jpg" />
</Frame>

***

## Gestione dei Crediti

### Visualizzazioni della Dashboard

#### Elenco dei Diritti di Credito

Visualizza tutti i tuoi diritti di credito in **Prodotti → Crediti**. La tabella mostra il nome del credito, le impostazioni di scadenza e fornisce azioni rapide per la modifica o l'archiviazione.

<Frame caption="Credits listing with total count, creation button, and management actions.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Entitlements%20%20-%20Credits.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=f9f30f473d342657d3f0f857e53b2e85" alt="Pagina elenco dei crediti nella sezione Prodotti" width="3354" height="2004" data-path="images/CBB/Desktop - Entitlements  - Credits.jpg" />
</Frame>

#### Dettagli Crediti Clienti

Visualizza i saldi dei crediti e la cronologia delle transazioni di uno specifico cliente in **Clienti → \[Nome Cliente] → Crediti**.

<Frame caption="Customer detail page showing credit balance and full transaction ledger.">
  <img src="https://mintcdn.com/dodopayments/ibNfoFRyCIGyt3pO/images/CBB/Desktop%20-%20Customer%20Details.jpg?fit=max&auto=format&n=ibNfoFRyCIGyt3pO&q=85&s=a52e7e914338d698bf72498821f6a8b6" alt="Pagina dettagli cliente con scheda Crediti che mostra saldo e transazioni" width="2880" height="1920" data-path="images/CBB/Desktop - Customer Details.jpg" />
</Frame>

La visualizzazione dei crediti cliente include:

* **Selettore di Credito** - Cambia tra diversi diritti di credito
* **Saldo Disponibile** - Saldo corrente in grande, display prominente
* **Applica Credito/Debit** - Pulsante per regolare manualmente il saldo del cliente
* **Transazioni Recenti** - Registro completo con data, ID transazione, tipo, importo e saldo corrente

### Regolazioni Manuali

Puoi accreditare o addebitare manualmente il saldo di un cliente direttamente dalla dashboard:

<Steps>
  <Step title="Navigate to Customer">
    Vai a **Clienti** e seleziona il cliente.
  </Step>

  <Step title="Open Credits Tab">
    Fai clic sulla scheda **Crediti** e seleziona il diritto di credito appropriato dal selettore del portafoglio.
  </Step>

  <Step title="Apply Credit or Debit">
    Fai clic su **Applica Credito/Debito** per aprire l'interfaccia di regolazione.

    <ParamField path="Transaction Type" type="string" required>
      Seleziona **Credito** per aggiungere crediti o **Debito** per rimuovere crediti dal saldo del cliente.
    </ParamField>

    <ParamField path="Amount" type="number" required>
      Il numero di crediti da aggiungere o rimuovere.
    </ParamField>

    <ParamField path="Reason" type="string">
      Spiegazione opzionale per la regolazione (es., "Compensazione servizio", "Bonus promozionale").
    </ParamField>
  </Step>

  <Step title="Confirm">
    Rivedi e applica la regolazione. La modifica è immediatamente riflessa nel saldo del cliente e registrata nel registro dei crediti.

    <Check>
      Le regolazioni manuali creano una voce di registro `ManualAdjustment` con pista di controllo completa.
    </Check>
  </Step>
</Steps>

### Registro Crediti

Ogni operazione di credito è registrata nel registro dei crediti, fornendo una pista di controllo completa:

| Tipo di Transazione      | Descrizione                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------- |
| **Credito Aggiunto**     | Crediti concessi (abbonamento, una tantum o API)                                      |
| **Credito Detratto**     | Crediti consumati tramite uso o addebito manuale                                      |
| **Credito Scaduto**      | Crediti scaduti senza rollover                                                        |
| **Credito Transpotato**  | Crediti portati al periodo successivo                                                 |
| **Rollover Perso**       | Crediti trasportati persi dopo che il conteggio massimo di rollover è stato raggiunto |
| **Eccedenza Addebitata** | Uso oltre il saldo di credito con eccedenza abilitata                                 |
| **Ricarica Automatica**  | Ripristino automatico del credito a basso saldo                                       |
| **Regolazione Manuale**  | Credito o debito applicato manualmente da commerciante                                |
| **Rimborso**             | Crediti rimborsati                                                                    |

Ogni voce di registro registra il saldo prima e dopo la transazione, eccedenza prima e dopo, una descrizione e riferimento alla fonte (pagamento, abbonamento, ecc.).

***

## Webhooks

La Fatturazione Basata su Crediti attiva eventi webhook per ogni cambiamento del ciclo di vita del credito. Usa questi per mantenere sincronizzata la tua applicazione con i saldi di crediti, attivare notifiche o costruire flussi di lavoro di fatturazione personalizzati.

| Evento                      | Descrizione                                           |
| --------------------------- | ----------------------------------------------------- |
| `credit.added`              | Crediti concessi a un cliente                         |
| `credit.deducted`           | Crediti consumati attraverso uso o addebito manuale   |
| `credit.expired`            | Crediti non utilizzati scaduti                        |
| `credit.rolled_over`        | Crediti portati a una nuova concessione               |
| `credit.rollover_forfeited` | Crediti persi al conteggio massimo di rollover        |
| `credit.overage_charged`    | Addebiti per eccedenza applicati                      |
| `credit.manual_adjustment`  | Regolazione manuale di credito/debito effettuata      |
| `credit.balance_low`        | Il saldo è sceso al di sotto della soglia configurata |

Tutti gli eventi del ledger (`credit.added` fino a `credit.manual_adjustment`) includono l'intero payload `CreditLedgerEntry` con saldo prima/dopo, eccedenza prima/dopo, riferimento della fonte, e l'`metadata` dell'abbonamento di origine della concessione o del pagamento (vuoto per le concessioni create direttamente tramite l'API). L'evento `credit.balance_low` include la configurazione della soglia e il saldo attuale.

<Card title="Credit Webhook Payloads" icon="bell" href="/developer-resources/webhooks/intents/credit">
  Visualizza schemi di payload completi, descrizioni dei campi ed esempi di integrazione per tutti gli eventi webhook di credito.
</Card>

***

## Gestione API

<AccordionGroup>
  <Accordion title="Create Credit Entitlements">
    Utilizza l'API per creare diritti di credito programmaticamente con controllo completo su rollover, eccedenza e impostazioni di scadenza.

    <CardGroup cols={2}>
      <Card title="Create Credit Entitlement" icon="plus" href="/api-reference/credit-entitlements/create-credit-entitlement">
        Crea un nuovo diritto di credito con configurazione di rollover, eccedenza e scadenza.
      </Card>

      <Card title="List Credit Entitlements" icon="list" href="/api-reference/credit-entitlements/list-credit-entitlements">
        Recupera tutti i diritti di credito per la tua attività.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Manage Credit Entitlements">
    Recupera, aggiorna o elimina diritti di credito. I diritti eliminati possono essere ripristinati.

    <CardGroup cols={2}>
      <Card title="Get Credit Entitlement" icon="magnifying-glass" href="/api-reference/credit-entitlements/get-credit-entitlement">
        Recupera un diritto di credito specifico per ID.
      </Card>

      <Card title="Update Credit Entitlement" icon="pen" href="/api-reference/credit-entitlements/update-credit-entitlement">
        Aggiorna il rollover, l'eccedenza, la scadenza o altre impostazioni.
      </Card>

      <Card title="Delete Credit Entitlement" icon="trash" href="/api-reference/credit-entitlements/delete-credit-entitlement">
        Elimina soft un diritto di credito.
      </Card>

      <Card title="Undelete Credit Entitlement" icon="rotate-left" href="/api-reference/credit-entitlements/undelete-credit-entitlement">
        Ripristina un diritto di credito precedentemente eliminato.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Grant and Adjust Credits">
    Concedi crediti direttamente al saldo di un cliente senza richiedere un acquisto o crea voci di addebito manuali per regolazioni di fatturazione.

    <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
      Accredita o addebita il saldo di un cliente con piena pista di controllo e supporto per l'idempotenza.
    </Card>
  </Accordion>

  <Accordion title="Query Balances and Ledger">
    Recupera il saldo del credito attuale di un cliente, la cronologia delle concessioni e il registro completo delle transazioni per qualsiasi diritto di credito.

    <CardGroup cols={2}>
      <Card title="List Balances" icon="wallet" href="/api-reference/credit-entitlements/list-balances">
        Elenca tutti i saldi dei clienti per un diritto di credito.
      </Card>

      <Card title="Get Customer Balance" icon="user" href="/api-reference/credit-entitlements/get-customer-balance">
        Ottieni il saldo specifico di un cliente.
      </Card>

      <Card title="List Customer Grants" icon="gift" href="/api-reference/credit-entitlements/list-customer-grants">
        Visualizza tutte le concessioni di credito per un cliente.
      </Card>

      <Card title="List Customer Ledger" icon="scroll" href="/api-reference/credit-entitlements/list-customer-ledger">
        Cronologia completa delle transazioni per un cliente.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

### Esempio di Integrazione

Inizializza il client di Dodo Payments:

```typescript theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode', // defaults to 'live_mode'
});
```

Allega crediti a un prodotto in abbonamento durante il checkout:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ai_pro_plan',
      quantity: 1,
    }
  ],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yourapp.com/success'
});
```

Invia eventi di utilizzo che detraggono automaticamente i crediti:

```typescript theme={null}
await client.usageEvents.ingest({
  events: [{
    event_id: `gen_${Date.now()}`,
    customer_id: 'cus_abc123',
    event_name: 'ai.generation',
    timestamp: new Date().toISOString(),
    metadata: { model: 'gpt-4', tokens: 1500 }
  }]
});
```

***

## Esempi Reali

<AccordionGroup>
  <Accordion title="AI SaaS Platform">
    **Struttura Prezzi:**

    | Piano      | Prezzo   | Crediti/Mese    | Eccedenza     |
    | ---------- | -------- | --------------- | ------------- |
    | Starter    | \$29/mo  | 10,000 token    | \$0.003/token |
    | Pro        | \$99/mo  | 100,000 token   | \$0.002/token |
    | Enterprise | \$499/mo | 1,000,000 token | \$0.001/token |

    **Configurazione:**

    * Tipo di Credito: Unità Personalizzata ("Token AI")
    * Precisione: 0 (token interi)
    * Rollover: 25% max, durata 1 mese
    * Eccedenza: abilitata, fattura eccedenza alla fatturazione
    * Metro: `ai.generation` con aggregazione Sum su campo `tokens`
  </Accordion>

  <Accordion title="API Gateway">
    **Struttura Prezzi:**

    | Piano     | Prezzo  | Crediti/Mese     | Eccedenza         |
    | --------- | ------- | ---------------- | ----------------- |
    | Free      | \$0/mo  | 1,000 chiamate   | Bloccato          |
    | Developer | \$19/mo | 50,000 chiamate  | \$0.001/chiamata  |
    | Business  | \$99/mo | 500,000 chiamate | \$0.0005/chiamata |

    **Configurazione:**

    * Tipo di Credito: Unità Personalizzata ("Chiamate API")
    * Precisione: 0 (chiamate intere)
    * Rollover: Disabilitato
    * Eccedenza: piani Developer+ consentono eccedenza (perdona al reset), piano Free disabilita eccedenza
    * Metro: `api.request` con aggregazione Count
  </Accordion>

  <Accordion title="Cloud Storage Service">
    **Struttura Prezzi:**

    | Piano    | Prezzo  | Crediti/Mese | Eccedenza     |
    | -------- | ------- | ------------ | ------------- |
    | Personal | \$9/mo  | 100 ore-GB   | \$0.05/ora-GB |
    | Team     | \$49/mo | 1,000 ore-GB | \$0.03/ora-GB |

    **Configurazione:**

    * Tipo di Credito: Unità Personalizzata ("Ore-GB")
    * Precisione: 2 (due decimali)
    * Rollover: 50% max, trasporta una volta
    * Eccedenza: abilitata con limite al 200%
    * Metro: `storage.usage` con aggregazione Sum
  </Accordion>
</AccordionGroup>

***

## Migliori Pratiche

* **Inizia semplice**: Comincia con un singolo tipo di credito e nessun rollover. Aggiungi complessità basata sul feedback dei clienti e sui modelli di utilizzo.
* **Imposta aspettative chiare**: Mostra allocazioni di credito, saldi rimanenti e prezzi di eccedenza in modo prominente nelle pagine dei tuoi prodotti e nel portale clienti.
* **Usa unità significative**: Dai un nome ai crediti basato su ciò che rappresentano (es., "Chiamate API", "Token AI") piuttosto che termini generici. Questo aiuta i clienti a capire il valore.
* **Configura la scadenza con attenzione**: Finestre di scadenza brevi (7 giorni) creano urgenza ma possono frustrare i clienti. Finestre più lunghe (30–90 giorni) sono più adatte ai prodotti SaaS.
* **Monitora i saldi bassi**: Imposta soglie di saldo basso per avvisare i clienti prima che esauriscano, riducendo i costi di eccedenza a sorpresa.
* **Test in modalità di test**: Crea crediti, allegali a prodotti di test e simula il ciclo completo (acquisto → uso → detrazione → scadenza) prima di andare live.

<Info>
  La Fatturazione Basata su Crediti funziona perfettamente con tutte le altre funzionalità di Dodo Payments - abbonamenti con prove, cambi di piano con ripartizione e il portale clienti. Inizia con una configurazione di base ed espandi man mano che il tuo modello di prezzo evolve.
</Info>