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

API Reference - Events Ingestion

Accédez à la documentation API complète pour ingérer les événements d’utilisation et tester de manière interactive les requêtes et réponses d’ingestion d’événements.

API Reference - Meters Creation

Explorez la documentation API complète pour créer des compteurs et tester de manière interactive les requêtes et réponses de création de compteur.

Création d’un compteur

Les compteurs définissent comment vos événements d’utilisation sont agrégés et mesurés à des fins de facturation. Avant de créer un compteur, planifiez votre stratégie de suivi de l’utilisation :

Identifiez les événements d’utilisation que vous souhaitez suivre
Déterminez comment les événements doivent être agrégés (compte, somme, etc.)
Définissez les exigences de filtrage pour des cas d’utilisation spécifiques

Étapes de création de compteur

Suivez ce guide complet pour configurer votre compteur d’utilisation :

Configure Basic Information

Configurez les éléments fondamentaux de votre compteur.

Meter Name

string

requis

Choisissez un nom clair et descriptif qui identifie ce que ce compteur mesure.Exemples : “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”

Description

string

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

Event Name

string

requis

Précisez l’identifiant d’événement qui déclenchera ce compteur.Exemples : “token”, “api.call”, “storage.usage”, “compute.session”

Le nom de l’événement doit correspondre exactement à ce que vous envoyez dans vos événements d’utilisation. Les noms d’événements sont sensibles à la casse.

Configure Aggregation Settings

Définissez la façon dont le compteur calcule l’utilisation à partir de vos événements.

Aggregation Type

string

requis

Sélectionnez la manière dont les événements doivent être agrégés :

Count
Sum
Max
Last

Compte simplement le nombre d’événements reçus.Cas d’utilisation : appels API, vues de pages, téléchargements de fichiersCalcul : nombre total d’événements

Over Property

string

Le nom de la propriété des métadonnées d’événement sur laquelle agréger.

Ce champ est requis lors de l’utilisation des types d’agrégation Sum, Max ou Last.

Measurement Unit

string

requis

Définissez l’étiquette d’unité pour l’affichage dans les rapports et la facturation.Exemples : “calls”, “GB”, “hours”, “tokens”

Configure Event Filtering (Optional)

Définissez des critères permettant de contrôler les événements inclus dans le compteur.

Le filtrage d’événements vous permet d’élaborer des règles sophistiquées qui déterminent quels événements contribuent à vos calculs d’utilisation. Cela est utile pour exclure les événements de test, filtrer par niveaux d’utilisateurs ou se concentrer sur des actions spécifiques.

Activer le filtrage des événementsActivez Activer le filtrage des événements pour activer le traitement conditionnel des événements.Choisir la logique de filtrageSélectionnez comment plusieurs conditions sont évaluées :

AND Logic
OR Logic

Toutes les conditions doivent être vraies pour qu’un événement soit comptabilisé. Utilisez cette option lorsque vous avez besoin que les événements remplissent plusieurs critères stricts simultanément.Exemple : comptez les appels API où user_tier = "premium" ET endpoint = "/api/v2/users"

Au moins une condition doit être vraie pour qu’un événement soit comptabilisé. Utilisez cette option lorsque vous souhaitez inclure des événements répondant à n’importe lequel de plusieurs critères.Exemple : comptez les événements où method = "POST" OU method = "PUT" OU method = "DELETE"

Configuration des conditions de filtrage

Add Condition

Cliquez sur Add condition pour créer une nouvelle règle de filtre.

Configure Property Key

Précisez le nom de la propriété issue de vos métadonnées d’événement.

Select Comparator

Choisissez parmi les opérateurs disponibles :

equals - Exact match
not equals - Exclusion filter
greater than - Numeric comparison
greater than or equals - Numeric comparison (inclusive)
less than - Numeric comparison
less than or equals - Numeric comparison (inclusive)
contains - String contains substring
does not contain - String exclusion filter

Set Comparison Value

Définissez la valeur cible pour la comparaison.

Add Groups

Utilisez Add Group pour créer des groupes de conditions supplémentaires pour une logique complexe.

Les propriétés filtrées doivent être incluses dans vos métadonnées d’événement pour que les conditions fonctionnent correctement. Les événements dépourvus des propriétés requises seront exclus du comptage.

Create Meter

Passez en revue la configuration de votre compteur et cliquez sur Create Meter.

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

Lier le compteur à un produit

Une fois que vous avez créé votre compteur, vous devez le lier à un produit pour activer la facturation basée sur l’utilisation. Ce processus connecte les données d’utilisation de votre compteur aux règles de tarification pour la facturation des clients. Lier des compteurs à des produits établit la connexion entre le suivi de l’utilisation et la facturation :

Les produits définissent les règles de tarification et le comportement de facturation
Les compteurs fournissent des données d’utilisation pour les calculs de facturation
Plusieurs compteurs peuvent être liés à un seul produit pour des 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 à votre page de création ou d’édition de produit et sélectionnez Usage-Based comme type de produit.

Select Associated Meter

Cliquez sur Associated Meter pour ouvrir le panneau de sélection de compteur depuis la barre latérale.Ce panneau vous permet de configurer les compteurs qui suivront l’utilisation pour ce produit.

Add Your Meter

Dans le panneau de sélection de compteur :

Cliquez sur Ajouter des compteurs pour voir 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 pour chaque unité d’utilisation suivie par votre compteur.

Price Per Unit

number

requis

Indiquez combien facturer pour chaque unité mesurée par votre compteur.Exemple : fixer $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 une allocation d’utilisation gratuite avant le début de la facturation.

Free Threshold

number

Nombre d’unités que les clients peuvent consommer sans frais avant que le calcul de l’usage payant ne démarre.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 conviennent parfaitement aux modèles freemium, aux périodes d’essai ou pour offrir aux clients une allocation de base incluse dans leur plan.

Le seuil gratuit s’applique à chaque cycle de facturation, offrant aux clients de nouveaux crédits mensuels ou selon votre calendrier de facturation.

Save Configuration

Passez en revue la configuration de votre compteur et de vos tarifs, puis cliquez sur Save Changes pour finaliser la configuration.

Votre produit est désormais configuré pour une facturation basée sur l’utilisation et facturera automatiquement les clients en fonction de leur consommation mesurée.

Ce qui se passe ensuite :

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 lors de chaque cycle de facturation

N’oubliez pas que vous pouvez ajouter jusqu’à 10 compteurs par produit, permettant un suivi d’utilisation sophistiqué selon plusieurs dimensions comme les appels API, le stockage, le temps de calcul et les métriques personnalisées.

Envoi d’événements d’utilisation

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

Structure de l’événement

Chaque événement d’utilisation doit inclure ces champs requis :

event_id

string

requis

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

customer_id

string

requis

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

event_name

string

requis

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

timestamp

string

Horodatage au format ISO 8601 de la survenue de l’événement. Utilise l’heure actuelle par défaut si non fourni.

metadata

object

Propriétés supplémentaires pour le filtrage et l’agrégation. Incluez toutes les valeurs référencées dans le paramètre « Over Property » ou les conditions de filtrage de votre compteur.

Exemples d’API d’événements d’utilisation

Envoyez des événements d’utilisation à vos compteurs configurés en utilisant l’API des événements :

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

Analyse de la facturation basée sur l’utilisation

Surveillez et analysez vos données de facturation basée sur l’utilisation avec un tableau de bord d’analyse complet. Suivez les modèles de consommation des clients, la performance des compteurs et les tendances de facturation pour optimiser votre stratégie de tarification et comprendre les comportements d’utilisation.

Analyse d’ensemble

L’onglet d’ensemble fournit une vue complète de votre performance de facturation basée sur l’utilisation :

Métriques d’activité

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

Current Month

metric

Affiche l’activité d’utilisation pour la période de facturation en cours, ce qui vous aide à comprendre les modèles de consommation mensuels.

All Time

metric

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

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

Graphique des quantités de compteurs

Graphique des quantités du compteur montrant les tendances d'utilisation au fil du temps avec une visualisation en dégradé violet

Le graphique des quantités de compteurs visualise les tendances d’utilisation au fil du temps avec les fonctionnalités suivantes :

Visualisation en série temporelle : Suivez les modèles d’utilisation sur des jours, des semaines ou des mois
Support de plusieurs compteurs : Affichez les données de différents compteurs simultanément
Analyse des tendances : Identifiez les pics d’utilisation, les modèles et les trajectoires de croissance

Le graphique s’adapte automatiquement en fonction de votre volume d’utilisation et de la plage temporelle sélectionnée, offrant une visibilité claire tant sur les petites fluctuations que sur les variations majeures d’utilisation.

Analyse des événements

Table des événements montrant les noms d'événements, les identifiants et les commandes de pagination pour une analyse détaillée

L’onglet Événements fournit une visibilité granulaire 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 qui a généré l’événement d’utilisation
ID de l’événement : Identifiant unique pour chaque instance d’événement
ID client : Le client associé à l’événement
Horodatage : Quand l’événement s’est produit

Cette vue vous permet de suivre et surveiller les événements d’utilisation individuels au sein de votre base clients, offrant transparence sur les calculs de facturation et les tendances d’utilisation.

Analyse des clients

L’onglet Clients 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

Customer Email

string

Adresse e-mail du client pour l’identification.

Subscription ID

string

Identifiant unique de l’abonnement du client.

Free Threshold

number

Nombre d’unités gratuites incluses dans le plan du client avant que les frais ne s’appliquent.

Price Per Unit

currency

Coût par unité pour l’utilisation dépassant le seuil gratuit.

Last Event

timestamp

Horodatage du dernier événement d’utilisation du client.

Total Price

currency

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

Consumed Units

number

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

Chargeable Units

number

Nombre d’unités dépassant le seuil gratuit et facturées.

Fonctionnalités du tableau

Filtrage des colonnes : Utilisez la fonction “Modifier les colonnes” pour afficher/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 de la façon dont différents types d’agrégation fonctionnent :

Comprendre les types d’agrégation

Différents types d’agrégation servent différents scénarios de facturation. Choisissez le bon type en fonction de la manière dont vous souhaitez mesurer et facturer l’utilisation.

Exemples d’implémentation pratique

Ces exemples démontrent des applications réelles de chaque type d’agrégation avec des événements d’exemple et des 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 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 compteur :

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 selon le 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 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 concurrents au maximum facturés au client

Exemples de filtrage d’événements

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

Comptez 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 de filtre seraient comptabilisés. Les événements avec d’autres points de terminaison seraient ignorés.

Comptez uniquement les téléchargements de gros fichiers :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 supérieurs à 1 Mo seraient comptabilisés. Les fichiers plus petits seraient ignorés.

Comptez les appels API premium pendant les heures ouvrables :Configuration du filtre (logique AND) :

Propriété : plan_type, Comparateur : equals, Valeur : premium
Propriété : hour, Comparateur : greater_than_or_equal, 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 pendant les heures ouvrables (9h - 17h) seraient comptés.

Dépannage

Résolvez les problèmes courants liés à la mise en œuvre de la facturation basée sur l’utilisation et assurez un suivi et une facturation précis.

Problèmes courants

La plupart des problèmes de facturation basée sur l’utilisation se classent dans ces catégories :

Problèmes de livraison et de traitement des événements
Problèmes de configuration des compteurs
Erreurs de type de données et de formatage
Problèmes d’ID client et d’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’analyse des événements
Vérifiez que la configuration du compteur correspond à votre structure d’événement
Validez les ID clients et l’authentification API
Examinez les conditions de filtrage et les paramètres d’agrégation

Solutions et corrections

Events not showing in meter

Causes fréquentes :

Le nom de l’événement ne correspond pas exactement à la configuration du compteur
Les conditions de filtrage excluent vos événements
L’identifiant client n’existe pas dans votre compte Dodo Payments
L’horodatage de l’événement est en dehors de la période de facturation en cours

Solutions :

Vérifiez l’orthographe et la sensibilité à la casse du nom de l’événement
Passez en revue et testez vos conditions de filtrage
Confirmez que l’identifiant 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 fréquentes :

Le nom de la propriété Over Property ne correspond pas aux clés des métadonnées de l’événement
Les valeurs de métadonnées sont de type incorrect (chaîne contre nombre)
Propriétés requises manquantes dans les métadonnées

Solutions :

Assurez-vous que les clés de métadonnées correspondent exactement au paramètre Over Property
Convertissez les nombres en chaînes en véritables nombres dans vos événements
Incluez toutes les propriétés requises dans chaque événement

Filtering not working

Causes fréquentes :

Les noms de propriétés de filtre ne correspondent pas aux métadonnées des événements
Comparateur incorrect pour le type de données (chaîne contre nombre)
Sensibilité à la casse dans les comparaisons de chaînes

Solutions :

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

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

Création d’un compteur

Étapes de création de compteur

Lier le compteur à un produit

Processus de configuration du produit

Envoi d’événements d’utilisation

Structure de l’événement

Exemples d’API d’événements d’utilisation

Analyse de la facturation basée sur l’utilisation

Analyse d’ensemble

Métriques d’activité

Graphique des quantités de compteurs

Analyse des événements

Affichage des informations sur les événements

Analyse des clients

Colonnes de données disponibles

Fonctionnalités du tableau

Exemples d’agrégation

Comprendre les types d’agrégation

Exemples d’implémentation pratique

Exemples de filtrage d’événements

Dépannage

Problèmes courants

Étapes de débogage

Solutions et corrections

Integration Guides

Billing Deconstructions

Cookbooks

API Reference - Events Ingestion

API Reference - Meters Creation

​Création d’un compteur

​Étapes de création de compteur

​Lier le compteur à un produit

​Processus de configuration du produit

​Envoi d’événements d’utilisation

​Structure de l’événement

​Exemples d’API d’événements d’utilisation

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

​Analyse d’ensemble

​Métriques d’activité

​Graphique des quantités de compteurs

​Analyse des événements

​Affichage des informations sur les événements

​Analyse des clients

​Colonnes de données disponibles

​Fonctionnalités du tableau

​Exemples d’agrégation

​Comprendre les types d’agrégation

​Exemples d’implémentation pratique

​Exemples de filtrage d’événements

​Dépannage

​Problèmes courants

​Étapes de débogage

​Solutions et corrections

Création d’un compteur

Étapes de création de compteur

Lier le compteur à un produit

Processus de configuration du produit

Envoi d’événements d’utilisation

Structure de l’événement

Exemples d’API d’événements d’utilisation

Analyse de la facturation basée sur l’utilisation

Analyse d’ensemble

Métriques d’activité

Graphique des quantités de compteurs

Analyse des événements

Affichage des informations sur les événements

Analyse des clients

Colonnes de données disponibles

Fonctionnalités du tableau

Exemples d’agrégation

Comprendre les types d’agrégation

Exemples d’implémentation pratique

Exemples de filtrage d’événements

Dépannage

Problèmes courants

Étapes de débogage

Solutions et corrections