Accéder directement au contenu
Créez un compte ou connecter-vous
Logo de la documentation Stripe
/
Créez un compteConnectez-vous

Enregistrement de l'usage pour la facturation à l'aide de l'API

Découvrez comment enregistrer l'usage à l'aide de l'API Stripe.

Vous devez enregistrer l’utilisation dans Stripe pour vous assurer de facturer à vos clients les montants exacts à chaque période de facturation. Pour enregistrer l’utilisation, commencez par configurer votre dispositif de mesure, puis envoyez les événements de mesure qui incluent le nom de l’événement configuré sur le dispositif, l’ID du client, la valeur numérique et un horodatage (facultatif).

Vous pouvez décider de la fréquence à laquelle vous enregistrez l’usage dans Stripe, par exemple au fur et à mesure ou par lots. Stripe traite les événements de mesure de manière asynchrone. L’usage compilé dans des récapitulatifs d’événements de mesure et sur les factures à venir peut donc ne pas refléter immédiatement les derniers événements de mesure.

Créer des événements de mesure de la consommation

Créez un événement de mesure à l’aide de l’API.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/billing/meter_events \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d event_name=hypernian_tokens \
  -d "payload[value]=25" \
  -d "payload[stripe_customer_id]={{CUSTOMER_ID}}"

Idempotence

Utilisez les clés d’idempotence pour éviter d’envoyer des données d’usage plus d’une fois en cas de latence ou d’autres problèmes. Chaque événement de mesure correspond à un identifiant que vous pouvez préciser dans votre requête (sinon, 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 sert en cas de 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 accepte des valeurs décimales. Les valeurs décimales sont également prises en charge sur les factures. Si la consommation globale au cours du cycle est négative, Stripe indique que la quantité d’utilisation du sous-poste de facture est égale à 0.

Limites de cardinalité des dimensions

Stripe limite le nombre de combinaisons uniques de paires clé-valeur de charges utiles de dimensions configurées qu’il accepte :

  • Pour chaque compteur, Stripe accepte jusqu’à 10 000 combinaisons uniques pour chaque heure pendant laquelle Stripe reçoit des événements de compteur.
  • Pour chaque client associé à un compteur, Stripe accepte jusqu’à 100 combinaisons uniques sur l’ensemble des événements.

Les événements correspondant à des combinaisons de dimensions déjà comptabilisées dans la limite applicable continuent d’être traités. Les événements qui introduisent une nouvelle combinaison de dimensions après l’atteinte de l’une ou l’autre limite ne sont pas valides et apparaissent dans v1.billing.meter.error_report_triggered avec le code d’erreur meter_event_dimension_count_too_high.

Limites de débit

Les appels à l’endpoint Meter Event en mode production sont soumis à une limite d’appels distincte et ne sont pas comptabilisés dans la limite d’appels globale de votre compte. La limite pour Meter Event est de 1 000 appels par seconde par compte Stripe. En outre, les événements Meter Event sont limités à un appel simultané par client et par compteur.

Dans un environnement de test, les appels vers l’endpoint Meter Events sont comptabilisés dans votre limite d’appels globale. Pour les plateformes Connect, les appels effectués sur un compte connecté vers l’endpoint Meter Events sont également comptabilisés dans la limite de base.

Les événements de compteur comportent également des limites de cardinalité des dimensions, qui limitent le nombre de combinaisons uniques de charges utiles de dimensions acceptées par Stripe. Ces limites sont distinctes des limites d’appels applicables aux requêtes API.

Si vous prévoyez de dépasser ces limites, vous avez deux options :

  • Précompilez vos données d’utilisation avant de les envoyer à Stripe. Par exemple, au lieu d’envoyer un événement pour chaque action individuelle de l’utilisateur, vous pouvez accumuler l’utilisation sur plusieurs actions et envoyer un seul événement agrégé périodiquement. Cela permet de réduire le nombre d’appels à l’API tout en signalant avec précision l’utilisation totale.
  • Utilisez la méthode d’ingestion à haut débit avec des flux d’événements de mesure pour des volumes nettement plus élevés.

Remarque

Si vous êtes une plateforme Connect qui fait des demandes au nom d’un compte connecté en utilisant l’en-tête Stripe-Account, vous êtes soumis à la limite de débit normale de Stripe, qui est de 100 opérations par seconde.

Vous pouvez surveiller les codes d’état 429 et implémenter 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.

Ingestion à haut débit avec des seuils plus élevés API v2

Avec l’API v2, vous pouvez envoyer jusqu’à 10 000 événements par seconde à Stripe en utilisant les flux d’événements de mesure. Cela fonctionne uniquement en mode production.

Cet endpoint utilise des sessions d’identification sans état. Tout d’abord, créez une session d’événement facturé à l’usage pour recevoir un token d’authentification. Les tokens d’authentification ne sont valables que pour 15 minutes, vous devez donc créer une nouvelle session d’événement facturé à l’usage lorsque votre token expire.

Ensuite, utilisez le token d’authentification renvoyé pour créer vos événements de mesure à haut débit avec l’API Meter Event Stream.

Remarque

En raison du volume important de requêtes API, nous n’incluons pas les requêtes de flux d’événements de compteur dans l’onglet Logs de Workbench.

Vous pouvez surveiller les codes d’état 429 et implémenter 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.

Ruby
Python
PHP
Java
Node.js
.NET
Go
No results
require 'stripe'
require 'date'

class MeterEventManager
  attr_accessor :api_key
  attr_accessor :meter_event_session

  def initialize(api_key)
    @api_key = api_key
    @meter_event_session = nil

Gérer les erreurs relatives aux événements de mesure de la consommation

Stripe traite les événements de mesure de manière asynchrone. Si nous trouvons une erreur, nous créons l’un des événements suivants :

ÉvénementDescriptionType de charge utile
v1.billing.meter.error_report_triggeredCet événement se produit quand une mesure compte des événements d’usage non valide.thin
v1.billing.meter.no_meter_foundCet événement se produit quand des événements d’usage comptent des ID de mesure manquants ou non valide.thin

Avertissement

Pour créer une destination d’événement abonnée aux événements légers, activez Workbench dans vos paramètres de développement.

Exemples de charges utiles

Voici un exemple de charge utile pour un événement v1.billing.meter.error_report_triggered.

{
  "id": "evt_test_65R2GpwDsnmpzihMjdT16R2GDhI4SQdXJGRbvn7JA8mPEm",
  "object": "v2.core.event",
  "created": "2024-08-28T20:54:12.051Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {

Codes d’erreur

reason.error_types.code : indique la catégorie d’erreur déclenchée. Les codes d’erreur possibles sont les suivants :

  • meter_event_customer_not_found
  • meter_event_no_customer_defined
  • meter_event_dimension_count_too_high
  • archived_meter
  • timestamp_too_far_in_past
  • timestamp_in_future
  • meter_event_value_not_found
  • meter_event_invalid_value
  • no_meter (pris en charge uniquement pour le type d’événement v1.billing.meter.no_meter_found)

Écouter les événements

Vous pouvez écouter des événements en configurant un endpoint de webhook ou un autre type de destination d’événement.

  1. Dans l’onglet Webhooks de Workbench, cliquez sur Créer une destination. Vous pouvez également utiliser ce modèle pour configurer une nouvelle destination dans Workbench avec les deux types d’événements présélectionnés.

  2. Cliquez sur Afficher les options avancées, puis sélectionnez le style de charge utile Léger.

  3. Sélectionnezv1.billing.meter.error_report_triggered et v1.billing.meter.no_meter_found dans la liste des événements.

  4. Créez un gestionnaire pour traiter l’événement.

    Python
    Ruby
    PHP
    Java
    Node.js
    .NET
    No results
    import os
from stripe import StripeClient
from stripe.events import V1BillingMeterErrorReportTriggeredEvent

from flask import Flask, request, jsonify

app = Flask(__name__)
api_key = os.environ.get('STRIPE_API_KEY')
webhook_secret = os.environ.get('WEBHOOK_SECRET')

  5. Testez votre gestionnaire en configurant un écouteur local avec la CLI Stripe afin d’envoyer les événements à votre machine locale à des fins de test avant de déployer le gestionnaire en mode production. Utilisez le flag --forward-thin-to afin de spécifier l’URL vers laquelle transférer les événements thin, et le flag --thin-events pour spécifier les événements thin à transférer. Vous pouvez transférer tous les événements thin avec un astérisque (*), ou un sous-ensemble des événements thin vers votre application.

    $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*"

  6. Déclenchez des événements de test dans votre gestionnaire. Utilisez la fonction de déclenchement pour exécuter les commandes suivantes, qui simulent les événements respectifs dans votre compte à des fins de test.

    $ stripe trigger v1.billing.meter.error_report_triggered --api-key <your-secret-key>
$ stripe trigger v1.billing.meter.no_meter_found --api-key <your-secret-key>

  7. Si vous traitez des événements avec un endpoint de webhook, vérifiez les signatures de webhook pour sécuriser votre endpoint et vous assurer que toutes les requêtes proviennent de Stripe.

  8. Corrigez et renvoyez les événements non valides afin qu’ils soient traités à nouveau.

Sur cette page
Guides connexes
Modèles de tarification à l'usage