> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingestion d'événements

> Envoyez des événements d'utilisation depuis votre application pour suivre la consommation des clients et alimenter la facturation.

Les événements sont la base de la facturation basée sur l'utilisation. Envoyez des événements lorsque des actions facturables se produisent, et les compteurs les agrègent en charges.

<Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
  Documentation complète de l’API avec exemples et codes de réponse.
</Card>

## Structure de l'événement

<Accordion title="Required Fields">
  <ParamField body="event_id" type="string" required>
    Identifiant unique. Utilisez des UUID ou combinez l’ID client + l’horodatage + l’action.
  </ParamField>

  <ParamField body="customer_id" type="string" required>
    ID client Dodo Payments. Doit être un client existant valide.
  </ParamField>

  <ParamField body="event_name" type="string" required>
    Type d’événement correspondant au nom d’événement de votre compteur (respect de la casse). Exemples : `api.call`, `image.generated`
  </ParamField>
</Accordion>

<Accordion title="Optional Fields">
  <ParamField body="timestamp" type="string">
    Horodatage ISO 8601. Par défaut, heure du serveur si omis. Incluez-le pour une facturation précise avec des événements différés/en lots.
  </ParamField>

  <ParamField body="metadata" type="object">
    Propriétés supplémentaires pour l’agrégation et le filtrage :

    * Valeurs numériques : `bytes`, `tokens`, `duration_ms`
    * Filtres : `endpoint`, `method`, `quality`

    ```javascript theme={null}
    metadata: {
      endpoint: "/v1/orders",
      method: "POST",
      tokens: 1024
    }
    ```
  </ParamField>
</Accordion>

## Envoi d'événements

<CodeGroup>
  ```javascript Single Event theme={null}
  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_abc123",
        event_name: "api.call",
        metadata: { endpoint: "/v1/orders" }
      }]
    })
  });
  ```

  ```javascript Batch Events theme={null}
  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: "call_1", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_2", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_3", customer_id: "cus_abc", event_name: "api.call" }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      'https://test.dodopayments.com/events/ingest',
      headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'},
      json={'events': [{'event_id': 'call_1', 'customer_id': 'cus_abc', 'event_name': 'api.call'}]}
  )
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://test.dodopayments.com/events/ingest' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"events": [{"event_id": "call_1", "customer_id": "cus_abc", "event_name": "api.call"}]}'
  ```
</CodeGroup>

<Tip>
  Regroupez jusqu'à 1 000 événements par requête pour de meilleures performances. L'API impose une limite stricte de 1 000 événements par appel.
</Tip>

## Modèles d'ingestion

Modèles d'événements prêts à l'emploi pour des cas d'utilisation courants. Commencez avec un modèle éprouvé au lieu de construire à partir de zéro.

<CardGroup cols={2}>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Suivez l’utilisation des jetons IA pour OpenAI, Anthropic, Groq, Gemini et plus encore.
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    Mesurez les requêtes API avec filtrage par point de terminaison et prise en charge de la limitation de débit.
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    Suivez les téléchargements de fichiers et la consommation de stockage pour les services de stockage cloud.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Mesurez la bande passante de streaming pour la vidéo, l’audio et les données en temps réel.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Facturez en fonction du temps écoulé pour les fonctions serverless et les instances de calcul.
  </Card>

  <Card title="View All Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Consultez tous les plans disponibles avec des guides d’implémentation détaillés.
  </Card>
</CardGroup>

## Meilleures pratiques

<AccordionGroup>
  <Accordion title="Use Unique Event IDs">
    Utilisez des identifiants déterministes pour éviter les doublons : `${customerId}_${action}_${timestamp}`
  </Accordion>

  <Accordion title="Implement Retries">
    Réessayez en cas d’erreurs 5xx avec un backoff exponentiel. Ne réessayez pas les erreurs 4xx.
  </Accordion>

  <Accordion title="Include Timestamps">
    Omettre pour les événements en temps réel. Inclure pour les événements différés/en lots pour plus de précision.
  </Accordion>

  <Accordion title="Monitor Delivery">
    Suivez les taux de réussite et mettez en file d’attente les événements échoués pour une nouvelle tentative.
  </Accordion>
</AccordionGroup>

## Dépannage

<AccordionGroup>
  <Accordion title="Events not appearing">
    * Le nom de l’événement doit correspondre exactement au compteur (respect de la casse)
    * L’ID client doit exister
    * Vérifiez que les filtres du compteur n’excluent pas les événements
    * Vérifiez que les horodatages sont récents
  </Accordion>

  <Accordion title="Authentication errors (401)">
    Vérifiez que la clé API est correcte et utilisez le format : `Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Validation errors (400)">
    Assurez-vous que tous les champs obligatoires sont présents : `event_id`, `customer_id`, `event_name`
  </Accordion>

  <Accordion title="Metadata not aggregating">
    * Les clés de métadonnées doivent correspondre exactement à la « Propriété sur » du compteur
    * Utilisez des nombres, pas des chaînes : `tokens: 150` et non `tokens: "150"`
  </Accordion>
</AccordionGroup>

## Prochaines étapes

<CardGroup cols={2}>
  <Card title="Create Meters" icon="sliders" href="/features/usage-based-billing/meters">
    Définissez comment vos événements sont agrégés en quantités facturables avec des filtres et des fonctions d’agrégation.
  </Card>

  <Card title="Ingestion Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Utilisez des plans prêts à l’emploi pour des cas d’usage courants comme le suivi de LLM, les passerelles API et le stockage.
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Construisez un générateur d’images IA complet avec facturation basée sur l’utilisation à partir de zéro.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/usage-events/ingest-events">
    Documentation complète de l’API avec tous les paramètres, codes de réponse et tests interactifs.
  </Card>
</CardGroup>