Enregistrer l'utilisation en vue de la facturation
Note
Nous avons mis à jour notre processus de facturation à la consommation. Pour en savoir plus sur les anciennes instructions, consultez notre ancienne documentation sur la facturation à la consommation.
Configuration du dispositif de mesure de la consommation
Assurez-vous d’avoir correctement configuré votre dispositif de mesure de la consommation avant d’enregistrer l’utilisation. Les dispositifs de mesure sont immuables, à l’exception de leur nom affiché.
Nom de l’événement
Il s’agit du nom de l’événement de mesure pour lequel vous prévoyez d’enregistrer l’utilisation avec ce dispositif. Utilisez ce nom dans le champ event_name
de l’événement de mesure lorsque vous envoyez l’utilisation à Stripe. De cette façon, l’utilisation est prise en compte et additionnée par le bon dispositif de mesure. Vous ne pouvez utiliser un nom d’événement qu’avec un seul dispositif.
Ingestion des données sur l’événement
Indiquez la manière dont vous souhaitez envoyer les événements à Stripe. Vous avez le choix entre deux options :
- Brut : traitez tous les événements de mesure comme des événements indépendants. Lorsque plusieurs événements sont envoyés avec le même horodatage, ils ne s’écrasent pas les uns les autres et sont inclus dans la compilation. Si rien n’est spécifié, c’est l’option par défaut.
- Précompilés (horaire ou quotidien) : si vous envoyez des événements précompilés sur un intervalle de temps spécifique (soit horaire, soit quotidien), Stripe utilise uniquement l’événement de mesure le plus récent dans la période horaire ou quotidienne pour l’agrégation. Un nouvel événement envoyé dans la même période horaire ou quotidienne remplace l’événement précédent.
Formule d’agrégation
Indiquez comment agréger la consommation sur la période de facturation. Les options pour ce paramètre sont les suivantes :
- Somme : facture basée sur la somme de toutes les valeurs d’utilisation pour la période de facturation.
- Nombre : facture basée en fonction du nombre d’utilisations au cours de la période de facturation.
- Dernier enregistrement (bientôt disponible) : facture établie sur l’enregistrement de la consommation le plus récent pour la période de facturation. Si aucune consommation n’est communiquée, la facture est basée sur une quantité d’utilisation de 0.
- Max (bientôt): Facturer sur la base de la valeur la plus élevée dans le laps de temps spécifié (seconde, heure, jour) au cours de la période de facturation. Par exemple, le nombre maximum d’utilisateurs qui se sont connectés au cours d’une journée de la période de facturation, souvent appelé “high watermark billing” (facturation en filigrane)
Rectifications de la clé de charge utile
Spécifiez les clés de la charge utile de l’événement correspondant aux valeurs d’utilisation client et numérique.
- value_settings : définissez la clé faisant référence à la valeur d’utilisation numérique dans la charge utile de l’événement de mesure de la consommation avec ce paramètre. Si la clé par défaut est
value
, vous pouvez spécifier une clé différente, par exemple des tokens. - customer_mapping : définissez la clé dans la charge utile de l’événement associée à l’ID du client Stripe avec ce paramètre. Si la clé par défaut est
stripe_customer_id
, vous pouvez en spécifier une autre (par exemple,customer_id
).
Enregistrement de l’utilisation
Vous pouvez communiquer à Stripe les informations relatives à l’utilisation en créant des événements de mesure de la consommation contenant un customer_id
, une valeur numérique et un horodatage (facultatif). C’est à vous de décider la fréquence à laquelle vous nous communiquerez l’utilisation. Par exemple, vous pouvez envoyer l’utilisation au fur et à mesure ou par lots (par exemple, chaque jour). Au terme de la période de facturation, Stripe calcule automatiquement le prix total et génère une facture tenant compte de toute utilisation pour la période de facturation.
Pour créer des événements de mesure :
Idempotence
Utilisez les clés d’idempotence pour éviter d’envoyer des données d’utilisation en double en cas de latence ou d’autres problèmes. Chaque événement de compteur correspond à un identifiant que vous pouvez spécifier dans votre requête (si vous ne le spécifiez pas, nous en générons un automatiquement).
Horodatage des événements
Assurez-vous que l’horodatage est compris dans les 35 derniers jours calendaires et qu’il ne se situe pas plus de 5 minutes dans le futur (la fenêtre de 5 minutes tient compte du décalage entre l’horloge de votre serveur et celle des systèmes de Stripe).
Valeurs d’utilisation
La valeur numérique de l’utilisation dans la charge utile n’accepte que les nombres entiers positifs.
Vous souhaitez utiliser des valeurs décimales ou négatives ?
Contactez-nous à l’adresse usage-based-billing@stripe.com afin que nous puissions mieux comprendre votre cas d’usage.
Limites d’appels
Tenez compte de la limite d’appels. L’endpoint d’événements de mesure autorise un maximum de 1 000 appels par seconde et par compte Stripe, et un appel simultané par client et par dispositif de mesure. Si votre service est susceptible de dépasser cette limite, vous pouvez créer un produit groupé. Par exemple, si vous facturez par lot de 1 000 requêtes, vous pourriez définir un produit correspondant à 1 000 transactions et envoyer 1 enregistrement d’utilisation par lot de 1 000.
Surveillez les codes d’état 429
et implémentez un mécanisme de relance avec un délai d’attente qui augmente de manière exponentielle pour gérer le volume de requêtes.
En outre, nous vous recommandons d’incorporer une part d’aléatoire à vos délais d’attente pour éviter tout effet de réaction de masse.
Vous souhaitez augmenter les plafonds ?
You can report usage either by dropping it into an S3 bucket or through a bulk endpoint. Learn about recording usage for billing with the S3 connector. For a better understanding of your specific needs and to get early access, reach out to us at usage-based-billing@stripe.com.
Bonnes pratiques
Les données d’utilisation sont essentielles pour garantir une facturation précise des utilisateurs. Protégez votre système contre les défaillances réseau. Par exemple, utilisez une file d’attente fiable comme Amazon SQS pour envoyer les données à Stripe afin de pouvoir effectuer de nouvelles tentatives si nécessaire.
Corriger les utilisations erronées
Vous pouvez annuler les événements communiqués par erreur, à l’aide du réajustement des événements de mesure. Pour ce faire, vous avez besoin de l’identifiant de l’événement de mesure concerné.
L’annulation des événements de mesure est soumise aux restrictions suivantes :
- Vous pouvez uniquement annuler les événements qui ont été envoyés à Stripe au cours des dernières 24 heures.
- Nous ne prenons pas en charge les réajustements de factures dans le cadre des utilisations annulées pour lesquelles nous avons déjà facturé le client.
- Si vous annulez l’utilisation déjà incluse sur une facture finalisée, nous ne mettons pas cette facture à jour. De plus, nous n’envoyons pas de nouvelle facture corrective pour l’utilisation annulée.