Guida all'integrazione della fatturazione basata sull'uso

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.

Creazione di un contatore

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

Procedura passo-passo per la creazione di un contatore

Segui questa guida completa per configurare il tuo contatore di utilizzo:

Configure Basic Information

Configura i dettagli fondamentali del tuo meter.

Meter Name

string

obbligatorio

Scegli un nome chiaro e descrittivo che identifichi cosa monitora questo meter.Esempi: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

Description

string

Fornisci una spiegazione dettagliata di cosa misura questo meter.Esempio: “Counts each POST /v1/orders request made by the customer”

Event Name

string

obbligatorio

Specifica l’identificatore evento che attiverà questo meter.Esempi: “token”, “api.call”, “storage.usage”, “compute.session”

Il nome dell’evento deve corrispondere esattamente a quello che invii nei tuoi eventi di utilizzo. I nomi sono sensibili al maiuscolo/minuscolo.

Configure Aggregation Settings

Definisci come il meter calcola l’utilizzo dai tuoi eventi.

Aggregation Type

string

obbligatorio

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

Over Property

string

Nome della proprietà nei metadati dell’evento su cui effettuare l’aggregazione.

Questo campo è obbligatorio quando si utilizzano i tipi di aggregazione Somma, Massimo o Ultimo.

Measurement Unit

string

obbligatorio

Definisci l’etichetta dell’unità per la visualizzazione nei report e nella fatturazione.Esempi: “calls”, “GB”, “hours”, “tokens”

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

Add Condition

Clicca Aggiungi condizione per creare una nuova regola di filtro.

Configure Property Key

Specifica il nome della proprietà nei tuoi metadati dell’evento.

Select Comparator

Scegli tra gli operatori disponibili:

equals - Corrispondenza esatta
not equals - Filtro di esclusione
greater than - Confronto numerico
greater than or equals - Confronto numerico (inclusivo)
less than - Confronto numerico
less than or equals - Confronto numerico (inclusivo)
contains - La stringa contiene la sottostringa
does not contain - Filtro di esclusione stringa

Set Comparison Value

Imposta il valore di riferimento per il confronto.

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.

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.

Collegare il contatore a un prodotto

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

Processo di configurazione del prodotto

Trasforma i tuoi dati di utilizzo in addebiti fatturabili configurando correttamente le impostazioni del tuo prodotto:

Choose Usage-Based Billing Product Type

Vai alla pagina di creazione o modifica del prodotto e seleziona Basato sull’utilizzo come tipo di prodotto.

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.

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

Configure Price Per Unit

Imposta il prezzo per ciascuna unità di utilizzo monitorata dal tuo meter.

Price Per Unit

number

obbligatorio

Definisci quanto addebitare per ogni unità misurata dal tuo meter.Esempio: impostando $0.50 per unità significa:

1,000 unità consumate = 1,000 × $0.50 = 500.00 addebitati
500 unità consumate = 500 × $0.50 = 250.00 addebitati
100 unità consumate = 100 × $0.50 = 50.00 addebitati

Set Free Threshold (Optional)

Configura una soglia di utilizzo gratuita prima dell’inizio della fatturazione.

Free Threshold

number

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.

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.

Invio di eventi di utilizzo

Una volta configurato il tuo contatore, puoi iniziare a inviare eventi di utilizzo dalla tua applicazione per monitorare l’uso dei clienti.

Struttura dell’evento

Ogni evento di utilizzo deve includere questi campi obbligatori:

event_id

string

obbligatorio

Identificatore univoco per questo evento specifico. Deve essere unico tra tutti gli eventi.

customer_id

string

obbligatorio

L’ID cliente Dodo Payments a cui attribuire questo utilizzo.

event_name

string

obbligatorio

Il nome dell’evento che corrisponde alla configurazione del tuo meter. I nomi degli eventi attivano il meter appropriato.

timestamp

string

Timestamp ISO 8601 in cui si è verificato l’evento. Se non fornito, predefinito all’ora corrente.

metadata

object

Proprietà aggiuntive per il filtraggio e l’aggregazione. Includi tutti i valori riferiti nella tua impostazione “Over Property” o nelle condizioni di filtraggio.

Esempi di API per eventi di utilizzo

Invia eventi di utilizzo ai tuoi contatori configurati utilizzando l’API degli eventi:

const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "api_call_1234",
        customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

Analisi della fatturazione basata sull’uso

Monitora e analizza i tuoi dati di fatturazione basata sull’uso con un dashboard analitico completo. Monitora i modelli di consumo dei clienti, le prestazioni dei contatori e le tendenze di fatturazione per ottimizzare la tua strategia di prezzo e comprendere i comportamenti di utilizzo.

Analisi panoramica

La scheda Panoramica fornisce una visione completa delle prestazioni della tua fatturazione basata sull’uso:

Metriche di attività

Monitora le statistiche chiave di utilizzo su diversi periodi di tempo:

Current Month

metric

Mostra l’attività di utilizzo nel periodo di fatturazione corrente, aiutandoti a comprendere i modelli mensili di consumo.

All Time

metric

Mostra statistiche cumulative dall’inizio del tracciamento, offrendo approfondimenti sulla crescita a lungo termine.

Usa il selettore del periodo per confrontare l’utilizzo in mesi diversi e identificare tendenze stagionali o schemi di crescita.

Grafico delle quantità dei contatori

Grafico delle quantità del contatore che mostra le tendenze d'uso nel tempo con visualizzazione a gradiente viola

Il grafico delle quantità dei contatori visualizza le tendenze di utilizzo nel tempo con le seguenti caratteristiche:

Visualizzazione temporale: Monitora i modelli di utilizzo su giorni, settimane o mesi
Supporto per più contatori: Visualizza i dati di diversi contatori simultaneamente
Analisi delle tendenze: Identifica picchi di utilizzo, modelli e traiettorie di crescita

Il grafico si adatta automaticamente in base al volume di utilizzo e al range temporale selezionato, offrendo visibilità chiara sia sulle piccole fluttuazioni che sui maggiori cambiamenti.

Analisi degli eventi

Tabella degli eventi che mostra i nomi degli eventi, gli ID e i controlli di paginazione per un'analisi dettagliata degli eventi

La scheda Eventi fornisce visibilità granulare sugli eventi di utilizzo individuali:

Visualizzazione delle informazioni sugli eventi

La tabella degli eventi fornisce una chiara visione degli eventi di utilizzo individuali con le seguenti colonne:

Nome dell’evento: L’azione o il trigger specifico che ha generato l’evento di utilizzo
ID evento: Identificatore unico per ogni istanza di evento
ID cliente: Il cliente associato all’evento
Timestamp: Quando si è verificato l’evento

Questa visualizzazione ti consente di monitorare eventi di utilizzo individuali su tutta la base clienti, fornendo trasparenza nei calcoli di fatturazione e nei modelli di utilizzo.

Analisi dei clienti

La scheda Clienti fornisce una vista tabellare dettagliata dei dati di utilizzo dei clienti con le seguenti informazioni:

Colonne di dati disponibili

Customer Email

string

Indirizzo email del cliente per identificazione.

Subscription ID

string

Identificatore univoco per l’abbonamento del cliente.

Free Threshold

number

Numero di unità gratuite incluse nel piano del cliente prima che si applichino addebiti.

Price Per Unit

currency

Il costo per unità dell’utilizzo oltre la soglia gratuita.

Last Event

timestamp

Timestamp dell’evento di utilizzo più recente del cliente.

Total Price

currency

Importo totale addebitato al cliente per la fatturazione basata sull’utilizzo.

Consumed Units

number

Numero totale di unità consumate dal cliente.

Chargeable Units

number

Numero di unità che superano la soglia gratuita e vengono addebitate.

Caratteristiche della tabella

Filtraggio delle colonne: Usa la funzione “Modifica colonne” per mostrare/nascondere colonne di dati specifiche
Aggiornamenti in tempo reale: I dati di utilizzo riflettono le metriche di consumo più attuali

Esempi di aggregazione

Ecco esempi pratici di come funzionano i diversi tipi di aggregazione:

Comprendere i tipi di aggregazione

Diversi tipi di aggregazione servono a diversi scenari di fatturazione. Scegli il tipo giusto in base a come desideri misurare e addebitare per l’uso.

Esempi di implementazione pratica

Questi esempi dimostrano applicazioni reali di ciascun tipo di aggregazione con eventi di esempio e risultati attesi.

Count Aggregation - API Calls

Scenario: Monitora il numero totale di richieste APIConfigurazione del meter:

Nome evento: api.call
Tipo di aggregazione: Count
Unità di misura: calls

Eventi di esempio:

{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}

Risultato: 3 chiamate fatturate al cliente

Sum Aggregation - Data Transfer

Scenario: Fattura in base al totale di byte trasferitiConfigurazione del meter:

Nome evento: data.transfer
Tipo di aggregazione: Sum
Over Property: bytes
Unità di misura: GB

Eventi di esempio:

{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}

Risultato: 1.5 GB di trasferimento totale fatturati al cliente

Max Aggregation - Peak Concurrent Users

Scenario: Fattura basata sul numero massimo di utenti simultaneiConfigurazione del meter:

Nome evento: concurrent.users
Tipo di aggregazione: Max
Over Property: count
Unità di misura: users

Eventi di esempio:

{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}

Risultato: 23 utenti concorrenti di picco fatturati al cliente

Esempi di filtraggio degli eventi

Filter by API Endpoint
Filter by Value Range
Complex Multi-Condition Filters

Conta solo le chiamate API verso endpoint specifici:Configurazione del filtro:

Proprietà: endpoint
Comparatore: equals
Valore: /v1/orders

Evento di esempio:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}

Risultato: Gli eventi che soddisfano i criteri del filtro verrebbero conteggiati. Gli eventi con endpoint diversi verrebbero ignorati.

Conta solo i caricamenti di file di grandi dimensioni:Configurazione del filtro:

Proprietà: file_size
Comparatore: greater_than
Valore: 1048576 (1MB in byte)

Evento di esempio:

{
  "event_id": "upload_1",
  "customer_id": "cus_123", 
  "event_name": "file.upload",
  "metadata": {
    "file_size": 5242880,
    "file_type": "image"
  }
}

Risultato: I file più grandi di 1MB verrebbero conteggiati. I file più piccoli verrebbero ignorati.

Conta le chiamate API premium durante l’orario lavorativo:Configurazione del filtro (usando logica AND):

Proprietà: plan_type, Comparatore: equals, Valore: premium
Proprietà: hour, Comparatore: greater_than_or_equal, Valore: 9
Proprietà: hour, Comparatore: less_than, Valore: 17

Evento di esempio:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "plan_type": "premium",
    "hour": 14,
    "endpoint": "/v1/analytics"
  }
}

Risultato: Le chiamate API premium durante l’orario lavorativo (9 AM - 5 PM) verrebbero conteggiate.

Risoluzione dei problemi

Risolvi i problemi comuni con l’implementazione della fatturazione basata sull’uso e assicurati un tracciamento e una fatturazione accurati.

Problemi comuni

La maggior parte dei problemi di fatturazione basata sull’uso rientra in queste categorie:

Problemi di consegna e elaborazione degli eventi
Problemi di configurazione del contatore
Errori di tipo di dati e formattazione
Problemi di ID cliente e autenticazione

Passi per il debug

Quando risolvi i problemi della fatturazione basata sull’uso:

Verifica la consegna degli eventi nella scheda analitica degli eventi
Controlla che la configurazione del contatore corrisponda alla struttura del tuo evento
Valida gli ID cliente e l’autenticazione API
Rivedi le condizioni di filtraggio e le impostazioni di aggregazione

Soluzioni e correzioni

Events not showing in meter

Cause comuni:

Il nome dell’evento non corrisponde esattamente alla configurazione del meter
Le condizioni di filtraggio escludono i tuoi eventi
L’ID cliente non esiste nel tuo account Dodo Payments
Il timestamp dell’evento è fuori dal periodo di fatturazione corrente

Soluzioni:

Verifica ortografia e maiuscole del nome dell’evento
Rivedi e testa le condizioni di filtraggio
Conferma che l’ID cliente sia valido e attivo
Controlla che i timestamp degli eventi siano recenti e formattati correttamente

Aggregation not working as expected

Cause comuni:

Il nome di Over Property non corrisponde alle chiavi dei metadati dell’evento
I valori dei metadati sono del tipo di dato sbagliato (stringa vs numero)
Mancano proprietà dei metadati richieste

Soluzioni:

Assicurati che le chiavi dei metadati corrispondano esattamente alla tua impostazione Over Property
Converti le stringhe numeriche in numeri effettivi nei tuoi eventi
Includi tutte le proprietà richieste in ogni evento

Filtering not working

Cause comuni:

I nomi delle proprietà del filtro non corrispondono ai metadati dell’evento
Comparatore sbagliato per il tipo di dato (stringa vs numero)
Sensibilità al maiuscolo/minuscolo nei confronti delle stringhe

Soluzioni:

Ricontrolla che i nomi delle proprietà corrispondano esattamente
Usa comparatori appropriati per i tuoi tipi di dato
Considera la sensibilità al maiuscolo/minuscolo quando filtri le stringhe

Riferimenti API Correlati

Create Meter

Riferimento API per la creazione e configurazione di contatori d’uso per monitorare il consumo dei clienti

Ingest Usage Events

Riferimento API per inviare eventi di utilizzo ai tuoi contatori configurati per i calcoli di fatturazione

Integration Guides

Billing Deconstructions

Cookbooks

Guida all'integrazione della fatturazione basata sull'uso

API Reference - Events Ingestion

API Reference - Meters Creation

Creazione di un contatore

Procedura passo-passo per la creazione di un contatore

Collegare il contatore a un prodotto

Processo di configurazione del prodotto

Invio di eventi di utilizzo

Struttura dell’evento

Esempi di API per eventi di utilizzo

Analisi della fatturazione basata sull’uso

Analisi panoramica

Metriche di attività

Grafico delle quantità dei contatori

Analisi degli eventi

Visualizzazione delle informazioni sugli eventi

Analisi dei clienti

Colonne di dati disponibili

Caratteristiche della tabella

Esempi di aggregazione

Comprendere i tipi di aggregazione

Esempi di implementazione pratica

Esempi di filtraggio degli eventi

Risoluzione dei problemi

Problemi comuni

Passi per il debug

Soluzioni e correzioni

Riferimenti API Correlati

Create Meter

Ingest Usage Events

Integration Guides

Billing Deconstructions

Cookbooks

Documentation Index

API Reference - Events Ingestion

API Reference - Meters Creation

​Creazione di un contatore

​Procedura passo-passo per la creazione di un contatore

​Collegare il contatore a un prodotto

​Processo di configurazione del prodotto

​Invio di eventi di utilizzo

​Struttura dell’evento

​Esempi di API per eventi di utilizzo

​Analisi della fatturazione basata sull’uso

​Analisi panoramica

​Metriche di attività

​Grafico delle quantità dei contatori

​Analisi degli eventi

​Visualizzazione delle informazioni sugli eventi

​Analisi dei clienti

​Colonne di dati disponibili

​Caratteristiche della tabella

​Esempi di aggregazione

​Comprendere i tipi di aggregazione

​Esempi di implementazione pratica

​Esempi di filtraggio degli eventi

​Risoluzione dei problemi

​Problemi comuni

​Passi per il debug

​Soluzioni e correzioni

​Riferimenti API Correlati

Create Meter

Ingest Usage Events

Creazione di un contatore

Procedura passo-passo per la creazione di un contatore

Collegare il contatore a un prodotto

Processo di configurazione del prodotto

Invio di eventi di utilizzo

Struttura dell’evento

Esempi di API per eventi di utilizzo

Analisi della fatturazione basata sull’uso

Analisi panoramica

Metriche di attività

Grafico delle quantità dei contatori

Analisi degli eventi

Visualizzazione delle informazioni sugli eventi

Analisi dei clienti

Colonne di dati disponibili

Caratteristiche della tabella

Esempi di aggregazione

Comprendere i tipi di aggregazione

Esempi di implementazione pratica

Esempi di filtraggio degli eventi

Risoluzione dei problemi

Problemi comuni

Passi per il debug

Soluzioni e correzioni

Riferimenti API Correlati