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

API Reference - Events Ingestion

예시와 응답 코드를 포함한 전체 API 문서.

​
이벤트 구조

​
event_id
string
필수
고유 식별자입니다. UUID를 사용하거나 고객 ID + 타임스탬프 + 작업을 조합하세요.
​
customer_id
string
필수
Dodo Payments 고객 ID입니다. 기존의 유효한 고객이어야 합니다.
​
event_name
string
필수
메터의 이벤트 이름(대소문자 구분)과 일치하는 이벤트 유형입니다. 예시: api.call, image.generated
​
timestamp
string
ISO 8601 타임스탬프입니다. 생략하면 서버 시간이 기본값으로 사용됩니다. 지연/배치 이벤트의 정확한 청구를 위해 포함하세요.
​
metadata
object
집계 및 필터링을 위한 추가 속성:
  • 숫자 값: 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" }
    }]
  })
});
성능 향상을 위해 요청당 최대 100개 이벤트를 배치 처리하세요.

​
수집 청사진

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

LLM Blueprint

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

API Gateway Blueprint

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

Object Storage Blueprint

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

Stream Blueprint

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

Time Range Blueprint

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

View All Blueprints

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

​
모범 사례

중복을 방지하려면 결정론적 ID를 사용하세요: ${customerId}_${action}_${timestamp}
5xx 오류에는 지수 백오프를 사용해 재시도하세요. 4xx 오류는 재시도하지 마세요.
실시간 이벤트에는 생략하세요. 정확성을 위해 지연/배치 이벤트에는 포함하세요.
성공률을 추적하고 실패한 이벤트를 재시도 대기열에 추가하세요.

​
문제 해결

  • 이벤트 이름은 메터와 정확히 일치해야 합니다(대소문자 구분)
  • 고객 ID가 존재해야 합니다
  • 메터 필터가 이벤트를 제외하지 않는지 확인하세요
  • 타임스탬프가 최신인지 검증하세요
API 키가 정확한지 확인하고 형식을 사용하세요: Bearer YOUR_API_KEY
필수 필드가 모두 있는지 확인하세요: event_id, customer_id, event_name
  • 메타데이터 키는 메터의 “Over Property”와 정확히 일치해야 합니다
  • 문자열이 아닌 숫자를 사용하세요: tokens: 150, tokens: "150" 대신

​
다음 단계

Create Meters

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

Ingestion Blueprints

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

Complete Tutorial

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

API Reference

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