Skip to main content

API Reference - Events Ingestion

사용량 이벤트를 수집하기 위한 전체 API 문서를 확인하고 이벤트 수집 요청과 응답을 대화형으로 테스트하세요.

API Reference - Meters Creation

미터 생성에 대한 전체 API 문서를 확인하고 미터 생성 요청과 응답을 대화형으로 테스트하세요.

미터 생성

미터는 결제를 위해 사용량 이벤트를 집계하고 측정하는 방식을 정의합니다. 미터를 생성하기 전에 사용량 추적 전략을 계획하세요:
  • 추적할 사용량 이벤트를 식별합니다
  • 이벤트를 집계할 방식을 결정합니다(개수, 합계 등)
  • 특정 사용 사례에 필요한 필터링 요구 사항을 정의합니다

단계별 미터 생성

다음 종합 가이드에 따라 사용량 미터를 설정하세요:
1

Configure Basic Information

미터의 기본 정보를 설정합니다.
string
필수
이 미터가 추적하는 대상을 식별할 수 있도록 명확하고 설명적인 이름을 선택합니다.예: “토큰”, “API Calls”, “Storage Usage”, “Compute Hours”
string
이 미터가 측정하는 항목을 자세히 설명합니다.예: “고객이 보낸 각 POST /v1/orders 요청을 계산합니다”
string
필수
이 미터를 트리거할 이벤트 식별자를 지정합니다.예: “token”, “api.call”, “storage.usage”, “compute.session”
이벤트 이름은 사용량 이벤트로 전송하는 값과 정확히 일치해야 합니다. 이벤트 이름은 대소문자를 구분합니다.
2

Configure Aggregation Settings

미터가 이벤트에서 사용량을 계산하는 방식을 정의합니다.
string
필수
이벤트를 집계할 방식을 선택합니다:
수신한 이벤트 수를 단순히 계산합니다.사용 사례: API calls, page views, file uploads계산: 총 이벤트 수
string
집계할 이벤트 메타데이터의 속성 이름입니다.
Sum, Max 또는 Last 집계 유형을 사용할 때 이 필드는 필수입니다.
string
필수
보고서와 결제 화면에 표시할 단위 레이블을 정의합니다.예: “calls”, “GB”, “hours”, “tokens”
3

Configure Event Filtering (Optional)

미터에 포함할 이벤트를 제어하는 기준을 설정합니다.
이벤트 필터링을 사용하면 사용량 계산에 반영할 이벤트를 결정하는 정교한 규칙을 만들 수 있습니다. 테스트 이벤트를 제외하거나, 사용자 등급별로 필터링하거나, 특정 작업에 집중할 때 유용합니다.
이벤트 필터링 활성화조건부 이벤트 처리를 활성화하려면 Enable Event Filtering을 전환합니다.필터 로직 선택여러 조건을 평가할 방식을 선택합니다:
이벤트가 계산되려면 모든 조건이 true여야 합니다. 여러 엄격한 기준을 동시에 충족하는 이벤트가 필요한 경우 사용합니다.예: user_tier = "premium" AND endpoint = "/api/v2/users"인 API calls 계산
필터 조건 설정
1

Add Condition

새 필터 규칙을 만들려면 Add condition을 클릭합니다.
2

Configure Property Key

이벤트 메타데이터의 속성 이름을 지정합니다.
3

Select Comparator

사용 가능한 연산자 중에서 선택합니다:
  • equals - 정확히 일치
  • not_equals - 제외 필터
  • greater_than - 숫자 비교
  • greater_than_or_equals - 숫자 비교(포함)
  • less_than - 숫자 비교
  • less_than_or_equals - 숫자 비교(포함)
  • contains - 문자열에 하위 문자열 포함
  • does_not_contain - 문자열 제외 필터
4

Set Comparison Value

비교할 대상 값을 설정합니다.
5

Add Groups

복잡한 로직을 위해 추가 조건 그룹을 만들려면 Add Group을 사용합니다.
조건이 정상적으로 작동하려면 필터링된 속성이 이벤트 메타데이터에 포함되어야 합니다. 필수 속성이 없는 이벤트는 계산에서 제외됩니다.
4

Create Meter

미터 구성을 검토하고 Create Meter를 클릭합니다.
이제 미터가 사용량 이벤트를 수신하고 집계할 준비가 되었습니다.

제품에 미터 연결

미터를 생성한 후에는 사용량 기반 결제를 활성화하기 위해 제품에 연결해야 합니다. 이 과정에서 미터의 사용량 데이터가 고객 결제를 위한 가격 규칙과 연결됩니다. 미터를 제품에 연결하면 사용량 추적과 결제가 연동됩니다:
  • 제품은 가격 규칙과 결제 동작을 정의합니다
  • 미터는 결제 계산에 사용할 사용량 데이터를 제공합니다
  • 복잡한 결제 시나리오에서는 여러 미터를 하나의 제품에 연결할 수 있습니다

제품 구성 과정

제품 설정을 올바르게 구성하여 사용량 데이터를 청구 가능한 요금으로 변환하세요:
1

Choose Usage-Based Billing Product Type

제품 생성 또는 편집 페이지로 이동하여 제품 유형으로 Usage-Based를 선택합니다.
2

Select Associated Meter

측면에서 미터 선택 패널을 열려면 Associated Meter를 클릭합니다.이 패널에서 이 제품의 사용량을 추적할 미터를 구성할 수 있습니다.
3

Add Your Meter

미터 선택 패널에서 다음을 수행합니다:
  1. 사용 가능한 미터를 보려면 Add Meters를 클릭합니다
  2. 드롭다운 목록에서 생성한 미터를 선택합니다
  3. 선택한 미터가 제품 구성에 표시됩니다
4

Configure Price Per Unit

미터가 추적하는 각 사용량 단위의 가격을 설정합니다.
number
필수
미터가 측정하는 각 단위에 부과할 금액을 정의합니다.: 단위당 $0.50로 설정하면 다음과 같습니다:
  • 1,000 units consumed = 1,000 × $0.50 = 500.00 charged
  • 500 units consumed = 500 × $0.50 = 250.00 charged
  • 100 units consumed = 100 × $0.50 = 50.00 charged
5

Set Free Threshold (Optional)

결제가 시작되기 전에 무료 사용 한도를 설정합니다.
number
유료 사용량 계산이 시작되기 전에 고객이 무료로 사용할 수 있는 단위 수입니다.작동 방식:
  • 무료 임계값: 100 units
  • 단위당 가격: $0.50
  • 고객 사용량: 250 units
  • 계산: (250 - 100) × 0.50=0.50 = **75.00** charged
무료 임계값은 프리미엄 모델, 체험 기간 또는 플랜에 포함된 기본 한도를 고객에게 제공할 때 적합합니다.
무료 임계값은 각 결제 주기에 적용되므로 고객은 매월 또는 설정한 결제 일정에 따라 새로운 무료 한도를 받습니다.
6

Save Configuration

미터와 가격 구성을 검토한 다음 Save Changes를 클릭하여 설정을 완료합니다.
이제 제품이 사용량 기반 결제에 맞게 구성되었으며 측정된 사용량에 따라 고객에게 자동으로 요금이 청구됩니다.
다음 단계:
  • 미터로 전송된 사용량 이벤트가 추적되고 집계됩니다
  • 결제 계산에 가격 규칙이 자동으로 적용됩니다
  • 각 결제 주기 동안 실제 사용량을 기준으로 고객에게 요금이 청구됩니다
제품당 최대 10개의 미터를 추가할 수 있습니다. 이를 통해 API calls, 스토리지, 컴퓨팅 시간 및 사용자 지정 지표와 같은 여러 차원에서 정교하게 사용량을 추적할 수 있습니다.

사용량 이벤트 전송

미터를 구성한 후 애플리케이션에서 사용량 이벤트를 전송하여 고객 사용량을 추적할 수 있습니다.

이벤트 구조

각 사용량 이벤트에는 다음 필수 필드가 포함되어야 합니다:
string
필수
이 특정 이벤트의 고유 식별자입니다. 모든 이벤트에서 고유해야 합니다.
string
필수
이 사용량을 귀속할 Dodo Payments customer ID입니다.
string
필수
미터 구성과 일치하는 이벤트 이름입니다. 이벤트 이름이 적절한 미터를 트리거합니다.
string
이벤트가 발생한 시점의 ISO 8601 timestamp입니다. 제공하지 않으면 현재 시간으로 설정됩니다.
object
필터링과 집계를 위한 추가 속성입니다. 미터의 “Over Property” 또는 필터링 조건에서 참조하는 값을 포함하세요.

사용량 이벤트 API 예시

Events API를 사용하여 구성된 미터로 사용량 이벤트를 전송합니다:

안정적인 수집을 위해 알아야 할 핵심 사항

프로덕션 환경에서 사용량 추적을 정확하고 복원력 있게 유지하려면 다음 방식을 따르세요.
결정적이고 멱등적인 event_id를 사용하세요. event_id는 모든 이벤트에서 고유해야 하며 멱등성 키로 사용됩니다. 재사용된 event_id는 중복으로 처리되어 다시 집계되지 않으므로 재시도로 인해 이중 청구가 발생하지 않습니다. 임의의 값 대신 작업에서 ID를 도출하세요. 예: `${customer_id}_${action}_${timestamp}`.
요청당 최대 1,000개의 이벤트를 배치로 전송하세요. /events/ingest 엔드포인트는 호출당 최대 1,000개의 이벤트라는 엄격한 제한을 적용합니다. 이보다 큰 배치는 거부되므로 많은 양의 이벤트는 여러 호출로 나누세요. 대규모 워크로드에서는 이벤트마다 하나의 요청을 보내기보다 이벤트를 버퍼링한 후 배치로 플러시하세요.
5xx429는 재시도하고, 4xx는 절대 재시도하지 마세요. 서버 오류(5xx)와 속도 제한(429)이 발생하면 지수 백오프를 적용해 재시도하세요. 유효성 검사 오류인 400/422재시도하지 마세요. 페이로드 형식이 잘못되어 매번 실패하므로 수정한 후 다시 전송해야 합니다. 재시도 후에도 계속 실패하는 이벤트는 대기열에 추가하여 누락되지 않도록 하세요.
타임스탬프를 신중하게 설정하세요. 실시간 이벤트에서는 timestamp를 생략하면 수집 시간으로 기본 설정됩니다. 백필하거나 지연된 이벤트 또는 배치 이벤트를 전송할 때는 이를 명시적으로 설정하세요(ISO 8601). 그러면 사용량이 올바른 청구 기간에 반영됩니다.
집계되는 메타데이터는 문자열이 아닌 숫자로 전송하세요. 미터의 Over Property(Sum, Max, Last)에서 참조하는 모든 속성은 숫자 타입이어야 합니다. { "tokens": 150 }가 올바른 예이며 { "tokens": "150" }는 올바르지 않습니다. 문자열 값은 집계되지 않습니다.

사용량 기반 청구 분석

종합 분석 대시보드에서 사용량 기반 청구 데이터를 모니터링하고 분석하세요. 고객 소비 패턴, 미터 성능 및 청구 추세를 추적하여 가격 전략을 최적화하고 사용 행태를 파악할 수 있습니다.

개요 분석

개요 탭에서는 사용량 기반 청구 성과를 종합적으로 확인할 수 있습니다.

활동 지표

다양한 기간에 걸쳐 주요 사용량 통계를 추적하세요.
metric
현재 청구 기간의 사용량 활동을 보여 주므로 월별 소비 패턴을 파악하는 데 도움이 됩니다.
metric
추적을 시작한 이후의 누적 사용량 통계를 표시하여 장기적인 성장 추세를 파악할 수 있습니다.
기간 선택기를 사용하여 여러 달의 사용량을 비교하고 계절적 추세나 성장 패턴을 파악하세요.

미터 수량 차트

시간에 따른 사용량 추세를 보라색 그라데이션으로 표시하는 미터 수량 차트
미터 수량 차트는 다음 기능을 통해 시간에 따른 사용량 추세를 시각화합니다.
  • 시계열 시각화: 일, 주 또는 월별 사용량 패턴 추적
  • 여러 미터 지원: 서로 다른 미터의 데이터를 동시에 확인
  • 추세 분석: 사용량 급증, 패턴 및 성장 궤적 파악
차트는 사용량과 선택한 기간에 따라 자동으로 크기가 조정되므로 작은 변동과 주요 사용량 변화 모두를 명확하게 확인할 수 있습니다.

이벤트 분석

상세한 이벤트 분석을 위해 이벤트 이름, ID 및 페이지 매김 컨트롤을 표시하는 이벤트 테이블
이벤트 탭에서는 개별 사용량 이벤트를 세부적으로 확인할 수 있습니다.

이벤트 정보 표시

이벤트 테이블에서는 다음 열을 통해 개별 사용량 이벤트를 명확하게 확인할 수 있습니다.
  • 이벤트 이름: 사용량 이벤트를 생성한 특정 작업 또는 트리거
  • 이벤트 ID: 각 이벤트 인스턴스의 고유 식별자
  • 고객 ID: 이벤트와 연결된 고객
  • 타임스탬프: 이벤트가 발생한 시점
이 보기를 사용하면 고객 기반 전반의 개별 사용량 이벤트를 추적하고 모니터링하여 청구 계산 및 사용량 패턴을 투명하게 파악할 수 있습니다.

고객 분석

고객 탭에서는 다음 정보를 포함한 고객 사용량 데이터의 상세 테이블 보기를 제공합니다.

사용 가능한 데이터 열

string
식별을 위한 고객의 이메일 주소입니다.
string
고객 구독의 고유 식별자입니다.
number
요금이 부과되기 전에 고객의 플랜에 포함된 무료 단위 수입니다.
currency
무료 기준을 초과한 사용량에 대한 단위당 비용입니다.
timestamp
고객의 가장 최근 사용량 이벤트 타임스탬프입니다.
currency
사용량 기반 청구로 고객에게 청구된 총 금액입니다.
number
고객이 소비한 총 단위 수입니다.
number
무료 기준을 초과하여 요금이 부과되는 단위 수입니다.

테이블 기능

  • 열 필터링: “Edit Columns” 기능을 사용하여 특정 데이터 열을 표시하거나 숨깁니다.
  • 실시간 업데이트: 사용량 데이터에는 가장 최신의 소비 지표가 반영됩니다.

집계 예시

다음은 다양한 집계 유형이 작동하는 방식에 대한 실제 예시입니다.

집계 유형 이해하기

집계 유형마다 적합한 청구 시나리오가 다릅니다. 사용량을 측정하고 요금을 부과하려는 방식에 따라 적절한 유형을 선택하세요.

실제 구현 예시

다음 예시는 샘플 이벤트와 예상 결과를 통해 각 집계 유형의 실제 활용 사례를 보여 줍니다.
시나리오: 총 API 요청 수 추적미터 구성:
  • 이벤트 이름: api.call
  • 집계 유형: Count
  • 측정 단위: calls
샘플 이벤트:
결과: 고객에게 3회의 호출이 청구됨
시나리오: 전송된 총 바이트를 기준으로 청구미터 구성:
  • 이벤트 이름: data.transfer
  • 집계 유형: Sum
  • Over Property: bytes
  • 측정 단위: GB
샘플 이벤트:
결과: 총 1.5GB 전송량이 고객에게 청구됨
시나리오: 동시 사용자 수의 최댓값을 기준으로 청구미터 구성:
  • 이벤트 이름: concurrent.users
  • 집계 유형: Max
  • Over Property: count
  • 측정 단위: users
샘플 이벤트:
결과: 최대 동시 사용자 23명이 고객에게 청구됨

이벤트 필터링 예시

특정 엔드포인트에 대한 API 호출만 집계:필터 구성:
  • 속성: endpoint
  • 비교 연산자: equals
  • 값: /v1/orders
샘플 이벤트:
결과: 필터 기준과 일치하는 이벤트가 집계됩니다. 다른 엔드포인트의 이벤트는 무시됩니다.

문제 해결

사용량 기반 청구 구현에서 발생하는 일반적인 문제를 해결하고 정확한 추적 및 청구를 보장하세요.

일반적인 문제

대부분의 사용량 기반 청구 문제는 다음 범주에 해당합니다.
  • 이벤트 전달 및 처리 문제
  • 미터 구성 문제
  • 데이터 타입 및 형식 오류
  • 고객 ID 및 인증 문제

디버깅 단계

사용량 기반 청구 문제를 해결할 때는 다음을 수행하세요.
  1. 이벤트 분석 탭에서 이벤트 전달을 확인합니다.
  2. 미터 구성이 이벤트 구조와 일치하는지 확인합니다.
  3. 고객 ID와 API 인증을 검증합니다.
  4. 필터링 조건과 집계 설정을 검토합니다.

해결 방법 및 수정 사항

일반적인 원인:
  • 이벤트 이름이 미터 구성과 정확히 일치하지 않음
  • 이벤트 필터링 조건이 이벤트를 제외함
  • 고객 ID가 Dodo Payments 계정에 존재하지 않음
  • 이벤트 타임스탬프가 현재 청구 기간을 벗어남
해결 방법:
  • 이벤트 이름의 철자와 대소문자를 확인합니다.
  • 필터링 조건을 검토하고 테스트합니다.
  • 고객 ID가 유효하고 활성 상태인지 확인합니다.
  • 이벤트 타임스탬프가 최근 시점이며 올바른 형식인지 확인합니다.
일반적인 원인:
  • Over Property 이름이 이벤트 메타데이터 키와 일치하지 않음
  • 메타데이터 값의 데이터 타입이 잘못됨(문자열과 숫자 간 불일치)
  • 필수 메타데이터 속성이 누락됨
해결 방법:
  • 메타데이터 키가 Over Property 설정과 정확히 일치하는지 확인합니다.
  • 이벤트에서 문자열 숫자를 실제 숫자로 변환합니다.
  • 모든 이벤트에 필요한 속성을 포함합니다.
일반적인 원인:
  • 필터 속성 이름이 이벤트 메타데이터와 일치하지 않음
  • 데이터 타입에 적합하지 않은 비교 연산자 사용(문자열과 숫자 간 불일치)
  • 문자열 비교에서 대소문자를 구분함
해결 방법:
  • 속성 이름이 정확히 일치하는지 다시 확인합니다.
  • 데이터 타입에 적합한 비교 연산자를 사용합니다.
  • 문자열을 필터링할 때 대소문자 구분 여부를 고려합니다.

관련 API Reference

Create Meter

고객 소비량 추적을 위한 사용량 미터 생성 및 구성 API reference

Ingest Usage Events

청구 계산을 위해 구성된 미터로 사용량 이벤트를 전송하는 API reference
마지막 수정일 2026년 7월 31일