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

Dokumentasi API lengkap dengan contoh dan kode respons.

Event Structure

Required Fields

string

wajib

Pengenal unik untuk event, digunakan untuk mendeteksi event duplikat saat melakukan retry. Turunkan ID ini dari tindakan yang dilakukan, misalnya customer ID + tindakan + timestamp, sehingga event yang di-retry tetap memiliki ID yang sama. UUID acak baru pada setiap retry dapat menyebabkan event yang sama dihitung dua kali.

string

wajib

Customer ID Dodo Payments. Harus merupakan customer yang valid dan sudah ada.

string

wajib

Jenis event yang cocok dengan nama event meter Anda (peka huruf besar-kecil). Contoh: api.call, image.generated.

Optional Fields

string

Timestamp ISO 8601 (UTC). Jika tidak disertakan, nilainya secara default adalah waktu server saat ini. Sertakan untuk penagihan yang akurat pada event yang tertunda atau batch. Timestamp yang lebih lama dari 1 jam atau lebih dari 5 menit di masa mendatang akan ditolak.

object

Properti tambahan untuk agregasi dan pemfilteran. Hingga 50 kunci; setiap kunci dapat memiliki panjang hingga 100 karakter dan setiap nilai hingga 500 karakter.

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

Kelompokkan hingga 1.000 event dalam setiap request untuk performa yang lebih baik. API memberlakukan batas tetap sebanyak 1.000 event 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

Gunakan ID deterministik untuk mencegah duplikasi: ${customerId}_${action}_${timestamp}.

Implement Retries

Lakukan retry pada error 5xx dan 429 dengan exponential backoff. Jangan melakukan retry pada error 4xx lainnya.

Include Timestamps

Jangan sertakan timestamp untuk event real-time. Sertakan timestamp untuk event yang tertunda atau batch agar akurat.

Monitor Delivery

Track success rates and queue failed events for retry.

Troubleshooting

Events not appearing

Nama event harus sama persis dengan meter (peka huruf besar-kecil)
Customer ID harus ada di akun Anda
Periksa apakah filter meter tidak mengecualikan event
Pastikan timestamp masih baru

Authentication errors (401)

Pastikan API key sudah benar dan gunakan format: Bearer YOUR_API_KEY.

Validation errors (400)

Pastikan semua field yang wajib sudah ada: event_id, customer_id, event_name.

Metadata not aggregating

Key metadata harus sama persis dengan “Over Property” pada meter
Gunakan angka, bukan string: tokens: 150 bukan 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