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

Référence API - Ingestion des événements

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

Référence API - Création de compteurs

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

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 :

Configurer les informations de base

Configurez les détails fondamentaux de votre compteur.

Nom du compteur

string

required

Choisissez un nom clair et descriptif qui identifie ce que ce compteur suit.Exemples : “Tokens”, “Appels API”, “Utilisation de stockage”, “Heures de calcul”

Description

string

Fournissez une explication détaillée de ce que ce compteur mesure.Exemple : “Compte chaque requête POST /v1/orders effectuée par le client”

Nom de l'événement

string

required

Spécifiez l’identifiant de l’é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.

Configurer les paramètres d'agrégation

Définissez comment le compteur calcule l’utilisation à partir de vos événements.

Type d'agrégation

string

required

Sélectionnez comment les événements doivent être agrégés :

Compter
Somme
Max
Dernier

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

Sur la propriété

string

Le nom de la propriété à partir des métadonnées de l’événement à agréger.

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

Unité de mesure

string

required

Définissez l’étiquette d’unité à des fins d’affichage dans les rapports et la facturation.Exemples : “appels”, “Go”, “heures”, “tokens”

Configurer le filtrage des événements (optionnel)

Configurez des critères pour contrôler quels événements sont inclus dans le compteur.

Le filtrage des événements vous permet de créer 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’utilisateur 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 :

Logique ET
Logique OU

Toutes les conditions doivent être vraies pour qu’un événement soit compté. Utilisez ceci lorsque vous avez besoin que les événements répondent à 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 compté. Utilisez ceci lorsque vous souhaitez inclure des événements qui répondent à l’un des plusieurs critères.Exemple : Comptez les événements où method = "POST" OU method = "PUT" OU method = "DELETE"

Configuration des conditions de filtrage

Ajouter une condition

Cliquez sur Ajouter une condition pour créer une nouvelle règle de filtrage.

Configurer la clé de propriété

Spécifiez le nom de la propriété à partir de vos métadonnées d’événement.

Sélectionner le comparateur

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 (inclusif)
less than - Comparaison numérique
less than or equals - Comparaison numérique (inclusif)
contains - La chaîne contient une sous-chaîne
does not contain - Filtre d’exclusion de chaîne

Définir la valeur de comparaison

Définissez la valeur cible pour la comparaison.

Ajouter des groupes

Utilisez Ajouter un groupe 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 manquant de propriétés requises seront exclus du comptage.

Créer un compteur

Examinez la configuration de votre compteur et cliquez sur Créer un compteur.

Votre compteur est maintenant prêt à recevoir et à agréger des é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 :

Choisir le type de produit de facturation basée sur l'utilisation

Accédez à votre page de création ou d’édition de produit et sélectionnez Basé sur l’utilisation comme type de produit.

Sélectionner le compteur associé

Cliquez sur Compteur associé pour ouvrir le panneau de sélection de compteur sur le côté.Ce panneau vous permet de configurer quels compteurs suivront l’utilisation pour ce produit.

Ajouter votre compteur

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

Configurer le prix par unité

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

Prix par unité

number

required

Définissez combien facturer pour chaque unité mesurée par votre compteur.Exemple : Définir $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

Définir le seuil gratuit (optionnel)

Configurez une allocation d’utilisation gratuite avant le début de la facturation.

Seuil gratuit

number

Nombre d’unités que les clients peuvent consommer sans frais avant que le calcul de l’utilisation payante ne commence.Comment cela fonctionne :

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 pour fournir aux clients une allocation de base incluse dans leur plan.

Le seuil gratuit s’applique à chaque cycle de facturation, offrant aux clients de nouvelles allocations mensuelles ou selon votre calendrier de facturation.

Enregistrer la configuration

Examinez la configuration de votre compteur et de votre tarification, puis cliquez sur Enregistrer les modifications pour finaliser la configuration.

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

Que se passe-t-il 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 de tarification
Les clients seront facturés en fonction de la consommation réelle pendant chaque cycle de facturation

N’oubliez pas que vous pouvez ajouter jusqu’à 10 compteurs par produit, permettant un suivi sophistiqué de l’utilisation à travers 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

required

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

customer_id

string

required

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

event_name

string

required

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

timestamp

string

Horodatage ISO 8601 lorsque l’événement s’est produit. Par défaut, il s’agit de l’heure actuelle 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 la “Sur la propriété” de votre compteur ou dans les conditions de filtrage.

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_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 :

Mois en cours

metric

Montre l’activité d’utilisation pour la période de facturation actuelle, vous aidant à comprendre les modèles de consommation mensuels.

Tout le temps

metric

Affiche les statistiques cumulatives d’utilisation depuis que vous avez commencé à suivre, fournissant des informations sur la croissance à long terme.

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

Graphique des quantités de compteurs

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 de temps sélectionnée, offrant une visibilité claire sur les petites fluctuations et les changements majeurs d’utilisation.

Analyse des événements

Tableau des événements montrant les noms d'événements, les ID et les contrôles de pagination pour une analyse détaillée des événements

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 de surveiller les événements d’utilisation individuels à travers votre base de clients, offrant une transparence sur les calculs de facturation et les modèles 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

Email du client

string

Adresse e-mail du client pour identification.

ID d'abonnement

string

Identifiant unique pour l’abonnement du client.

Seuil gratuit

number

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

Prix par unité

currency

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

Dernier événement

timestamp

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

Prix total

currency

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

Unités consommées

number

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

Unités facturables

number

Nombre d’unités qui dépassent le seuil gratuit et qui sont 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.

Agrégation par comptage - Appels API

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

Nom de l’événement : api.call
Type d’agrégation : Compter
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

Agrégation par somme - Transfert de données

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 : Somme
Sur la propriété : 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

Agrégation par max - Utilisateurs simultanés maximum

Scénario : Facturer en fonction du nombre maximum d’utilisateurs simultanésConfiguration du compteur :

Nom de l’événement : concurrent.users
Type d’agrégation : Max
Sur la propriété : 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 maximum facturés au client

Exemples de filtrage d’événements

Filtrer par point de terminaison API
Filtrer par plage de valeurs
Filtres complexes à plusieurs conditions

Ne comptez que 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 filtrage seraient comptés. Les événements avec des points de terminaison différents seraient ignorés.

Ne comptez que 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 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 seraient comptés. Les fichiers plus petits seraient ignorés.

Comptez les appels API premium pendant les heures de bureau :Configuration du filtre (en utilisant la logique ET) :

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 de bureau (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

Événements ne s'affichant pas dans le compteur

Causes courantes :

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

Solutions :

Vérifiez l’orthographe et la sensibilité à la casse du nom de l’événement
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

L'agrégation ne fonctionne pas comme prévu

Causes courantes :

Le nom de la propriété sur laquelle se base l’agrégation ne correspond pas aux clés des métadonnées de l’événement
Les valeurs des métadonnées sont du mauvais type de données (chaîne vs nombre)
Propriétés de métadonnées requises manquantes

Solutions :

Assurez-vous que les clés des métadonnées correspondent exactement à votre paramètre de propriété
Convertissez les chaînes de caractères numériques en nombres réels dans vos événements
Incluez toutes les propriétés requises dans chaque événement

Le filtrage ne fonctionne pas

Causes courantes :

Les noms de propriétés de filtrage ne correspondent pas aux métadonnées de l’événement
Mauvais comparateur pour le type de données (chaîne vs nombre)
Sensibilité à la casse dans les comparaisons de chaînes

Solutions :

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

Integration Guides

Cookbooks

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

Référence API - Ingestion des événements

Référence API - Création de compteurs

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

Cookbooks

Référence API - Ingestion des événements

Référence API - Création de compteurs

​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