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

API Reference - Events Ingestion

Complete API documentation with examples and response codes.

​
Event Structure

​
event_id
string
required
Unique identifier. Use UUIDs or combine customer ID + timestamp + action.
​
customer_id
string
required
Dodo Payments customer ID. Must be a valid existing customer.
​
event_name
string
required
Event type that matches your meter’s event name (case-sensitive). Examples: api.call, image.generated
​
timestamp
string
ISO 8601 timestamp. Defaults to server time if omitted. Include for accurate billing with delayed/batch events.
​
metadata
object
Additional properties for aggregation and filtering:
  • Numeric values: bytes, tokens, duration_ms
  • Filters: 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" }
    }]
  })
});
Batch up to 100 events per request for better performance.

​
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 deterministic IDs to prevent duplicates: ${customerId}_${action}_${timestamp}
Retry on 5xx errors with exponential backoff. Don’t retry 4xx errors.
Omit for real-time events. Include for delayed/batch events for accuracy.
Track success rates and queue failed events for retry.

​
Troubleshooting

  • Event name must exactly match meter (case-sensitive)
  • Customer ID must exist
  • Check meter filters aren’t excluding events
  • Verify timestamps are recent
Verify API key is correct and use format: Bearer YOUR_API_KEY
Ensure all required fields are present: event_id, customer_id, event_name
  • Metadata keys must match meter’s “Over Property” exactly
  • Use numbers, not strings: tokens: 150 not 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.