Guida all'integrazione della fatturazione basata sull'uso
Scopri come configurare i contatori e inviare eventi di utilizzo per abilitare una fatturazione basata sull’uso accurata con Dodo Payments.
API Reference - Events Ingestion
Accedi alla documentazione API completa per l’ingestione degli eventi di utilizzo e prova interattivamente le richieste e le risposte di ingestione degli eventi.
API Reference - Meters Creation
Esplora la documentazione API completa per la creazione dei meter e testa interattivamente le richieste e le risposte.
I contatori definiscono come gli eventi di utilizzo vengono aggregati e misurati ai fini della fatturazione.Prima di creare un contatore, pianifica la tua strategia di tracciamento dell’uso:
Identifica quali eventi di utilizzo desideri monitorare
Determina come gli eventi devono essere aggregati (conteggio, somma, ecc.)
Definisci eventuali requisiti di filtraggio per casi d’uso specifici
Seleziona come devono essere aggregati gli eventi:
Count
Sum
Max
Last
Conta semplicemente il numero di eventi ricevuti.Caso d’uso: chiamate API, visualizzazioni di pagina, caricamenti di fileCalcolo: Numero totale di eventi
Somma i valori di una proprietà specifica nei tuoi eventi.Caso d’uso: trasferimento dati, consumo di storage, tempo di elaborazioneCalcolo: Somma di tutti i valori della proprietà
Registra il valore più alto di una determinata proprietà durante il periodo di fatturazione.Caso d’uso: utenti simultanei di picco, massimo storage utilizzato, massima larghezza di bandaCalcolo: Valore massimo della proprietà osservato
Usa il valore più recente di una proprietà specifica.Caso d’uso: livello attuale del piano, ultima impostazione di configurazioneCalcolo: Ultimo valore della proprietà registrato
Definisci l’etichetta dell’unità per la visualizzazione nei report e nella fatturazione.Esempi: “calls”, “GB”, “hours”, “tokens”
3
Configure Event Filtering (Optional)
Definisci i criteri per controllare quali eventi vengono inclusi nel meter.
Il filtraggio degli eventi ti permette di creare regole sofisticate che determinano quali eventi contribuiscono ai calcoli di utilizzo. Utile per escludere eventi di test, filtrare per tier utente o concentrarsi su azioni specifiche.
Abilita il filtraggio degli eventiAttiva Abilita il filtraggio degli eventi per attivare l’elaborazione condizionale degli eventi.Scegli la logica di filtroSeleziona come vengono valutate più condizioni:
AND Logic
OR Logic
Tutte le condizioni devono essere vere affinché un evento venga conteggiato. Usalo quando hai bisogno che gli eventi soddisfino più criteri rigorosi contemporaneamente.Esempio: Conta le chiamate API dove user_tier = "premium" AND endpoint = "/api/v2/users"
Almeno una condizione deve essere vera affinché un evento venga conteggiato. Usalo quando vuoi includere eventi che soddisfano uno qualsiasi di diversi criteri.Esempio: Conta gli eventi dove method = "POST" OR method = "PUT" OR method = "DELETE"
Impostazione delle condizioni di filtro
1
Add Condition
Clicca Aggiungi condizione per creare una nuova regola di filtro.
2
Configure Property Key
Specifica il nome della proprietà nei tuoi metadati dell’evento.
Imposta il valore di riferimento per il confronto.
5
Add Groups
Usa Aggiungi gruppo per creare gruppi di condizioni aggiuntivi per logica complessa.
Le proprietà filtrate devono essere incluse nei metadati dell’evento affinché le condizioni funzionino correttamente. Gli eventi privi delle proprietà richieste verranno esclusi dal conteggio.
4
Create Meter
Rivedi la configurazione del meter e clicca su Crea meter.
Il tuo meter è ora pronto per ricevere e aggregare gli eventi di utilizzo.
Una volta creato il tuo contatore, devi collegarlo a un prodotto per abilitare la fatturazione basata sull’uso. Questo processo collega i dati di utilizzo del tuo contatore alle regole di prezzo per la fatturazione dei clienti.Collegare i contatori ai prodotti stabilisce la connessione tra il tracciamento dell’uso e la fatturazione:
I prodotti definiscono le regole di prezzo e il comportamento di fatturazione
I contatori forniscono dati di utilizzo per i calcoli di fatturazione
Più contatori possono essere collegati a un singolo prodotto per scenari di fatturazione complessi
Trasforma i tuoi dati di utilizzo in addebiti fatturabili configurando correttamente le impostazioni del tuo prodotto:
1
Choose Usage-Based Billing Product Type
Vai alla pagina di creazione o modifica del prodotto e seleziona Basato sull’utilizzo come tipo di prodotto.
2
Select Associated Meter
Clicca su Meter associato per aprire il pannello di selezione meter dal lato.Questo pannello ti consente di configurare quali meter monitoreranno l’utilizzo per questo prodotto.
3
Add Your Meter
Nella barra di selezione del meter:
Clicca su Aggiungi contatori per visualizzare i contatori disponibili
Seleziona il contatore che hai creato dall’elenco a discesa
Il contatore selezionato apparirà nella configurazione del tuo prodotto
4
Configure Price Per Unit
Imposta il prezzo per ciascuna unità di utilizzo monitorata dal tuo meter.
Numero di unità che i clienti possono consumare gratuitamente prima che inizi il calcolo dell’utilizzo a pagamento.Come funziona:
Soglia gratuita: 100 unità
Prezzo per unità: $0.50
Utilizzo cliente: 250 unità
Calcolo: (250 - 100) × 0.50=∗∗75.00** addebitati
Le soglie gratuite sono ideali per modelli freemium, periodi di prova o per fornire ai clienti un’allocazione base inclusa nel piano.
La soglia gratuita si applica a ogni ciclo di fatturazione, offrendo ai clienti nuove allocazioni mensili o secondo il tuo programma.
6
Save Configuration
Rivedi la configurazione del meter e dei prezzi, quindi clicca Salva modifiche per finalizzare.
Il tuo prodotto è ora configurato per la fatturazione basata sull’utilizzo e addebiterà automaticamente i clienti in base al consumo misurato.
Cosa succede dopo:
Gli eventi di utilizzo inviati al tuo meter verranno tracciati e aggregati
I calcoli di fatturazione applicheranno automaticamente le tue regole di prezzo
I clienti verranno addebitati in base al consumo reale durante ogni ciclo di fatturazione
Ricorda che puoi aggiungere fino a 10 meter per prodotto, abilitando monitoraggi sofisticati dell’utilizzo su più dimensioni come chiamate API, storage, tempo di calcolo e metriche personalizzate.
Proprietà aggiuntive per il filtraggio e l’aggregazione. Includi tutti i valori riferiti nella tua impostazione “Over Property” o nelle condizioni di filtraggio.
Elementi chiave da conoscere per un’ingestione affidabile
Segui queste pratiche per mantenere il monitoraggio dell’utilizzo accurato e resiliente in produzione.
Usa event_id deterministici e idempotenti.event_id deve essere univoco tra tutti gli eventi e funge da chiave di idempotenza: un event_id riutilizzato viene trattato come duplicato e non viene conteggiato nuovamente, quindi i retry non generano doppi addebiti. Ricava l’ID dall’azione invece di usare un valore casuale, ad esempio `${customer_id}_${action}_${timestamp}`.
Raggruppa gli eventi, fino a 1.000 per richiesta. L’endpoint /events/ingest impone un limite massimo rigido di 1.000 eventi per chiamata; i batch più grandi vengono rifiutati, quindi suddividi i volumi elevati in più chiamate. Per i carichi di lavoro ad alto volume, memorizza temporaneamente gli eventi e inviali in batch invece di effettuare una richiesta per ogni evento.
Ripeti 5xx e 429, mai 4xx. Esegui il retry in caso di errori del server (5xx) e di limiti di frequenza (429), utilizzando un backoff esponenziale. Non eseguire il retry per gli errori di convalida 400/422: il payload è malformato e fallirà ogni volta; correggilo e invialo nuovamente. Accoda gli eventi che continuano a fallire dopo i retry, così non ne andrà perso nessuno.
Imposta i timestamp intenzionalmente. Ometti timestamp per gli eventi in tempo reale: verrà impostato automaticamente sull’ora di ingestione. Impostalo esplicitamente (ISO 8601) durante il backfill o quando invii eventi ritardati/in batch, affinché l’utilizzo venga assegnato al periodo di fatturazione corretto.
Invia i metadati aggregati come numeri, non come stringhe. Qualsiasi proprietà a cui fa riferimento la voce Over Property di un meter (Sum, Max, Last) deve essere di tipo numerico: { "tokens": 150 }, non { "tokens": "150" }. I valori stringa non verranno aggregati.
Monitora e analizza i dati della tua fatturazione basata sull’utilizzo con una dashboard di analisi completa. Tieni traccia dei modelli di consumo dei clienti, delle prestazioni dei meter e delle tendenze di fatturazione per ottimizzare la tua strategia di prezzo e comprendere i comportamenti di utilizzo.
Il grafico delle quantità dei meter visualizza le tendenze di utilizzo nel tempo con le seguenti funzionalità:
Visualizzazione delle serie temporali: monitora i modelli di utilizzo su giorni, settimane o mesi
Supporto per più meter: visualizza contemporaneamente i dati di meter diversi
Analisi delle tendenze: individua picchi di utilizzo, modelli e traiettorie di crescita
Il grafico si adatta automaticamente in base al volume di utilizzo e all’intervallo di tempo selezionato, offrendo una visibilità chiara sia sulle piccole fluttuazioni sia sui cambiamenti significativi nell’utilizzo.
La tabella degli eventi offre una visione chiara dei singoli eventi di utilizzo con le seguenti colonne:
Nome evento: l’azione o il trigger specifico che ha generato l’evento di utilizzo
ID evento: identificatore univoco per ogni istanza dell’evento
ID cliente: il cliente associato all’evento
Timestamp: il momento in cui si è verificato l’evento
Questa vista ti consente di monitorare i singoli eventi di utilizzo tra tutti i tuoi clienti, offrendo trasparenza nei calcoli di fatturazione e nei modelli di utilizzo.
I diversi tipi di aggregazione sono adatti a diversi scenari di fatturazione. Scegli il tipo corretto in base a come vuoi misurare e addebitare l’utilizzo.
Risolvi i problemi comuni nell’implementazione della fatturazione basata sull’utilizzo e assicurati che il monitoraggio e la fatturazione siano accurati.