이벤트 수집

이벤트는 사용 기반 청구의 기초입니다. 청구 가능한 작업이 발생할 때 이벤트를 전송하고, 미터가 이를 집계하여 요금으로 변환합니다.

API Reference — Events Ingestion

예시와 응답 코드를 포함한 완전한 API 문서입니다.

이벤트 구조

Required Fields

string

필수

재시도 시 중복 이벤트를 감지하는 데 사용되는 이벤트의 고유 식별자입니다. 작업을 기반으로 생성하세요. 예를 들어 customer ID + 작업 + 타임스탬프를 사용하면 재시도된 이벤트가 동일한 ID를 유지합니다. 재시도할 때마다 새로운 무작위 UUID를 생성하면 동일한 이벤트가 두 번 집계됩니다.

string

필수

Dodo Payments customer ID입니다. 유효한 기존 customer여야 합니다.

string

필수

meter의 event name과 일치하는 이벤트 유형입니다(대소문자 구분). 예: api.call, image.generated.

Optional Fields

string

ISO 8601 타임스탬프(UTC)입니다. 생략하면 현재 서버 시간으로 설정됩니다. 지연 이벤트 또는 batch 이벤트의 정확한 billing을 위해 포함하세요. 1시간보다 오래된 타임스탬프 또는 현재 시간보다 5분 넘게 미래인 타임스탬프는 거부됩니다.

object

집계 및 필터링을 위한 추가 속성입니다. 최대 50개의 키를 사용할 수 있으며, 각 키는 최대 100자, 각 값은 최대 500자까지 사용할 수 있습니다.

숫자 값: bytes, tokens, duration_ms
필터: endpoint, method, quality

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

이벤트 전송

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

성능 향상을 위해 요청당 최대 1,000개의 이벤트를 batch 처리할 수 있습니다. API는 요청당 1,000개의 이벤트라는 하드 리밋을 적용합니다.

수집 청사진

일반적인 사용 사례를 위한 준비된 이벤트 패턴입니다. 처음부터 구축하는 대신 검증된 청사진으로 시작하세요.

LLM Blueprint

OpenAI, Anthropic, Groq, Gemini 등 전반의 AI 토큰 사용량을 추적하세요.

API Gateway Blueprint

엔드포인트 필터링 및 속도 제한 지원과 함께 API 요청을 계량하세요.

Object Storage Blueprint

클라우드 스토리지 서비스의 파일 업로드 및 저장소 사용량을 추적하세요.

Stream Blueprint

비디오, 오디오 및 실시간 데이터의 스트리밍 대역폭을 측정하세요.

Time Range Blueprint

서버리스 함수 및 컴퓨트 인스턴스에 대해 경과 시간 기준으로 청구하세요.

View All Blueprints

상세 구현 가이드가 포함된 모든 사용 가능한 청사진을 확인하세요.

모범 사례

Use Unique Event IDs

중복을 방지하려면 결정론적 ID를 사용하세요: ${customerId}_${action}_${timestamp}.

Implement Retries

지수 백오프를 사용하여 5xx 및 429 오류 발생 시 재시도하세요. 다른 4xx 오류는 재시도하지 마세요.

Include Timestamps

실시간 이벤트에서는 타임스탬프를 생략하세요. 정확성을 위해 지연 이벤트 또는 batch 이벤트에는 타임스탬프를 포함하세요.

Monitor Delivery

성공률을 추적하고 실패한 이벤트를 재시도 대기열에 추가하세요.

문제 해결

Events not appearing

이벤트 이름은 meter와 정확히 일치해야 합니다(대소문자 구분)
Customer ID가 계정에 존재해야 합니다
meter 필터가 이벤트를 제외하고 있지 않은지 확인하세요
타임스탬프가 최근 값인지 확인하세요

Authentication errors (401)

API key가 올바른지 확인하고 다음 형식을 사용하세요: Bearer YOUR_API_KEY.

Validation errors (400)

필수 필드가 모두 포함되어 있는지 확인하세요: event_id, customer_id, event_name.

Metadata not aggregating

Metadata 키는 meter의 “Over Property”와 정확히 일치해야 합니다
문자열이 아닌 숫자를 사용하세요: tokens: 150, tokens: "150"가 아님

다음 단계

Create Meters

필터 및 집계 함수로 이벤트가 청구 대상 수량으로 어떻게 집계되는지 정의하세요.

Ingestion Blueprints

LLM 추적, API 게이트웨이, 저장소 같은 일반적인 사용 사례에 대해 준비된 청사진을 사용하세요.

Complete Tutorial

사용량 기반 청구를 포함한 전체 AI 이미지 생성기를 처음부터 구축하세요.

API Reference

모든 매개변수, 응답 코드 및 상호 작용 테스트가 포함된 전체 API 문서를 확인하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

API Reference — Events Ingestion

이벤트 구조

이벤트 전송

수집 청사진

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

모범 사례

문제 해결

다음 단계

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

API Reference — Events Ingestion

​이벤트 구조

​이벤트 전송

​수집 청사진

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

​모범 사례

​문제 해결

​다음 단계

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

이벤트 구조

이벤트 전송

수집 청사진

모범 사례

문제 해결

다음 단계