Event Ingestion

Events are the foundation of usage-based billing. Send events when billable actions occur, and meters aggregate them into charges.

API Reference — Events Ingestion

Komplett API-dokumentation med exempel och svarskoder.

Event Structure

Required Fields

string

obligatorisk

En unik identifierare för händelsen som används för att upptäcka duplicerade händelser vid nya försök. Härled den från åtgärden, till exempel kund-ID + åtgärd + tidsstämpel, så att en händelse som försöks igen behåller samma ID. Ett nytt slumpmässigt UUID vid varje nytt försök gör att samma händelse kan räknas två gånger.

string

obligatorisk

Dodo Payments-kundens ID. Måste vara en giltig befintlig kund.

string

obligatorisk

Händelsetypen som matchar mätarens händelsenamn (skiftlägeskänsligt). Exempel: api.call, image.generated.

Optional Fields

string

ISO 8601-tidsstämpel (UTC). Om den utelämnas används den aktuella servertiden som standard. Inkludera den för korrekt debitering vid fördröjda händelser eller batchhändelser. Tidsstämplar som är äldre än 1 timme eller mer än 5 minuter framåt i tiden avvisas.

object

Ytterligare egenskaper för aggregering och filtrering. Upp till 50 nycklar; varje nyckel kan vara upp till 100 tecken lång och varje värde upp till 500 tecken långt.

Numeriska värden: bytes, tokens, duration_ms
Filter: endpoint, method, quality

metadata: {
  endpoint: "/v1/orders",
  method: "POST",
  tokens: 1024
}

Sending Events

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

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

import os
import requests

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

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"}]}'

Bearbeta upp till 1 000 händelser per begäran för bättre prestanda. API:et tillämpar en hård gräns på 1 000 händelser per begäran.

Ingestion Blueprints

Ready-made event patterns for common use cases. Start with a proven blueprint instead of building from scratch.

LLM Blueprint

Track AI token usage across OpenAI, Anthropic, Groq, Gemini, and more.

API Gateway Blueprint

Meter API requests with endpoint filtering and rate limiting support.

Object Storage Blueprint

Track file uploads and storage consumption for cloud storage services.

Stream Blueprint

Measure streaming bandwidth for video, audio, and real-time data.

Time Range Blueprint

Bill by elapsed time for serverless functions and compute instances.

View All Blueprints

See all available blueprints with detailed implementation guides.

Best Practices

Use Unique Event IDs

Använd deterministiska ID:n för att förhindra dubbletter: ${customerId}_${action}_${timestamp}.

Implement Retries

Försök igen vid 5xx- och 429-fel med exponentiell backoff. Försök inte igen vid andra 4xx-fel.

Include Timestamps

Utelämna tidsstämplar för realtidshändelser. Inkludera dem för fördröjda händelser eller batchhändelser för bättre noggrannhet.

Monitor Delivery

Track success rates and queue failed events for retry.

Troubleshooting

Events not appearing

Händelsenamnet måste exakt matcha mätaren (skiftlägeskänsligt)
Kund-ID:t måste finnas i ditt konto
Kontrollera att mätarens filter inte exkluderar händelser
Kontrollera att tidsstämplarna är aktuella

Authentication errors (401)

Kontrollera att API-nyckeln är korrekt och använd formatet: Bearer YOUR_API_KEY.

Validation errors (400)

Säkerställ att alla obligatoriska fält finns: event_id, customer_id, event_name.

Metadata not aggregating

Metadatanycklarna måste exakt matcha mätarens “Over Property”
Använd tal, inte strängar: tokens: 150, inte tokens: "150"

Next Steps

Create Meters

Define how your events are aggregated into billable quantities with filters and aggregation functions.

Ingestion Blueprints

Use ready-made blueprints for common use cases like LLM tracking, API gateways, and storage.

Complete Tutorial

Build a full AI image generator with usage-based billing from scratch.

API Reference

Complete API documentation with all parameters, response codes, and interactive testing.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

API Reference — Events Ingestion

Event Structure

Sending Events

Ingestion Blueprints

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

Best Practices

Troubleshooting

Next Steps

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

API Reference — Events Ingestion

​Event Structure

​Sending Events

​Ingestion Blueprints

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

​Best Practices

​Troubleshooting

​Next Steps

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

Event Structure

Sending Events

Ingestion Blueprints

Best Practices

Troubleshooting

Next Steps