Usage-Based Billing Integration guide

API Reference - Events Ingestion

Access the complete API documentation for ingesting usage events and test event ingestion requests and responses interactively.

API Reference - Meters Creation

Explore the full API documentation for creating meters and interactively test meter creation requests and responses.

Creating a Meter

Meters define how your usage events are aggregated and measured for billing purposes. Before creating a meter, plan your usage tracking strategy:

Identify what usage events you want to track
Determine how events should be aggregated (count, sum, etc.)
Define any filtering requirements for specific use cases

Step-by-Step Meter Creation

Follow this comprehensive guide to set up your usage meter:

Configure Basic Information

Set up the fundamental details for your meter.

string

erforderlich

Choose a clear, descriptive name that identifies what this meter tracks.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

Provide a detailed explanation of what this meter measures.Example: “Counts each POST /v1/orders request made by the customer”

string

erforderlich

Specify the event identifier that will trigger this meter.Examples: “token”, “api.call”, “storage.usage”, “compute.session”

The event name must match exactly what you send in your usage events. Event names are case-sensitive.

Configure Aggregation Settings

Define how the meter calculates usage from your events.

string

erforderlich

Select how events should be aggregated:

Count
Sum
Max
Last

Simply counts the number of events received.Use case: API calls, page views, file uploadsCalculation: Total number of events

string

The property name from event metadata to aggregate over.

This field is required when using Sum, Max, or Last aggregation types.

string

erforderlich

Define the unit label for display purposes in reports and billing.Examples: “calls”, “GB”, “hours”, “tokens”

Configure Event Filtering (Optional)

Set up criteria to control which events are included in the meter.

Event filtering allows you to create sophisticated rules that determine which events contribute to your usage calculations. This is useful for excluding test events, filtering by user tiers, or focusing on specific actions.

Enable Event FilteringToggle Enable Event Filtering to activate conditional event processing.Choose Filter LogicSelect how multiple conditions are evaluated:

AND Logic
OR Logic

All conditions must be true for an event to be counted. Use this when you need events to meet multiple strict criteria simultaneously.Example: Count API calls where user_tier = "premium" AND endpoint = "/api/v2/users"

At least one condition must be true for an event to be counted. Use this when you want to include events that meet any of several criteria.Example: Count events where method = "POST" OR method = "PUT" OR method = "DELETE"

Setting Up Filter Conditions

Add Condition

Click Add condition to create a new filter rule.

Configure Property Key

Specify the property name from your event metadata.

Select Comparator

Wählen Sie aus den verfügbaren Operatoren:

equals - Exakte Übereinstimmung
not_equals - Ausschlussfilter
greater_than - Numerischer Vergleich
greater_than_or_equals - Numerischer Vergleich (inklusive)
less_than - Numerischer Vergleich
less_than_or_equals - Numerischer Vergleich (inklusive)
contains - Zeichenkette enthält Teilstring
does_not_contain - Zeichenketten-Ausschlussfilter

Set Comparison Value

Set the target value for comparison.

Add Groups

Use Add Group to create additional condition groups for complex logic.

Filtered properties must be included in your event metadata for the conditions to work properly. Events missing required properties will be excluded from counting.

Create Meter

Review your meter configuration and click on Create Meter.

Your meter is now ready to receive and aggregate usage events.

Linking Meter in a Product

Once you have created your meter, you need to link it to a product to enable usage-based billing. This process connects your meter’s usage data to pricing rules for customer billing. Linking meters to products establishes the connection between usage tracking and billing:

Products define pricing rules and billing behavior
Meters provide usage data for billing calculations
Multiple meters can be linked to a single product for complex billing scenarios

Product Configuration Process

Transform your usage data into billable charges by properly configuring your product settings:

Choose Usage-Based Billing Product Type

Navigate to your product creation or editing page and select Usage-Based as the product type.

Select Associated Meter

Click on Associated Meter to open the meter selection panel from the side.This panel allows you to configure which meters will track usage for this product.

Add Your Meter

In the meter selection panel:

Click Add Meters to view available meters
Select the meter you created from the dropdown list
The selected meter will appear in your product configuration

Configure Price Per Unit

Set the pricing for each unit of usage tracked by your meter.

number

erforderlich

Define how much to charge for each unit measured by your meter.Example: Setting $0.50 per unit means:

1,000 units consumed = 1,000 × $0.50 = 500.00 charged
500 units consumed = 500 × $0.50 = 250.00 charged
100 units consumed = 100 × $0.50 = 50.00 charged

Set Free Threshold (Optional)

Configure a free usage allowance before billing begins.

number

Number of units customers can consume at no charge before paid usage calculation starts.How it works:

Free threshold: 100 units
Price per unit: $0.50
Customer usage: 250 units
Calculation: (250 - 100) × $0.50 = **$ 75.00** charged

Free thresholds are ideal for freemium models, trial periods, or providing customers with a base allowance included in their plan.

The free threshold applies to each billing cycle, giving customers fresh allowances monthly or according to your billing schedule.

Save Configuration

Review your meter and pricing configuration, then click Save Changes to finalize the setup.

Your product is now configured for usage-based billing and will automatically charge customers based on their measured consumption.

What happens next:

Usage events sent to your meter will be tracked and aggregated
Billing calculations will apply your pricing rules automatically
Customers will be charged based on actual consumption during each billing cycle

Remember that you can add up to 10 meters per product, enabling sophisticated usage tracking across multiple dimensions like API calls, storage, compute time, and custom metrics.

Sending Usage Events

Once your meter is configured, you can start sending usage events from your application to track customer usage.

Event Structure

Each usage event must include these required fields:

string

erforderlich

Unique identifier for this specific event. Must be unique across all events.

string

erforderlich

The Dodo Payments customer ID this usage should be attributed to.

string

erforderlich

The event name that matches your meter configuration. Event names trigger the appropriate meter.

string

ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.

object

Additional properties for filtering and aggregation. Include any values referenced in your meter’s “Over Property” or filtering conditions.

Usage Events API Examples

Send usage events to your configured meters using the Events API:

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
        }
      }
    ]
  })
});

import requests
from datetime import datetime

response = requests.post(
    'https://test.dodopayments.com/events/ingest',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'events': [
            {
                'event_id': 'api_call_1234',
                'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
                'event_name': 'api.call',
                'timestamp': datetime.now().isoformat(),
                'metadata': {
                    'endpoint': '/v1/orders',
                    'method': 'POST',
                    'response_size': 1024
                }
            }
        ]
    }
)

curl -X POST 'https://test.dodopayments.com/events/ingest' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "event_id": "api_call_1234",
        "customer_id": "cus_atXa1lklCRRzMicTqfiw2",
        "event_name": "api.call", 
        "timestamp": "2024-01-15T10:30:00Z",
        "metadata": {
          "endpoint": "/v1/orders",
          "method": "POST",
          "response_size": 1024
        }
      }
    ]
  }'

Wichtige Punkte für eine zuverlässige Ingestion

Befolgen Sie diese Vorgehensweisen, damit die Nutzungsdaten in der Produktion korrekt und resilient erfasst werden.

Verwenden Sie deterministische, idempotente event_ids. Der event_id muss über alle Events hinweg eindeutig sein und dient als Idempotency Key — ein wiederverwendeter event_id wird als Duplikat behandelt und nicht erneut gezählt, sodass Retries niemals doppelt abrechnen. Leiten Sie die ID aus der Aktion statt aus einem zufälligen Wert ab, z. B. `${customer_id}_${action}_${timestamp}`.

Bündeln Sie Events, bis zu 1.000 pro Request. Der /events/ingest-Endpunkt erzwingt ein absolutes Maximum von 1.000 Events pro Aufruf; größere Batches werden abgelehnt. Teilen Sie hohe Volumina daher auf mehrere Aufrufe auf. Bei Workloads mit hohem Volumen sollten Sie Events puffern und in Batches senden, statt für jedes Event einen einzelnen Request zu senden.

Führen Sie Retries für 5xx und 429 durch, niemals für 4xx. Führen Sie bei Serverfehlern (5xx) und Rate Limits (429) Retries mit exponentiellem Backoff durch. Führen Sie bei Validierungsfehlern von 400/422 keine Retries durch — der Payload ist fehlerhaft und wird jedes Mal fehlschlagen; korrigieren Sie ihn und senden Sie ihn erneut. Stellen Sie Events, die auch nach den Retries fehlschlagen, in eine Queue, damit keine verloren gehen.

Setzen Sie Timestamps bewusst. Lassen Sie timestamp bei Echtzeit-Events weg; dann wird standardmäßig die Ingestion-Zeit verwendet. Setzen Sie den Wert beim Backfilling oder beim Senden verzögerter bzw. gebündelter Events explizit (ISO 8601), damit die Nutzung dem korrekten Abrechnungszeitraum zugeordnet wird.

Senden Sie aggregierte Metadaten als Zahlen, nicht als Strings. Jede Property, auf die sich das Over Property eines Meters (Sum, Max, Last) bezieht, muss vom numerischen Typ sein — { "tokens": 150 }, nicht { "tokens": "150" }. String-Werte werden nicht aggregiert.

Analytics für nutzungsbasierte Abrechnung

Überwachen und analysieren Sie Ihre Daten zur nutzungsbasierten Abrechnung mit einem umfassenden Analytics-Dashboard. Verfolgen Sie Verbrauchsmuster von Kunden, die Performance von Metern und Abrechnungstrends, um Ihre Preisstrategie zu optimieren und Nutzungsverhalten zu verstehen.

Übersichtsanalyse

Der Tab „Overview“ bietet eine umfassende Ansicht Ihrer Performance bei der nutzungsbasierten Abrechnung:

Aktivitätsmetriken

Verfolgen Sie wichtige Nutzungsstatistiken über verschiedene Zeiträume hinweg:

metric

Zeigt die Nutzungsaktivität für den aktuellen Abrechnungszeitraum an und hilft Ihnen, monatliche Verbrauchsmuster zu verstehen.

metric

Zeigt kumulierte Nutzungsstatistiken seit Beginn der Erfassung an und liefert langfristige Einblicke in das Wachstum.

Verwenden Sie die Auswahl für den Zeitraum, um die Nutzung über verschiedene Monate hinweg zu vergleichen und saisonale Trends oder Wachstumsmuster zu erkennen.

Diagramm der Meter-Mengen

Das Diagramm der Meter-Mengen visualisiert Nutzungstrends im Zeitverlauf mit den folgenden Funktionen:

Zeitreihenvisualisierung: Verfolgen Sie Nutzungsmuster über Tage, Wochen oder Monate hinweg
Unterstützung mehrerer Meter: Sehen Sie Daten aus verschiedenen Metern gleichzeitig an
Trendanalyse: Erkennen Sie Nutzungsspitzen, Muster und Wachstumsverläufe

Das Diagramm wird automatisch anhand Ihres Nutzungsvolumens und des ausgewählten Zeitraums skaliert und bietet eine klare Übersicht sowohl über kleine Schwankungen als auch über große Nutzungsänderungen.

Event-Analytics

Event-Tabelle mit Event-Namen, IDs und Paginierungssteuerelementen für eine detaillierte Event-Analyse

Der Tab „Events“ bietet detaillierte Einblicke in einzelne Nutzungs-Events:

Anzeige von Event-Informationen

Die Event-Tabelle bietet mit den folgenden Spalten eine klare Übersicht über einzelne Nutzungs-Events:

Event Name: Die spezifische Aktion oder der Trigger, durch den das Nutzungs-Event erzeugt wurde
Event ID: Eindeutige Kennung für jede Event-Instanz
Customer ID: Der mit dem Event verknüpfte Kunde
Timestamp: Zeitpunkt, zu dem das Event aufgetreten ist

Diese Ansicht ermöglicht es Ihnen, einzelne Nutzungs-Events über Ihren gesamten Kundenstamm hinweg zu verfolgen und zu überwachen. Dadurch erhalten Sie Transparenz über Abrechnungsberechnungen und Nutzungsmuster.

Kunden-Analytics

Der Tab „Customers“ bietet eine detaillierte Tabellenansicht der Nutzungsdaten von Kunden mit den folgenden Informationen:

Verfügbare Datenspalten

string

E-Mail-Adresse des Kunden zur Identifikation.

string

Eindeutige Kennung für das Abonnement des Kunden.

number

Anzahl der kostenlosen Einheiten, die im Plan des Kunden enthalten sind, bevor Gebühren anfallen.

currency

Kosten pro Einheit für die Nutzung oberhalb des kostenlosen Schwellenwerts.

timestamp

Timestamp des letzten Nutzungs-Events des Kunden.

currency

Gesamtbetrag, der dem Kunden für die nutzungsbasierte Abrechnung berechnet wurde.

number

Gesamtzahl der Einheiten, die der Kunde verbraucht hat.

number

Anzahl der Einheiten, die den kostenlosen Schwellenwert überschreiten und berechnet werden.

Tabellenfunktionen

Spaltenfilterung: Verwenden Sie die Funktion „Edit Columns“, um bestimmte Datenspalten ein- oder auszublenden
Echtzeitaktualisierungen: Die Nutzungsdaten spiegeln die aktuellsten Verbrauchsmetriken wider

Aggregationsbeispiele

Hier finden Sie praktische Beispiele für die Funktionsweise verschiedener Aggregationstypen:

Aggregationstypen verstehen

Verschiedene Aggregationstypen eignen sich für unterschiedliche Abrechnungsszenarien. Wählen Sie den passenden Typ basierend darauf, wie Sie die Nutzung messen und abrechnen möchten.

Beispiele für die praktische Umsetzung

Diese Beispiele veranschaulichen reale Anwendungsfälle der einzelnen Aggregationstypen anhand von Beispiel-Events und erwarteten Ergebnissen.

Count Aggregation - API Calls

Szenario: Gesamtzahl der API-Requests erfassenMeter-Konfiguration:

Event Name: api.call
Aggregation Type: Count
Measurement Unit: calls

Beispiel-Events:

{
  "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"}
  ]
}

Ergebnis: 3 Aufrufe werden dem Kunden berechnet

Sum Aggregation - Data Transfer

Szenario: Abrechnung basierend auf der Gesamtzahl übertragener BytesMeter-Konfiguration:

Event Name: data.transfer
Aggregation Type: Sum
Over Property: bytes
Measurement Unit: GB

Beispiel-Events:

{
  "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}
    }
  ]
}

Ergebnis: Dem Kunden werden insgesamt 1,5 GB Übertragung berechnet

Max Aggregation - Peak Concurrent Users

Szenario: Abrechnung basierend auf der höchsten Anzahl gleichzeitig aktiver BenutzerMeter-Konfiguration:

Event Name: concurrent.users
Aggregation Type: Max
Over Property: count
Measurement Unit: users

Beispiel-Events:

{
  "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}
    }
  ]
}

Ergebnis: Dem Kunden werden 23 gleichzeitig aktive Benutzer als Spitzenwert berechnet

Beispiele für Event-Filterung

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

Nur API-Aufrufe an bestimmte Endpunkte zählen:Filterkonfiguration:

Property: endpoint
Comparator: equals
Value: /v1/orders

Beispiel-Event:

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

Ergebnis: Events, die den Filterkriterien entsprechen, werden gezählt. Events mit anderen Endpunkten werden ignoriert.

Nur große Datei-Uploads zählen:Filterkonfiguration:

Property: file_size
Comparator: greater_than
Value: 1048576 (1 MB in Bytes)

Beispiel-Event:

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

Ergebnis: Dateien größer als 1 MB werden gezählt. Kleinere Dateien werden ignoriert.

Premium-API-Aufrufe während der Geschäftszeiten zählen:Filterkonfiguration (mit AND-Logik):

Property: plan_type, Comparator: equals, Value: premium
Property: hour, Comparator: greater_than_or_equals, Value: 9
Property: hour, Comparator: less_than, Value: 17

Beispiel-Event:

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

Ergebnis: Premium-API-Aufrufe während der Geschäftszeiten (9–17 Uhr) werden gezählt.

Fehlerbehebung

Beheben Sie häufige Probleme bei der Implementierung der nutzungsbasierten Abrechnung und stellen Sie eine korrekte Erfassung und Abrechnung sicher.

Häufige Probleme

Die meisten Probleme bei der nutzungsbasierten Abrechnung fallen in diese Kategorien:

Probleme bei der Zustellung und Verarbeitung von Events
Probleme bei der Meter-Konfiguration
Fehler bei Datentypen und Formatierung
Probleme mit Customer ID und Authentifizierung

Schritte zur Fehlerbehebung

Bei der Fehlerbehebung für die nutzungsbasierte Abrechnung:

Überprüfen Sie die Zustellung der Events im Tab „Events“ der Analytics
Prüfen Sie, ob die Meter-Konfiguration der Struktur Ihrer Events entspricht
Validieren Sie Customer IDs und API-Authentifizierung
Überprüfen Sie Filterbedingungen und Aggregationseinstellungen

Lösungen und Korrekturen

Events not showing in meter

Häufige Ursachen:

Der Event Name stimmt nicht exakt mit der Meter-Konfiguration überein
Event-Filterbedingungen schließen Ihre Events aus
Die Customer ID ist in Ihrem Dodo Payments-Konto nicht vorhanden
Der Timestamp des Events liegt außerhalb des aktuellen Abrechnungszeitraums

Lösungen:

Überprüfen Sie Schreibweise und Groß-/Kleinschreibung des Event Name
Überprüfen und testen Sie Ihre Filterbedingungen
Bestätigen Sie, dass die Customer ID gültig und aktiv ist
Prüfen Sie, ob die Timestamps der Events aktuell und korrekt formatiert sind

Aggregation not working as expected

Häufige Ursachen:

Der Name der Over Property stimmt nicht mit den Metadaten-Keys des Events überein
Die Metadatenwerte haben den falschen Datentyp (String statt Zahl)
Erforderliche Metadaten-Properties fehlen

Lösungen:

Stellen Sie sicher, dass die Metadaten-Keys exakt mit Ihrer Over-Property-Einstellung übereinstimmen
Konvertieren Sie numerische Strings in Ihren Events in tatsächliche Zahlen
Fügen Sie alle erforderlichen Properties in jedes Event ein

Filtering not working

Häufige Ursachen:

Die Namen der Filter-Properties stimmen nicht mit den Event-Metadaten überein
Falscher Comparator für den Datentyp (String statt Zahl)
Groß-/Kleinschreibung bei String-Vergleichen

Lösungen:

Überprüfen Sie nochmals, ob die Property-Namen exakt übereinstimmen
Verwenden Sie für Ihre Datentypen geeignete Comparatoren
Berücksichtigen Sie bei der Filterung von Strings die Groß-/Kleinschreibung

Zugehörige API-Referenz

Create Meter

API-Referenz zum Erstellen und Konfigurieren von Nutzungsmetern für die Erfassung des Kundenverbrauchs

Ingest Usage Events

API-Referenz zum Senden von Nutzungs-Events an Ihre konfigurierten Meter für Abrechnungsberechnungen

Integration Guides

Billing Deconstructions

Cookbooks

API Reference - Events Ingestion

API Reference - Meters Creation

Creating a Meter

Step-by-Step Meter Creation

Linking Meter in a Product

Product Configuration Process

Sending Usage Events

Event Structure

Usage Events API Examples

Wichtige Punkte für eine zuverlässige Ingestion

Analytics für nutzungsbasierte Abrechnung

Übersichtsanalyse

Aktivitätsmetriken

Diagramm der Meter-Mengen

Event-Analytics

Anzeige von Event-Informationen

Kunden-Analytics

Verfügbare Datenspalten

Tabellenfunktionen

Aggregationsbeispiele

Aggregationstypen verstehen

Beispiele für die praktische Umsetzung

Beispiele für Event-Filterung

Fehlerbehebung

Häufige Probleme

Schritte zur Fehlerbehebung

Lösungen und Korrekturen

Zugehörige API-Referenz

Create Meter

Ingest Usage Events

API Reference - Events Ingestion

API Reference - Meters Creation

​Creating a Meter

​Step-by-Step Meter Creation

​Linking Meter in a Product

​Product Configuration Process

​Sending Usage Events

​Event Structure

​Usage Events API Examples

​Wichtige Punkte für eine zuverlässige Ingestion

​Analytics für nutzungsbasierte Abrechnung

​Übersichtsanalyse

​Aktivitätsmetriken

​Diagramm der Meter-Mengen

​Event-Analytics

​Anzeige von Event-Informationen

​Kunden-Analytics

​Verfügbare Datenspalten

​Tabellenfunktionen

​Aggregationsbeispiele

​Aggregationstypen verstehen

​Beispiele für die praktische Umsetzung

​Beispiele für Event-Filterung

​Fehlerbehebung

​Häufige Probleme

​Schritte zur Fehlerbehebung

​Lösungen und Korrekturen

​Zugehörige API-Referenz

Create Meter

Ingest Usage Events

Creating a Meter

Step-by-Step Meter Creation

Linking Meter in a Product

Product Configuration Process

Sending Usage Events

Event Structure

Usage Events API Examples

Wichtige Punkte für eine zuverlässige Ingestion

Analytics für nutzungsbasierte Abrechnung

Übersichtsanalyse

Aktivitätsmetriken

Diagramm der Meter-Mengen

Event-Analytics

Anzeige von Event-Informationen

Kunden-Analytics

Verfügbare Datenspalten

Tabellenfunktionen

Aggregationsbeispiele

Aggregationstypen verstehen

Beispiele für die praktische Umsetzung

Beispiele für Event-Filterung

Fehlerbehebung

Häufige Probleme

Schritte zur Fehlerbehebung

Lösungen und Korrekturen

Zugehörige API-Referenz