> ## 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.
# v1.86.0 (2 marzo 2026)
> Fatturazione basata sui crediti con rollover, controlli di overage e scadenza, hub unificato per la personalizzazione di design e tema, stato di rimborsi e dispute nell’API di elenchi pagamenti, tabella dei rimborsi nel portale clienti e copia in modalità live per i contatori
## Nuove funzionalità
### 1. **Fatturazione basata sui crediti**
Dodo Payments ora supporta la **fatturazione basata sui crediti**, un sistema flessibile per emettere, gestire e monitorare i diritti di credito attraverso abbonamenti, prodotti una tantum e la fatturazione basata sull’utilizzo. Invece di addebitare per uso o limitare l’accesso tramite flag di funzionalità, assegni un pool di crediti che i clienti utilizzano man mano che consumano il tuo servizio.
**Cosa puoi fare**
| Funzionalità | Descrizione |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Unità personalizzate o crediti fiat** | Definisci i crediti nella tua unità (chiamate API, token, ore di calcolo) o come valore in valuta reale (USD, EUR) |
| **Crediti per abbonamento** | Emetti crediti per ciclo di fatturazione con riemissione automatica al rinnovo |
| **Crediti una tantum** | Concedi un saldo fisso di crediti all’acquisto, ideale per pacchetti di ricarica o bundle promozionali |
| **Detrazione basata sull’utilizzo** | Collega i crediti ai contatori per una detrazione automatica in base agli eventi di consumo in tempo reale |
| **Rollover** | Consenti ai crediti inutilizzati di essere riportati avanti con percentuale massima, intervallo temporale e numero di rollover configurabili |
| **Controlli di overage** | Permetti ai clienti di continuare ad usare il servizio oltre il saldo, con opzioni per perdonare, addebitare o trasferire il deficit |
| **Scadenza** | Imposta la validità dei crediti da 7 giorni a mai, con numero di giorni personalizzato |
**Ciclo di vita dei crediti**
1. **Crediti emessi** - Concessi quando un cliente acquista un prodotto con diritti di credito associati. Per gli abbonamenti, i crediti vengono riemessi a ogni ciclo di fatturazione.
2. **Crediti consumati** - Detraibili man mano che i clienti utilizzano il servizio. I contatori detrattono automaticamente i crediti in base agli eventi in tempo reale, oppure puoi detrarli manualmente tramite dashboard o API.
3. **Crediti che scadono o si trasformano in rollover** - Alla fine del ciclo di fatturazione (o dopo il periodo di scadenza configurato), i crediti inutilizzati scadono o vengono trasferiti in base alle impostazioni.
4. **Gestione degli overage** - Se i crediti finiscono a metà ciclo, puoi consentire l’uso continuato e decidere come gestire l’overage a fine ciclo.
**Come associare crediti ai prodotti**
I crediti vengono aggiunti come **diritti** nel flusso di creazione del prodotto. Puoi associare fino a **3 crediti per prodotto** e funzionano con tutti e tre i tipi di prezzo: abbonamenti, pagamenti una tantum e fatturazione basata sull’utilizzo.
```typescript theme={null}
// Create a checkout session for a product with attached credits
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: 'pdt_ai_pro_plan',
quantity: 1,
}
],
customer: { email: 'customer@example.com' },
return_url: 'https://yourapp.com/success'
});
```
**Detrazione basata sull’utilizzo**
Quando i crediti sono collegati ai contatori, il sistema li detrae automaticamente in base agli eventi di utilizzo acquisiti. Configura il tasso **unità del contatore per credito** per controllare la conversione (es. 1.000 chiamate API = 1 credito).
```typescript theme={null}
// Send usage events that deduct credits automatically
await fetch('https://test.dodopayments.com/events/ingest', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
events: [{
event_id: `gen_${Date.now()}`,
customer_id: 'cus_abc123',
event_name: 'ai.generation',
timestamp: new Date().toISOString(),
metadata: { model: 'gpt-4', tokens: 1500 }
}]
})
});
```
**Esperienza del cliente**
I clienti possono visualizzare e gestire i saldi dei propri crediti nel **Portale clienti** nella sezione Crediti, con saldo disponibile, cronologia delle transazioni e ripartizioni di utilizzo. I crediti compaiono anche al checkout, nei dettagli dell’abbonamento e nelle pagine delle transazioni di pagamento.
**Webhook**
La fatturazione basata sui crediti genera eventi webhook per ogni modifica del ciclo di vita dei crediti:
| Evento | Descrizione |
| --------------------------- | -------------------------------------------------------------- |
| `credit.added` | Crediti concessi a un cliente |
| `credit.deducted` | Crediti consumati tramite utilizzo o addebito manuale |
| `credit.expired` | Crediti inutilizzati scaduti |
| `credit.rolled_over` | Crediti trasferiti a una nuova assegnazione |
| `credit.rollover_forfeited` | Crediti persi al raggiungimento del numero massimo di rollover |
| `credit.overage_charged` | Addebitati oneri per overage |
| `credit.manual_adjustment` | Regolazione manuale di credito/debito effettuata |
| `credit.balance_low` | Saldo sceso sotto la soglia configurata |
Inizia con impostazioni semplici, senza rollover e senza overage, 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 assegnazioni esistenti.
Scopri di più: [Credit-Based Billing](/features/credit-based-billing) | [Credit Webhook Payloads](/developer-resources/webhooks/intents/credit) | [Credit Entitlements API](/api-reference/credit-entitlements/create-credit-entitlement)
### 2. **Personalizzazione di design e tema**
Presentiamo la nuova pagina **Design**, un hub unificato per personalizzare l’aspetto del checkout, dello storefront e del portale clienti da un’unica posizione. Scegli temi predefiniti, configura tipografia e colori e applica override per sezione, il tutto con un’anteprima live prima di salvare.
**Punti salienti**
| Funzionalità | Descrizione |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| **Hub di design unificato** | Configura l’aspetto di checkout, storefront e portale clienti da un’unica pagina |
| **Temi predefiniti** | Parti da un tema curato (Dodo Pulses, Terminal, Bumblebee o Bubblegum) e personalizza da lì |
| **Modalità chiara e scura** | Definisci palette di colori separate per ciascuna modalità |
| **Anteprima live** | Visualizza come appaiono le modifiche su checkout, portale clienti e storefront prima di salvare |
| **Override per sezione** | Affina singole sezioni senza influenzare le altre |
| **Controllo programmatico** | Sovrascrivi i temi in fase di checkout tramite API o Checkout SDK |
**Per iniziare**
Vai su **Design** nella barra laterale principale della tua Merchant Dashboard. La pagina ha quattro schede:
| Scheda | Scopo |
| ------------------- | ----------------------------------------------------------------------------- |
| **Generale** | Nome azienda, logo, selezione del tema e impostazioni avanzate globali |
| **Checkout** | Sovrascrivi le impostazioni del tema specificamente per la pagina di checkout |
| **Storefront** | Sovrascrivi le impostazioni del tema e configura il layout dello storefront |
| **Portale clienti** | Sovrascrivi le impostazioni del tema per il portale clienti |
**Impostazioni avanzate**
Espandi le impostazioni avanzate nella scheda Generale per avere un controllo granulare sulla tipografia (Google Font primari/secondari, dimensione, peso), sulla configurazione dei colori (palette separate per modalità chiara e scura che coprono sfondi, testo, pulsanti e bordi) e sul raggio di curvatura per regolare gli angoli degli elementi UI.
**Temi predefiniti**
Quattro temi curati sono disponibili out-of-the-box:
* **Dodo Pulses** - Tema predefinito con accenti verde lime e tipografia sans-serif pulita
* **Terminal** - Pensato per sviluppatori con tipografia monospaziata e accenti blu reale
* **Bumblebee** - Accenti ambrati e oro con stile audace e premium
* **Bubblegum** - Accenti rosa e magenta giocosi con angoli completamente arrotondati
Dopo aver selezionato un tema predefinito, puoi personalizzare ulteriormente le proprietà individuali nelle impostazioni avanzate. Le proprietà non specificate tornano ai valori predefiniti del tema.
Scopri di più: [Design & Theme Customization](/features/design) | [Checkout Features](/features/checkout) | [Storefront](/features/storefront)
### 3. **Stato di rimborso e disputa nell’API List Payments**
L’endpoint di elenco `GET /payments` ora include i campi `refund_status` e `dispute_status` in ogni voce di pagamento, così puoi vedere lo stato di rimborso e disputa in un colpo d’occhio senza recuperare i dettagli singoli di ciascun pagamento.
| Campo | Tipo | Descrizione |
| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------- |
| `refund_status` | `partial \| full \| null` | Riepilogo dello stato del rimborso per questo pagamento. `null` se non esistono rimborsi riusciti |
| `dispute_status` | `string \| null` | Lo stato più recente della disputa per questo pagamento. `null` se non esistono dispute |
**Valori di `dispute_status`**: `dispute_opened`, `dispute_expired`, `dispute_accepted`, `dispute_cancelled`, `dispute_challenged`, `dispute_won`, `dispute_lost`
Utilizza questi campi per costruire dashboard di dispute e rimborsi, attivare avvisi sui cambi di stato delle dispute o evidenziare pagamenti che necessitano di attenzione.
Per saperne di più: [List Payments API](/api-reference/payments/get-payments)
### 4. **Tabella Rimborsi nel Portale Clienti**
Il Portale Clienti ora include una sezione dedicata ai **Rimborsi** dove i clienti possono visualizzare tutti i rimborsi associati ai loro pagamenti. Ogni voce di rimborso mostra l'importo del rimborso, lo stato, la data e il pagamento originale a cui è stato emesso, offrendo ai clienti piena trasparenza sulla loro storia di rimborsi senza bisogno di contattare il supporto.
La tabella dei rimborsi è disponibile automaticamente nel portale clienti per tutte le aziende. Non è necessaria alcuna configurazione.
Per saperne di più: [Customer Portal](/features/customer-portal)
### 5. **Copia in Modalità Live per i Contatori**
Ora puoi **copiare i contatori dalla modalità test alla modalità live** direttamente dal dashboard. Quando hai finito di testare una configurazione di contatore in modalità test, utilizza l'azione di copia per replicarla in modalità live con tutte le impostazioni preservate: tipo di aggregazione, nome dell'evento, filtri e associazioni di credito. Questo elimina la necessità di ricreare manualmente i contatori quando si passa dallo sviluppo alla produzione.
Costruisci e valida le configurazioni dei tuoi contatori prima in modalità test, poi copiale in modalità live quando sei pronto per andare in produzione. Questo garantisce che la tua configurazione di fatturazione sia testata prima di gestire l'uso reale dei clienti.
Per saperne di più: [Usage-Based Billing](/features/usage-based-billing/introduction) | [Meters](/features/usage-based-billing/meters)