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

Complete API documentation with examples and response codes.

Event Structure

Required Fields

string

required

A unique identifier for the event, used to detect duplicate events on retry. Derive it from the action, for example customer ID + action + timestamp, so a retried event keeps the same ID. A fresh random UUID on each retry lets the same event be counted twice.

string

required

The Dodo Payments customer ID. Must be a valid existing customer.

string

required

The event type that matches your meter’s event name (case-sensitive). Examples: api.call, image.generated.

Optional Fields

string

ISO 8601 timestamp (UTC). Defaults to the current server time if omitted. Include for accurate billing with delayed or batch events. Timestamps older than 1 hour or more than 5 minutes in the future are rejected.

object

Additional properties for aggregation and filtering. Up to 50 keys; each key can be up to 100 characters and each value up to 500 characters.

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

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

Batch up to 1,000 events per request for better performance. The API enforces a hard limit of 1,000 events per request.

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

Use deterministic IDs to prevent duplicates: ${customerId}_${action}_${timestamp}.

Implement Retries

Retry on 5xx and 429 errors with exponential backoff. Don’t retry other 4xx errors.

Include Timestamps

Omit timestamps for real-time events. Include them for delayed or batch events for accuracy.

Monitor Delivery

Track success rates and queue failed events for retry.

Troubleshooting

Events not appearing

Event name must exactly match the meter (case-sensitive)
Customer ID must exist in your account
Check that meter filters aren’t excluding events
Verify timestamps are recent

Authentication errors (401)

Verify the API key is correct and use the format: Bearer YOUR_API_KEY.

Validation errors (400)

Ensure all required fields are present: event_id, customer_id, event_name.

Metadata not aggregating

Metadata keys must match the 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.

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