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
3
Configure Event Filtering (Optional)
미터에 포함할 이벤트를 제어하는 기준을 설정합니다.이벤트 필터링 활성화조건부 이벤트 처리를 활성화하려면 Enable Event Filtering을 전환합니다.필터 로직 선택여러 조건을 평가할 방식을 선택합니다:필터 조건 설정
이벤트 필터링을 사용하면 사용량 계산에 반영할 이벤트를 결정하는 정교한 규칙을 만들 수 있습니다. 테스트 이벤트를 제외하거나, 사용자 등급별로 필터링하거나, 특정 작업에 집중할 때 유용합니다.
- AND Logic
- OR Logic
이벤트가 계산되려면 모든 조건이 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
미터 선택 패널에서 다음을 수행합니다:
- 사용 가능한 미터를 보려면 Add Meters를 클릭합니다
- 드롭다운 목록에서 생성한 미터를 선택합니다
- 선택한 미터가 제품 구성에 표시됩니다
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) × 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를 사용하여 구성된 미터로 사용량 이벤트를 전송합니다:안정적인 수집을 위해 알아야 할 핵심 사항
프로덕션 환경에서 사용량 추적을 정확하고 복원력 있게 유지하려면 다음 방식을 따르세요.타임스탬프를 신중하게 설정하세요. 실시간 이벤트에서는
timestamp를 생략하면 수집 시간으로 기본 설정됩니다. 백필하거나 지연된 이벤트 또는 배치 이벤트를 전송할 때는 이를 명시적으로 설정하세요(ISO 8601). 그러면 사용량이 올바른 청구 기간에 반영됩니다.사용량 기반 청구 분석
종합 분석 대시보드에서 사용량 기반 청구 데이터를 모니터링하고 분석하세요. 고객 소비 패턴, 미터 성능 및 청구 추세를 추적하여 가격 전략을 최적화하고 사용 행태를 파악할 수 있습니다.개요 분석
개요 탭에서는 사용량 기반 청구 성과를 종합적으로 확인할 수 있습니다.활동 지표
다양한 기간에 걸쳐 주요 사용량 통계를 추적하세요.metric
현재 청구 기간의 사용량 활동을 보여 주므로 월별 소비 패턴을 파악하는 데 도움이 됩니다.
metric
추적을 시작한 이후의 누적 사용량 통계를 표시하여 장기적인 성장 추세를 파악할 수 있습니다.
미터 수량 차트

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

이벤트 정보 표시
이벤트 테이블에서는 다음 열을 통해 개별 사용량 이벤트를 명확하게 확인할 수 있습니다.- 이벤트 이름: 사용량 이벤트를 생성한 특정 작업 또는 트리거
- 이벤트 ID: 각 이벤트 인스턴스의 고유 식별자
- 고객 ID: 이벤트와 연결된 고객
- 타임스탬프: 이벤트가 발생한 시점
이 보기를 사용하면 고객 기반 전반의 개별 사용량 이벤트를 추적하고 모니터링하여 청구 계산 및 사용량 패턴을 투명하게 파악할 수 있습니다.
고객 분석
고객 탭에서는 다음 정보를 포함한 고객 사용량 데이터의 상세 테이블 보기를 제공합니다.사용 가능한 데이터 열
string
식별을 위한 고객의 이메일 주소입니다.
string
고객 구독의 고유 식별자입니다.
number
요금이 부과되기 전에 고객의 플랜에 포함된 무료 단위 수입니다.
currency
무료 기준을 초과한 사용량에 대한 단위당 비용입니다.
timestamp
고객의 가장 최근 사용량 이벤트 타임스탬프입니다.
currency
사용량 기반 청구로 고객에게 청구된 총 금액입니다.
number
고객이 소비한 총 단위 수입니다.
number
무료 기준을 초과하여 요금이 부과되는 단위 수입니다.
테이블 기능
- 열 필터링: “Edit Columns” 기능을 사용하여 특정 데이터 열을 표시하거나 숨깁니다.
- 실시간 업데이트: 사용량 데이터에는 가장 최신의 소비 지표가 반영됩니다.
집계 예시
다음은 다양한 집계 유형이 작동하는 방식에 대한 실제 예시입니다.집계 유형 이해하기
집계 유형마다 적합한 청구 시나리오가 다릅니다. 사용량을 측정하고 요금을 부과하려는 방식에 따라 적절한 유형을 선택하세요.실제 구현 예시
다음 예시는 샘플 이벤트와 예상 결과를 통해 각 집계 유형의 실제 활용 사례를 보여 줍니다.Count Aggregation - API Calls
Count Aggregation - API Calls
시나리오: 총 API 요청 수 추적미터 구성:결과: 고객에게 3회의 호출이 청구됨
- 이벤트 이름:
api.call - 집계 유형: Count
- 측정 단위:
calls
Sum Aggregation - Data Transfer
Sum Aggregation - Data Transfer
시나리오: 전송된 총 바이트를 기준으로 청구미터 구성:결과: 총 1.5GB 전송량이 고객에게 청구됨
- 이벤트 이름:
data.transfer - 집계 유형: Sum
- Over Property:
bytes - 측정 단위:
GB
Max Aggregation - Peak Concurrent Users
Max Aggregation - Peak Concurrent Users
시나리오: 동시 사용자 수의 최댓값을 기준으로 청구미터 구성:결과: 최대 동시 사용자 23명이 고객에게 청구됨
- 이벤트 이름:
concurrent.users - 집계 유형: Max
- Over Property:
count - 측정 단위:
users
이벤트 필터링 예시
- Filter by API Endpoint
- Filter by Value Range
- Complex Multi-Condition Filters
특정 엔드포인트에 대한 API 호출만 집계:필터 구성:결과: 필터 기준과 일치하는 이벤트가 집계됩니다. 다른 엔드포인트의 이벤트는 무시됩니다.
- 속성:
endpoint - 비교 연산자:
equals - 값:
/v1/orders
문제 해결
사용량 기반 청구 구현에서 발생하는 일반적인 문제를 해결하고 정확한 추적 및 청구를 보장하세요.일반적인 문제
대부분의 사용량 기반 청구 문제는 다음 범주에 해당합니다.- 이벤트 전달 및 처리 문제
- 미터 구성 문제
- 데이터 타입 및 형식 오류
- 고객 ID 및 인증 문제
디버깅 단계
사용량 기반 청구 문제를 해결할 때는 다음을 수행하세요.- 이벤트 분석 탭에서 이벤트 전달을 확인합니다.
- 미터 구성이 이벤트 구조와 일치하는지 확인합니다.
- 고객 ID와 API 인증을 검증합니다.
- 필터링 조건과 집계 설정을 검토합니다.
해결 방법 및 수정 사항
Events not showing in meter
Events not showing in meter
일반적인 원인:
- 이벤트 이름이 미터 구성과 정확히 일치하지 않음
- 이벤트 필터링 조건이 이벤트를 제외함
- 고객 ID가 Dodo Payments 계정에 존재하지 않음
- 이벤트 타임스탬프가 현재 청구 기간을 벗어남
- 이벤트 이름의 철자와 대소문자를 확인합니다.
- 필터링 조건을 검토하고 테스트합니다.
- 고객 ID가 유효하고 활성 상태인지 확인합니다.
- 이벤트 타임스탬프가 최근 시점이며 올바른 형식인지 확인합니다.
Aggregation not working as expected
Aggregation not working as expected
일반적인 원인:
- Over Property 이름이 이벤트 메타데이터 키와 일치하지 않음
- 메타데이터 값의 데이터 타입이 잘못됨(문자열과 숫자 간 불일치)
- 필수 메타데이터 속성이 누락됨
- 메타데이터 키가 Over Property 설정과 정확히 일치하는지 확인합니다.
- 이벤트에서 문자열 숫자를 실제 숫자로 변환합니다.
- 모든 이벤트에 필요한 속성을 포함합니다.
Filtering not working
Filtering not working
일반적인 원인:
- 필터 속성 이름이 이벤트 메타데이터와 일치하지 않음
- 데이터 타입에 적합하지 않은 비교 연산자 사용(문자열과 숫자 간 불일치)
- 문자열 비교에서 대소문자를 구분함
- 속성 이름이 정확히 일치하는지 다시 확인합니다.
- 데이터 타입에 적합한 비교 연산자를 사용합니다.
- 문자열을 필터링할 때 대소문자 구분 여부를 고려합니다.
관련 API Reference
Create Meter
고객 소비량 추적을 위한 사용량 미터 생성 및 구성 API reference
Ingest Usage Events
청구 계산을 위해 구성된 미터로 사용량 이벤트를 전송하는 API reference