메인 콘텐츠로 건너뛰기

API Reference - Events Ingestion

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

API Reference - Meters Creation

미터를 생성하기 위한 전체 API 문서를 살펴보고 미터 생성 요청과 응답을 대화식으로 테스트하세요.

​
미터 생성

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

​
단계별 미터 생성

사용 미터를 설정하기 위한 이 포괄적인 가이드를 따르세요:
1

Configure Basic Information

미터의 기본 정보를 설정하세요.
​
Meter Name
string
필수
이 미터가 추적하는 항목을 식별할 수 있는 명확하고 설명적인 이름을 선택하세요.Examples: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”
​
Description
string
이 미터가 무엇을 측정하는지 상세히 설명하세요.Example: “Counts each POST /v1/orders request made by the customer”
​
Event Name
string
필수
이 미터를 트리거할 이벤트 식별자를 지정하세요.Examples: “token”, “api.call”, “storage.usage”, “compute.session”
이벤트 이름은 사용량 이벤트에 전송하는 값과 정확히 일치해야 합니다. 이벤트 이름은 대소문자를 구분합니다.
2

Configure Aggregation Settings

이 미터가 이벤트에서 사용량을 어떻게 계산할지 정의하세요.
​
Aggregation Type
string
필수
이벤트를 어떻게 집계할지 선택하세요:
수신된 이벤트 수를 단순히 계산합니다.사용 사례: API 호출, 페이지 조회수, 파일 업로드Calculation: Total number of events
​
Over Property
string
집계할 이벤트 메타데이터의 속성 이름입니다.
이 필드는 합계, 최대값, 또는 마지막 값 집계 유형을 사용할 때 필수입니다.
​
Measurement Unit
string
필수
보고서 및 청구에서 표시할 단위 레이블을 정의하세요.Examples: “calls”, “GB”, “hours”, “tokens”
3

Configure Event Filtering (Optional)

측정에 포함할 이벤트를 제어하는 기준을 설정하세요.
이벤트 필터링을 통해 테스트 이벤트 제외, 사용자 등급별 필터링, 특정 동작에 집중하는 등 복잡한 규칙을 만들어 사용량 계산에 포함될 이벤트를 결정할 수 있습니다.
이벤트 필터링 활성화조건부 이벤트 처리를 활성화하려면 이벤트 필터링 활성화를 전환하세요.필터 논리 선택여러 조건이 평가되는 방식을 선택하세요:
모든 조건이 참일 때만 이벤트를 계산합니다. 여러 엄격한 기준을 동시에 충족해야 할 때 사용하세요.예: user_tier = "premium" AND endpoint = "/api/v2/users"인 API 호출을 계산합니다.
필터 조건 설정
1

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

그룹 추가를 사용해 복잡한 논리를 위한 조건 그룹을 추가로 만드세요.
필터링되는 속성은 조건이 제대로 작동하려면 이벤트 메타데이터에 포함되어야 합니다. 필수 속성이 없는 이벤트는 계산에서 제외됩니다.
4

Create Meter

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

​
제품에 미터 연결하기

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

​
제품 구성 프로세스

제품 설정을 적절히 구성하여 사용 데이터를 청구 가능한 요금으로 변환하세요:
1

Choose Usage-Based Billing Product Type

제품 생성 또는 편집 페이지로 이동하여 제품 유형으로 사용량 기반을 선택하세요.
2

Select Associated Meter

측면에서 미터 선택 패널을 열려면 연관된 미터를 클릭하세요.이 패널에서 이 제품의 사용량을 추적할 미터를 구성할 수 있습니다.
3

Add Your Meter

미터 선택 패널에서:
  1. 미터 추가를 클릭하여 사용 가능한 미터를 확인합니다.
  2. 드롭다운 목록에서 생성한 미터를 선택합니다.
  3. 선택한 미터가 제품 구성에 나타납니다.
4

Configure Price Per Unit

미터가 추적하는 각 사용량 단위의 가격을 설정하세요.
​
Price Per Unit
number
필수
미터가 측정하는 각 단위에 대해 청구할 금액을 정의하세요.예: 단위당 $0.50로 설정하면:
  • 1,000 단위 소비 = 1,000 × 0.50=0.50 = 500.00 청구
  • 500 단위 소비 = 500 × 0.50=0.50 = 250.00 청구
  • 100 단위 소비 = 100 × 0.50=0.50 = 50.00 청구
5

Set Free Threshold (Optional)

청구가 시작되기 전에 무료 사용 할당량을 설정하세요.
​
Free Threshold
number
고객이 유료 사용량 계산이 시작되기 전에 무료로 사용할 수 있는 단위 수입니다.작동 방식:
  • 무료 임계값: 100 단위
  • 단위당 가격: $0.50
  • 고객 사용량: 250 단위
  • 계산: (250 - 100) × 0.50=∗∗0.50 = **75.00** 청구
무료 임계값은 프리미엄 모델, 평가판 기간 또는 플랜에 기본 포함된 허용량을 제공할 때 이상적입니다.
무료 임계값은 각 청구 주기에 적용되어 고객에게 매월 또는 청구 일정에 따라 새로운 허용량을 제공합니다.
6

Save Configuration

미터와 가격 구성을 검토한 다음 변경 사항 저장을 클릭하여 설정을 완료하세요.
제품이 이제 사용량 기반 청구를 위해 구성되었으며 측정된 소비량에 따라 고객에게 자동으로 청구됩니다.
다음 단계:
  • 미터에 전송된 사용량 이벤트가 추적되고 집계됩니다
  • 청구 계산은 가격 규칙을 자동으로 적용합니다
  • 고객은 각 청구 주기 동안 실제 소비량에 따라 요금이 청구됩니다
제품당 최대 10개의 미터를 추가하여 API 호출, 저장소, 컴퓨트 시간 또는 사용자 정의 메트릭처럼 여러 차원에서 정교하게 사용량을 추적할 수 있습니다.

​
사용 이벤트 전송

미터가 구성되면 애플리케이션에서 고객 사용량을 추적하기 위해 사용 이벤트를 전송할 수 있습니다.

​
이벤트 구조

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

​
사용 이벤트 API 예시

이벤트 API를 사용하여 구성된 미터에 사용 이벤트를 전송하세요: 
const response = 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_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

​
사용 기반 청구 분석

포괄적인 분석 대시보드를 통해 사용 기반 청구 데이터를 모니터링하고 분석하세요. 고객 소비 패턴, 미터 성능 및 청구 추세를 추적하여 가격 전략을 최적화하고 사용 행동을 이해하세요.

​
개요 분석

개요 탭은 사용 기반 청구 성과에 대한 포괄적인 보기를 제공합니다:

​
활동 메트릭

다양한 기간에 걸쳐 주요 사용 통계를 추적하세요:
​
Current Month
metric
현재 청구 기간의 사용량 활동을 보여주어 월간 소비 패턴을 이해하는 데 도움이 됩니다.
​
All Time
metric
추적을 시작한 이후의 누적 사용량 통계를 표시하여 장기적인 성장 통찰을 제공합니다.
기간 선택기를 사용하여 다양한 월간 사용량을 비교하고 계절적 추세나 성장 패턴을 확인하세요.

​
미터 수량 차트

Meter quantities chart showing usage trends over time with purple gradient visualization
미터 수량 차트는 다음 기능을 통해 시간에 따른 사용 추세를 시각화합니다:
  • 시계열 시각화: 일, 주 또는 월에 걸쳐 사용 패턴 추적
  • 다중 미터 지원: 서로 다른 미터의 데이터를 동시에 보기
  • 추세 분석: 사용 급증, 패턴 및 성장 궤적 식별
차트는 사용량 규모와 선택한 기간에 따라 자동으로 스케일링되어 작은 변동부터 주요 사용량 변화까지 명확하게 보여줍니다.

​
이벤트 분석

Events table showing event names, IDs, and pagination controls for detailed event analysis
이벤트 탭은 개별 사용 이벤트에 대한 세부적인 가시성을 제공합니다:

​
이벤트 정보 표시

이벤트 테이블은 다음 열을 통해 개별 사용 이벤트를 명확하게 보여줍니다:
  • 이벤트 이름: 사용 이벤트를 생성한 특정 작업 또는 트리거
  • 이벤트 ID: 각 이벤트 인스턴스에 대한 고유 식별자
  • 고객 ID: 이벤트와 관련된 고객
  • 타임스탬프: 이벤트가 발생한 시간
이 보기에서는 고객 기반 전반의 개별 사용량 이벤트를 추적하고 모니터링하여 청구 계산과 사용 패턴에 대한 투명성을 제공합니다.

​
고객 분석

고객 탭은 고객 사용 데이터의 세부 테이블 뷰를 제공하며 다음 정보를 포함합니다:

​
사용 가능한 데이터 열

​
Customer Email
string
식별을 위한 고객의 이메일 주소입니다.
​
Subscription ID
string
고객 구독의 고유 식별자입니다.
​
Free Threshold
number
고객 플랜에 포함된 무료 단위 수입니다.
​
Price Per Unit
currency
무료 임계값을 초과한 사용량에 대한 단위당 비용입니다.
​
Last Event
timestamp
고객의 가장 최근 사용 이벤트 타임스탬프입니다.
​
Total Price
currency
사용량 기반 청구로 고객에게 청구된 총 금액입니다.
​
Consumed Units
number
고객이 소비한 총 단위 수입니다.
​
Chargeable Units
number
무료 임계값을 초과하여 청구되는 단위 수입니다.

​
테이블 기능

  • 열 필터링: “열 편집” 기능을 사용하여 특정 데이터 열을 표시/숨기기
  • 실시간 업데이트: 사용 데이터는 가장 최신 소비 메트릭을 반영합니다.

​
집계 예시

다양한 집계 유형이 작동하는 방법에 대한 실용적인 예시입니다:

​
집계 유형 이해하기

다양한 집계 유형은 서로 다른 청구 시나리오에 적합합니다. 사용량을 측정하고 청구하는 방식을 기반으로 올바른 유형을 선택하세요.

​
실용적인 구현 예시

이 예시는 각 집계 유형의 실제 응용 프로그램을 샘플 이벤트 및 예상 결과와 함께 보여줍니다.
시나리오: 총 API 요청 수 추적미터 구성:
  • 이벤트 이름: api.call
  • 집계 유형: Count
  • 측정 단위: calls
샘플 이벤트:
{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}
결과: 고객에게 3회 호출이 청구됩니다
시나리오: 전송된 총 바이트를 기준으로 청구미터 구성:
  • 이벤트 이름: data.transfer
  • 집계 유형: Sum
  • Over Property: bytes
  • 측정 단위: GB
샘플 이벤트:
{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}
결과: 고객에게 총 1.5GB 전송량이 청구됩니다
시나리오: 최고 동시 사용자 수를 기준으로 청구미터 구성:
  • 이벤트 이름: concurrent.users
  • 집계 유형: Max
  • Over Property: count
  • 측정 단위: users
샘플 이벤트:
{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}
결과: 고객에게 23명의 최대 동시 사용자가 청구됩니다

​
이벤트 필터링 예시

특정 엔드포인트에 대한 API 호출만 계산:필터 구성:
  • 속성: endpoint
  • 비교자: equals
  • 값: /v1/orders
샘플 이벤트:
{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}
결과: 필터 기준에 맞는 이벤트만 계산됩니다. 다른 엔드포인트의 이벤트는 무시됩니다.

​
문제 해결

사용 기반 청구 구현과 관련된 일반적인 문제를 해결하고 정확한 추적 및 청구를 보장하세요.

​
일반적인 문제

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

​
디버깅 단계

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

​
솔루션 및 수정 사항

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