> ## 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.
# Event Ingestion
> Send usage events from your application to track customer consumption and power billing.
Events are the foundation of usage-based billing. Send events when billable actions occur, and meters aggregate them into charges.
Complete API documentation with examples and response codes.
## Event Structure
Unique identifier. Use UUIDs or combine customer ID + timestamp + action.
Dodo Payments customer ID. Must be a valid existing customer.
Event type that matches your meter's event name (case-sensitive). Examples: `api.call`, `image.generated`
ISO 8601 timestamp. Defaults to server time if omitted. Include for accurate billing with delayed/batch events.
Additional properties for aggregation and filtering:
* Numeric values: `bytes`, `tokens`, `duration_ms`
* Filters: `endpoint`, `method`, `quality`
```javascript theme={null}
metadata: {
endpoint: "/v1/orders",
method: "POST",
tokens: 1024
}
```
## Sending Events
```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"}]}'
```
Batch up to 1,000 events per request for better performance. The API enforces a hard limit of 1,000 events per call.
## Ingestion Blueprints
Ready-made event patterns for common use cases. Start with a proven blueprint instead of building from scratch.
Track AI token usage across OpenAI, Anthropic, Groq, Gemini, and more.
Meter API requests with endpoint filtering and rate limiting support.
Track file uploads and storage consumption for cloud storage services.
Measure streaming bandwidth for video, audio, and real-time data.
Bill by elapsed time for serverless functions and compute instances.
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
Define how your events are aggregated into billable quantities with filters and aggregation functions.
Use ready-made blueprints for common use cases like LLM tracking, API gateways, and storage.
Build a full AI image generator with usage-based billing from scratch.
Complete API documentation with all parameters, response codes, and interactive testing.