Guide d’intégration de la facturation basée sur l’utilisation

API Reference — Events Ingestion

Accédez à la documentation complète de l’API pour ingérer des événements d’utilisation et testez interactivement les requêtes et réponses d’ingestion d’événements.

API Reference — Meters Creation

Consultez la documentation complète de l’API pour créer des compteurs et testez interactivement les requêtes et réponses de création de compteurs.

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

Suivez ce guide pour configurer votre compteur d’utilisation :

Configure Basic Information

Set up the fundamental details for your meter.

string

requis

Un nom clair et descriptif qui identifie ce que suit ce compteur.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

string

Une explication détaillée de ce que mesure ce compteur.Example: “Counts each POST /v1/orders request made by the customer”

string

requis

L’identifiant de l’événement qui déclenchera ce compteur.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

Compte le nombre d’événements reçus.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

Le libellé de l’unité à afficher dans les rapports et la facturation.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 la 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

Vérifiez la configuration de votre compteur, puis cliquez sur Create Meter.

Votre compteur est maintenant prêt à recevoir et à agréger les événements d’utilisation.

Associer un compteur à un produit

Une fois votre compteur créé, vous devez l’associer à un produit pour activer la facturation à l’usage. Ce processus relie les données d’utilisation de votre compteur aux règles tarifaires appliquées à la facturation des clients. L’association de compteurs à des produits établit le lien entre le suivi de l’utilisation et la facturation :

Les produits définissent les règles tarifaires et le comportement de facturation
Les compteurs fournissent les données d’utilisation nécessaires aux calculs de facturation
Plusieurs compteurs peuvent être associés à un même produit pour les scénarios de facturation complexes

Processus de configuration du produit

Transformez vos données d’utilisation en frais facturables en configurant correctement les paramètres de votre produit :

Choose Usage-Based Billing Product Type

Accédez à la page de création ou de modification de votre produit et sélectionnez Usage Based Billing comme type de tarification.

Select Associated Meter

Cliquez sur Associated Meters pour ouvrir le panneau de sélection des compteurs.Ce panneau vous permet de configurer les compteurs qui suivront l’utilisation de ce produit.

Add Your Meter

Dans le panneau de sélection des compteurs :

Cliquez sur Add Meters pour afficher les compteurs disponibles
Sélectionnez le compteur que vous avez créé dans la liste déroulante
Le compteur sélectionné apparaîtra dans la configuration de votre produit

Configure Price Per Unit

Définissez le prix de chaque unité d’utilisation suivie par votre compteur.

number

requis

Définissez le montant à facturer pour chaque unité mesurée par votre compteur.Exemple : Fixer le prix à $0.50 par unité signifie :

1 000 unités consommées = 1 000 × $0.50 = $500.00 facturés
500 unités consommées = 500 × $0.50 = $250.00 facturés
100 unités consommées = 100 × $0.50 = $50.00 facturés

Set Free Threshold (Optional)

Configurez un quota d’utilisation gratuite avant le début de la facturation.

number

Nombre d’unités que les clients peuvent consommer gratuitement avant le début du calcul de l’utilisation payante.Fonctionnement :

Seuil gratuit : 100 unités
Prix par unité : $0.50
Utilisation du client : 250 unités
Calcul : (250 - 100) × $0.50 = $75.00 facturés

Les seuils gratuits sont idéaux pour les modèles freemium, les périodes d’essai ou l’inclusion d’un quota de base dans le forfait des clients.

Le seuil gratuit s’applique à chaque cycle de facturation, offrant aux clients un nouveau quota chaque mois ou selon votre calendrier de facturation.

Save Configuration

Vérifiez la configuration de votre compteur et de votre tarification, puis cliquez sur Save Changes pour finaliser la configuration.

Votre produit est maintenant configuré pour la facturation à l’usage et facturera automatiquement les clients en fonction de leur consommation mesurée.

Étapes suivantes :

Les événements d’utilisation envoyés à votre compteur seront suivis et agrégés
Les calculs de facturation appliqueront automatiquement vos règles tarifaires
Les clients seront facturés en fonction de leur consommation réelle au cours de chaque cycle de facturation

Vous pouvez ajouter jusqu’à 50 compteurs par produit, ce qui permet un suivi sophistiqué de l’utilisation selon plusieurs dimensions telles que les appels API, le stockage, le temps de calcul et les métriques personnalisées.

Envoyer des événements d’utilisation

Une fois votre compteur configuré, vous pouvez commencer à envoyer des événements d’utilisation depuis votre application pour suivre l’utilisation des clients.

Structure d’un événement

Chaque événement d’utilisation doit inclure les champs obligatoires suivants :

string

requis

Un identifiant unique pour cet événement spécifique. Doit être unique pour tous les événements.

string

requis

L’ID client Dodo Payments auquel cette utilisation doit être attribuée.

string

requis

Le nom de l’événement correspondant à la configuration de votre compteur. Les noms d’événements déclenchent le compteur approprié.

string

Horodatage ISO 8601 indiquant le moment où l’événement s’est produit. Utilise par défaut l’horodatage UTC actuel s’il n’est pas fourni. Doit se situer dans l’heure passée ou les 5 minutes à venir — les horodatages en dehors de cette fenêtre sont rejetés.

object

Propriétés supplémentaires utilisées pour le filtrage et l’agrégation. Incluez toutes les valeurs référencées dans la propriété “Over Property” de votre compteur ou dans les conditions de filtrage.

Exemples de l’API des événements d’utilisation

Envoyez des événements d’utilisation à vos compteurs configurés à l’aide de l’API Events :

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 os
import requests
from datetime import datetime, timezone

response = requests.post(
    'https://test.dodopayments.com/events/ingest',
    headers={
        'Authorization': f"Bearer {os.environ['DODO_PAYMENTS_API_KEY']}",
        'Content-Type': 'application/json'
    },
    json={
        'events': [
            {
                'event_id': 'api_call_1234',
                'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
                'event_name': 'api.call',
                'timestamp': datetime.now(timezone.utc).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
        }
      }
    ]
  }'

Points essentiels pour une ingestion fiable

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

Utilisez des event_id déterministes et idempotents. Le event_id doit être unique pour tous les événements et sert de clé d’idempotence. La réutilisation d’un event_id est considérée comme un doublon et ne sera pas comptabilisée à nouveau, de sorte que les nouvelles tentatives n’entraînent jamais une double facturation. Dérivez 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 un maximum strict de 1 000 événements par requête. Les lots plus importants sont rejetés : répartissez donc les volumes élevés sur plusieurs appels. Pour les charges importantes, 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 pour les erreurs 5xx et 429, mais jamais pour les autres erreurs 4xx. Réessayez en cas d’erreurs serveur (5xx) et de limites de débit (429) avec un backoff exponentiel. Ne réessayez pas pour les erreurs de validation 400/422 — la charge utile est mal formée et échouera à chaque fois. Corrigez-la et renvoyez-la. Mettez en file d’attente les événements qui échouent encore après les nouvelles tentatives afin qu’aucun ne soit perdu.

Définissez les horodatages intentionnellement. Omettez timestamp pour les événements en temps réel : il prendra par défaut l’horodatage UTC actuel. Définissez-le explicitement (au format ISO 8601) pour les événements différés ou regroupés afin que l’utilisation soit enregistrée dans la bonne période de facturation. Notez que la fenêtre acceptée est étroite : les événements horodatés plus d’une heure dans le passé ou plus de 5 minutes dans le futur sont rejetés. Le rattrapage historique n’est pas pris en charge — envoyez les événements mis en mémoire tampon dans l’heure.

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 la propriété Over Property d’un compteur (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 à l’usage

Surveillez et analysez vos données de facturation à l’usage grâce à un tableau de bord analytique complet. Suivez les habitudes de consommation des clients, les performances des compteurs 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 à l’usage :

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 et vous aide à comprendre les habitudes de consommation mensuelles.

metric

Affiche les statistiques cumulées d’utilisation depuis le début du suivi et fournit 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 modèles de croissance.

Graphique des quantités des compteurs

Le graphique des quantités des compteurs visualise les tendances d’utilisation au fil du temps grâce aux fonctionnalités suivantes :

Visualisation chronologique : suivez les habitudes d’utilisation sur plusieurs jours, semaines ou mois
Prise en charge de plusieurs compteurs : affichez simultanément les données de différents compteurs
Analyse des tendances : identifiez les pics d’utilisation, les habitudes 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 variations importantes.

Analyses des événements

Tableau des événements affichant les noms et ID des événements ainsi que les commandes 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 offre 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 à l’origine de l’événement d’utilisation
ID de l’événement : un identifiant unique pour chaque instance d’événement
ID client : le client associé à l’événement
Horodatage : le moment où l’événement s’est produit

Cette vue vous permet de suivre et de surveiller les événements d’utilisation individuels de l’ensemble de vos 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

L’adresse e-mail du client utilisée pour l’identifier.

string

Un identifiant unique pour l’abonnement du client.

number

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

currency

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

timestamp

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

currency

Montant total facturé au client pour la facturation à l’usage.

number

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

number

Nombre d’unités dépassant le seuil gratuit et faisant l’objet d’une facturation.

Fonctionnalités du tableau

Filtrage des colonnes : utilisez la fonctionnalité “Edit Columns” pour afficher ou masquer certaines colonnes de données
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 répondent à différents scénarios de facturation. Choisissez le type approprié selon la manière dont vous souhaitez mesurer et facturer l’utilisation.

Exemples pratiques de mise en œuvre

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

Count Aggregation — API Calls

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

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

Événements types :

{
  "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 compteur :

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

Événements types :

{
  "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 compteur :

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

Événements types :

{
  "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 type :

{
  "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 sont comptabilisés. Les événements associés à d’autres points de terminaison sont ignorés.

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

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

Événement type :

{
  "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 sont comptabilisés. Les fichiers plus petits sont 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 type :

{
  "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) sont comptabilisés.

Résolution des problèmes

Résolvez les problèmes courants liés à la mise en œuvre de la facturation à l’usage et garantissez un suivi et une facturation précis.

Problèmes courants

La plupart des problèmes de facturation à l’usage appartiennent aux catégories suivantes :

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

Étapes de débogage

Lors de la résolution de problèmes liés à la facturation à l’usage :

Vérifiez la livraison des événements dans l’onglet d’analyses Events
Vérifiez que la configuration du compteur correspond à la structure de vos événements
Validez les ID client et l’authentification de l’API
Vérifiez 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 compteur
Les conditions de filtrage des événements excluent vos événements
L’ID client n’existe pas dans votre compte Dodo Payments
L’horodatage 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 casse
Examinez et testez vos conditions de filtrage
Confirmez que l’ID client est valide et actif
Vérifiez que les horodatages des événements sont récents et correctement formatés

Aggregation not working as expected

Causes courantes :

Le nom de la propriété Over Property ne correspond pas aux clés des métadonnées de l’événement
Les valeurs des métadonnées ont 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 véritables nombres 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 correspond pas au type de données (chaîne au lieu de nombre)
La casse n’est pas respectée dans les comparaisons de chaînes

Solutions :

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

Référence API associée

Create Meter

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

Ingest Usage Events

Référence API pour envoyer des événements d’utilisation à vos compteurs configurés à des fins de calcul de la facturation.

Integration Guides

Billing Deconstructions

Cookbooks

Guide d’intégration de la facturation basée sur l’utilisation

API Reference — Events Ingestion

API Reference — Meters Creation

Creating a Meter

Step-by-Step Meter Creation

Associer un compteur à un produit

Processus de configuration du produit

Envoyer des événements d’utilisation

Structure d’un événement

Exemples de l’API des événements d’utilisation

Points essentiels pour une ingestion fiable

Analyses de la facturation à l’usage

Analyses générales

Métriques d’activité

Graphique des quantités des compteurs

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 de mise en œuvre

Exemples de filtrage des événements

Résolution des problèmes

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

​Associer un compteur à un produit

​Processus de configuration du produit

​Envoyer des événements d’utilisation

​Structure d’un événement

​Exemples de l’API des événements d’utilisation

​Points essentiels pour une ingestion fiable

​Analyses de la facturation à l’usage

​Analyses générales

​Métriques d’activité

​Graphique des quantités des compteurs

​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 de mise en œuvre

​Exemples de filtrage des événements

​Résolution des problèmes

​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

Associer un compteur à un produit

Processus de configuration du produit

Envoyer des événements d’utilisation

Structure d’un événement

Exemples de l’API des événements d’utilisation

Points essentiels pour une ingestion fiable

Analyses de la facturation à l’usage

Analyses générales

Métriques d’activité

Graphique des quantités des compteurs

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 de mise en œuvre

Exemples de filtrage des événements

Résolution des problèmes

Problèmes courants

Étapes de débogage

Solutions et correctifs

Référence API associée