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

requis

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

requis

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

requis

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

requis

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

Choisissez parmi les opérateurs disponibles :

equals - Correspondance exacte
not_equals - Filtre d’exclusion
greater_than - Comparaison numérique
greater_than_or_equals - Comparaison numérique (inclusive)
less_than - Comparaison numérique
less_than_or_equals - Comparaison numérique (inclusive)
contains - La chaîne contient une sous-chaîne
does_not_contain - Filtre d’exclusion de chaîne

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

requis

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

requis

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

string

requis

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

string

requis

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
        }
      }
    ]
  }'

Éléments clés à connaître pour une ingestion fiable

Suivez ces pratiques pour garantir un suivi de l’utilisation précis et résilient en production.

Utilisez des event_id déterministes et idempotents. L’event_id doit être unique pour l’ensemble des événements et sert de clé d’idempotence : un event_id réutilisé est considéré comme un doublon et n’est pas comptabilisé à nouveau, de sorte que les nouvelles tentatives ne génèrent jamais de double facturation. Déduisez l’ID de l’action plutôt que d’utiliser une valeur aléatoire, par exemple `${customer_id}_${action}_${timestamp}`.

Regroupez les événements, jusqu’à 1 000 par requête. Le point de terminaison /events/ingest impose une limite stricte de 1 000 événements par appel ; les lots plus volumineux sont rejetés. Répartissez donc les volumes importants sur plusieurs appels. Pour les charges de travail à fort volume, mettez les événements en mémoire tampon et envoyez-les par lots plutôt que d’envoyer une requête par événement.

Réessayez avec 5xx et 429, mais jamais avec 4xx. Effectuez une nouvelle tentative en cas d’erreurs serveur (5xx) et de limites de débit (429), avec un backoff exponentiel. N’effectuez pas de nouvelle tentative pour les erreurs de validation 400/422 : la charge utile est malformée et échouera à chaque fois ; corrigez-la, puis renvoyez-la. Mettez en file d’attente les événements qui échouent toujours après les nouvelles tentatives afin qu’aucun ne soit perdu.

Définissez les timestamps intentionnellement. Omettez timestamp pour les événements en temps réel : il prend par défaut l’heure d’ingestion. Définissez-le explicitement (ISO 8601) lors du rattrapage ou de l’envoi d’événements différés ou regroupés, afin que l’utilisation soit affectée à la bonne période de facturation.

Envoyez les métadonnées agrégées sous forme de nombres, et non de chaînes. Toute propriété référencée par le Over Property d’un meter (Sum, Max, Last) doit être de type numérique — { "tokens": 150 }, et non { "tokens": "150" }. Les valeurs de type chaîne ne seront pas agrégées.

Analyses de la facturation basée sur l’utilisation

Surveillez et analysez vos données de facturation basée sur l’utilisation grâce à un tableau de bord analytique complet. Suivez les habitudes de consommation des clients, les performances des meters et les tendances de facturation afin d’optimiser votre stratégie tarifaire et de comprendre les comportements d’utilisation.

Analyses générales

L’onglet Overview fournit une vue complète des performances de votre facturation basée sur l’utilisation :

Métriques d’activité

Suivez les principales statistiques d’utilisation sur différentes périodes :

metric

Affiche l’activité d’utilisation pour la période de facturation actuelle, afin de vous aider à comprendre les habitudes de consommation mensuelles.

metric

Affiche les statistiques d’utilisation cumulées depuis le début du suivi, fournissant des informations sur la croissance à long terme.

Utilisez le sélecteur de période pour comparer l’utilisation entre différents mois et identifier les tendances saisonnières ou les schémas de croissance.

Graphique des quantités des meters

Le graphique des quantités des meters visualise les tendances d’utilisation au fil du temps et offre les fonctionnalités suivantes :

Visualisation chronologique : suivez les habitudes d’utilisation sur plusieurs jours, semaines ou mois
Prise en charge de plusieurs meters : consultez simultanément les données de différents meters
Analyse des tendances : identifiez les pics d’utilisation, les schémas et les trajectoires de croissance

Le graphique s’adapte automatiquement en fonction de votre volume d’utilisation et de la période sélectionnée, offrant une visibilité claire sur les petites fluctuations comme sur les changements importants d’utilisation.

Analyses des événements

Tableau des événements affichant les noms et ID des événements ainsi que les contrôles de pagination pour une analyse détaillée des événements

L’onglet Events offre une visibilité détaillée sur les événements d’utilisation individuels :

Affichage des informations sur les événements

Le tableau des événements fournit une vue claire des événements d’utilisation individuels avec les colonnes suivantes :

Nom de l’événement : l’action ou le déclencheur spécifique ayant généré l’événement d’utilisation
ID de l’événement : identifiant unique de chaque instance d’événement
ID du client : le client associé à l’événement
Timestamp : moment où l’événement s’est produit

Cette vue vous permet de suivre et de surveiller les événements d’utilisation individuels dans l’ensemble de votre base de clients, offrant une transparence sur les calculs de facturation et les habitudes d’utilisation.

Analyses des clients

L’onglet Customers fournit une vue détaillée sous forme de tableau des données d’utilisation des clients, avec les informations suivantes :

Colonnes de données disponibles

string

Adresse e-mail du client à des fins d’identification.

string

Identifiant unique de l’abonnement du client.

number

Nombre d’unités gratuites incluses dans le forfait du client avant l’application de frais.

currency

Coût par unité pour l’utilisation au-delà du seuil gratuit.

timestamp

Timestamp de l’événement d’utilisation le plus récent du client.

currency

Montant total facturé au client pour la facturation basée sur l’utilisation.

number

Nombre total d’unités consommées par le client.

number

Nombre d’unités qui dépassent le seuil gratuit et sont facturées.

Fonctionnalités du tableau

Filtrage des colonnes : utilisez la fonctionnalité “Edit Columns” pour afficher ou masquer des colonnes de données spécifiques
Mises à jour en temps réel : les données d’utilisation reflètent les métriques de consommation les plus récentes

Exemples d’agrégation

Voici des exemples pratiques du fonctionnement des différents types d’agrégation :

Comprendre les types d’agrégation

Les différents types d’agrégation correspondent à différents scénarios de facturation. Choisissez le type approprié selon la manière dont vous souhaitez mesurer et facturer l’utilisation.

Exemples pratiques d’implémentation

Ces exemples illustrent les applications concrètes de chaque type d’agrégation, avec des événements d’exemple et les résultats attendus.

Count Aggregation - API Calls

Scénario : suivre le nombre total de requêtes APIConfiguration du meter :

Nom de l’événement : api.call
Type d’agrégation : Count
Unité de mesure : calls

Événements d’exemple :

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

Résultat : 3 appels facturés au client

Sum Aggregation - Data Transfer

Scénario : facturer en fonction du nombre total d’octets transférésConfiguration du meter :

Nom de l’événement : data.transfer
Type d’agrégation : Sum
Over Property : bytes
Unité de mesure : GB

Événements d’exemple :

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

Résultat : 1,5 Go de transfert total facturé au client

Max Aggregation - Peak Concurrent Users

Scénario : facturer en fonction du nombre maximal d’utilisateurs simultanésConfiguration du meter :

Nom de l’événement : concurrent.users
Type d’agrégation : Max
Over Property : count
Unité de mesure : users

Événements d’exemple :

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

Résultat : 23 utilisateurs simultanés au pic facturés au client

Exemples de filtrage des événements

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

Compter uniquement les appels API vers des points de terminaison spécifiques :Configuration du filtre :

Propriété : endpoint
Comparateur : equals
Valeur : /v1/orders

Événement d’exemple :

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

Résultat : les événements correspondant aux critères du filtre seront comptabilisés. Les événements associés à d’autres points de terminaison seront ignorés.

Compter uniquement les téléversements de fichiers volumineux :Configuration du filtre :

Propriété : file_size
Comparateur : greater_than
Valeur : 1048576 (1 Mo en octets)

Événement d’exemple :

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

Résultat : les fichiers de plus de 1 Mo seront comptabilisés. Les fichiers plus petits seront ignorés.

Compter les appels API premium pendant les heures ouvrées :Configuration du filtre (avec une logique AND) :

Propriété : plan_type, Comparateur : equals, Valeur : premium
Propriété : hour, Comparateur : greater_than_or_equals, Valeur : 9
Propriété : hour, Comparateur : less_than, Valeur : 17

Événement d’exemple :

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

Résultat : les appels API premium effectués pendant les heures ouvrées (de 9 h à 17 h) seront comptabilisés.

Dépannage

Résolvez les problèmes courants liés à l’implémentation de la facturation basée sur l’utilisation et assurez un suivi ainsi qu’une facturation précis.

Problèmes courants

La plupart des problèmes de facturation basée sur l’utilisation relèvent des catégories suivantes :

Problèmes de livraison et de traitement des événements
Problèmes de configuration des meters
Erreurs de type et de format des données
Problèmes liés à l’ID client et à l’authentification

Étapes de débogage

Lors du dépannage de la facturation basée sur l’utilisation :

Vérifiez la livraison des événements dans l’onglet d’analyses Events
Vérifiez que la configuration du meter correspond à la structure de vos événements
Validez les ID client et l’authentification API
Examinez les conditions de filtrage et les paramètres d’agrégation

Solutions et correctifs

Events not showing in meter

Causes courantes :

Le nom de l’événement ne correspond pas exactement à la configuration du meter
Les conditions de filtrage des événements excluent vos événements
L’ID client n’existe pas dans votre compte Dodo Payments
Le timestamp de l’événement se situe en dehors de la période de facturation actuelle

Solutions :

Vérifiez l’orthographe du nom de l’événement et la distinction majuscules-minuscules
Examinez et testez vos conditions de filtrage
Confirmez que l’ID client est valide et actif
Vérifiez que les timestamps des événements sont récents et correctement formatés

Aggregation not working as expected

Causes courantes :

Le nom de l’Over Property ne correspond pas aux clés des métadonnées de l’événement
Les valeurs des métadonnées sont d’un type incorrect (chaîne au lieu de nombre)
Des propriétés de métadonnées obligatoires sont manquantes

Solutions :

Assurez-vous que les clés des métadonnées correspondent exactement à votre paramètre Over Property
Convertissez les nombres sous forme de chaînes en nombres réels dans vos événements
Incluez toutes les propriétés obligatoires dans chaque événement

Filtering not working

Causes courantes :

Les noms des propriétés de filtrage ne correspondent pas aux métadonnées de l’événement
Le comparateur ne convient pas au type de données (chaîne au lieu de nombre)
La distinction majuscules-minuscules dans les comparaisons de chaînes

Solutions :

Vérifiez attentivement que les noms des propriétés correspondent exactement
Utilisez des comparateurs adaptés à vos types de données
Tenez compte de la distinction majuscules-minuscules lors du filtrage des chaînes

Référence API associée

Create Meter

Référence API pour créer et configurer des meters d’utilisation afin de suivre la consommation des clients

Ingest Usage Events

Référence API pour envoyer des événements d’utilisation vers vos meters configurés pour les calculs de facturation

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

Éléments clés à connaître pour une ingestion fiable

Analyses de la facturation basée sur l’utilisation

Analyses générales

Métriques d’activité

Graphique des quantités des meters

Analyses des événements

Affichage des informations sur les événements

Analyses des clients

Colonnes de données disponibles

Fonctionnalités du tableau

Exemples d’agrégation

Comprendre les types d’agrégation

Exemples pratiques d’implémentation

Exemples de filtrage des événements

Dépannage

Problèmes courants

Étapes de débogage

Solutions et correctifs

Référence API associée

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

​Éléments clés à connaître pour une ingestion fiable

​Analyses de la facturation basée sur l’utilisation

​Analyses générales

​Métriques d’activité

​Graphique des quantités des meters

​Analyses des événements

​Affichage des informations sur les événements

​Analyses des clients

​Colonnes de données disponibles

​Fonctionnalités du tableau

​Exemples d’agrégation

​Comprendre les types d’agrégation

​Exemples pratiques d’implémentation

​Exemples de filtrage des événements

​Dépannage

​Problèmes courants

​Étapes de débogage

​Solutions et correctifs

​Référence API associée

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

Éléments clés à connaître pour une ingestion fiable

Analyses de la facturation basée sur l’utilisation

Analyses générales

Métriques d’activité

Graphique des quantités des meters

Analyses des événements

Affichage des informations sur les événements

Analyses des clients

Colonnes de données disponibles

Fonctionnalités du tableau

Exemples d’agrégation

Comprendre les types d’agrégation

Exemples pratiques d’implémentation

Exemples de filtrage des événements

Dépannage

Problèmes courants

Étapes de débogage

Solutions et correctifs

Référence API associée