사용 기반 청구 통합 가이드

API 참조 - 이벤트 수집

사용 이벤트를 수집하기 위한 전체 API 문서에 접근하고 이벤트 수집 요청 및 응답을 대화식으로 테스트하세요.

API 참조 - 미터 생성

미터 생성에 대한 전체 API 문서를 탐색하고 미터 생성 요청 및 응답을 대화식으로 테스트하세요.

미터 생성

미터는 청구 목적으로 사용 이벤트가 집계되고 측정되는 방식을 정의합니다. 미터를 생성하기 전에 사용 추적 전략을 계획하세요:

추적할 사용 이벤트를 식별하세요
이벤트가 집계되는 방식을 결정하세요 (수, 합계 등)
특정 사용 사례에 대한 필터링 요구 사항을 정의하세요

단계별 미터 생성

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

기본 정보 구성

미터의 기본 세부 정보를 설정하세요.

미터 이름

string

required

이 미터가 추적하는 내용을 식별하는 명확하고 설명적인 이름을 선택하세요.예시: “토큰”, “API 호출”, “저장소 사용량”, “컴퓨트 시간”

설명

string

이 미터가 측정하는 내용에 대한 자세한 설명을 제공하세요.예시: “고객이 만든 각 POST /v1/orders 요청을 계산합니다.”

이벤트 이름

string

required

이 미터를 트리거할 이벤트 식별자를 지정하세요.예시: “token”, “api.call”, “storage.usage”, “compute.session”

이벤트 이름은 사용 이벤트에서 전송하는 내용과 정확히 일치해야 합니다. 이벤트 이름은 대소문자를 구분합니다.

집계 설정 구성

이 미터가 이벤트에서 사용량을 계산하는 방식을 정의하세요.

집계 유형

string

required

이벤트가 집계되는 방식을 선택하세요:

수
합계
최대
마지막

수신된 이벤트의 수를 단순히 계산합니다.사용 사례: API 호출, 페이지 조회수, 파일 업로드계산: 총 이벤트 수

속성에 대한 집계

string

집계할 이벤트 메타데이터의 속성 이름입니다.

합계, 최대 또는 마지막 집계 유형을 사용할 때 이 필드는 필수입니다.

측정 단위

string

required

보고서 및 청구에서 표시할 단위 레이블을 정의하세요.예시: “calls”, “GB”, “hours”, “tokens”

이벤트 필터링 구성 (선택 사항)

미터에 포함될 이벤트를 제어하기 위한 기준을 설정하세요.

이벤트 필터링을 통해 사용량 계산에 기여하는 이벤트를 결정하는 정교한 규칙을 만들 수 있습니다. 이는 테스트 이벤트를 제외하거나 사용자 계층에 따라 필터링하거나 특정 작업에 집중하는 데 유용합니다.

이벤트 필터링 활성화조건부 이벤트 처리를 활성화하려면 이벤트 필터링 활성화를 전환하세요.필터 논리 선택여러 조건이 평가되는 방식을 선택하세요:

AND 논리
OR 논리

모든 조건이 참이어야 이벤트가 계산됩니다. 여러 엄격한 기준을 동시에 충족해야 할 때 사용하세요.예시: user_tier = "premium" AND endpoint = "/api/v2/users"인 API 호출 수 계산

이벤트가 계산되기 위해서는 최소한 하나의 조건이 참이어야 합니다. 여러 기준 중 하나라도 충족하는 이벤트를 포함하고 싶을 때 사용하세요.예시: method = "POST" OR method = "PUT" OR method = "DELETE"인 이벤트 수 계산

필터 조건 설정

조건 추가

조건 추가를 클릭하여 새 필터 규칙을 만드세요.

속성 키 구성

이벤트 메타데이터에서 속성 이름을 지정하세요.

비교자 선택

사용 가능한 연산자 중에서 선택하세요:

equals - 정확한 일치
not equals - 제외 필터
greater than - 숫자 비교
greater than or equals - 숫자 비교 (포함)
less than - 숫자 비교
less than or equals - 숫자 비교 (포함)
contains - 문자열에 부분 문자열 포함
does not contain - 문자열 제외 필터

비교 값 설정

비교를 위한 목표 값을 설정하세요.

그룹 추가

복잡한 논리를 위한 추가 조건 그룹을 만들려면 그룹 추가를 사용하세요.

필터링된 속성은 조건이 제대로 작동하기 위해 이벤트 메타데이터에 포함되어야 합니다. 필수 속성이 누락된 이벤트는 계산에서 제외됩니다.

미터 생성

미터 구성을 검토하고 미터 생성을 클릭하세요.

이제 미터가 사용 이벤트를 수신하고 집계할 준비가 되었습니다.

제품에 미터 연결하기

미터를 생성한 후, 사용 기반 청구를 활성화하기 위해 제품에 연결해야 합니다. 이 과정은 미터의 사용 데이터를 고객 청구를 위한 가격 규칙에 연결합니다. 미터를 제품에 연결하면 사용 추적과 청구 간의 연결이 설정됩니다:

제품은 가격 규칙과 청구 동작을 정의합니다
미터는 청구 계산을 위한 사용 데이터를 제공합니다
복잡한 청구 시나리오를 위해 여러 미터를 단일 제품에 연결할 수 있습니다

제품 구성 프로세스

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

사용 기반 청구 제품 유형 선택

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

연관된 미터 선택

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

미터 추가

미터 선택 패널에서:

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

단위당 가격 설정

미터가 추적하는 각 사용 단위에 대한 가격을 설정하세요.

단위당 가격

number

required

미터로 측정된 각 단위에 대해 얼마를 청구할지 정의하세요.예시: $0.50 단위당 설정은 다음을 의미합니다:

1,000 단위 소비 = 1,000 × $0.50 = 500.00 청구
500 단위 소비 = 500 × $0.50 = 250.00 청구
100 단위 소비 = 100 × $0.50 = 50.00 청구

무료 한도 설정 (선택 사항)

청구가 시작되기 전에 무료 사용 허용량을 구성하세요.

무료 한도

number

고객이 유료 사용 계산이 시작되기 전에 소비할 수 있는 무료 단위 수입니다.작동 방식:

무료 한도: 100 단위
단위당 가격: $0.50
고객 사용량: 250 단위
계산: (250 - 100) × $0.50 = **$ 75.00** 청구

무료 한도는 프리미엄 모델, 시험 기간 또는 고객에게 요금제에 포함된 기본 허용량을 제공하는 데 이상적입니다.

무료 한도는 각 청구 주기에 적용되어 고객에게 매월 또는 청구 일정에 따라 새로운 허용량을 제공합니다.

구성 저장

미터 및 가격 구성을 검토한 후 변경 사항 저장을 클릭하여 설정을 완료하세요.

이제 제품이 사용 기반 청구를 위해 구성되었으며, 고객의 측정된 소비에 따라 자동으로 청구됩니다.

다음에 일어나는 일:

미터로 전송된 사용 이벤트가 추적되고 집계됩니다.
청구 계산이 가격 규칙을 자동으로 적용합니다.
고객은 각 청구 주기 동안 실제 소비에 따라 청구됩니다.

제품당 최대 10개의 미터를 추가할 수 있으므로 API 호출, 저장소, 컴퓨트 시간 및 사용자 정의 메트릭과 같은 여러 차원에서 정교한 사용 추적이 가능합니다.

사용 이벤트 전송

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

이벤트 구조

각 사용 이벤트는 다음 필드를 포함해야 합니다:

event_id

string

required

이 특정 이벤트에 대한 고유 식별자입니다. 모든 이벤트에서 고유해야 합니다.

customer_id

string

required

이 사용량이 귀속되어야 하는 Dodo Payments 고객 ID입니다.

event_name

string

required

미터 구성과 일치하는 이벤트 이름입니다. 이벤트 이름은 적절한 미터를 트리거합니다.

timestamp

string

이벤트가 발생한 ISO 8601 타임스탬프입니다. 제공되지 않으면 현재 시간으로 기본 설정됩니다.

metadata

object

필터링 및 집계를 위한 추가 속성입니다. 미터의 “속성에 대한 집계” 또는 필터링 조건에서 참조된 값을 포함하세요.

사용 이벤트 API 예시

이벤트 API를 사용하여 구성된 미터에 사용 이벤트를 전송하세요:

const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_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
        }
      }
    ]
  })
});

사용 기반 청구 분석

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

개요 분석

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

활동 메트릭

다양한 기간에 걸쳐 주요 사용 통계를 추적하세요:

현재 월

metric

현재 청구 기간 동안의 사용 활동을 보여주며, 월별 소비 패턴을 이해하는 데 도움이 됩니다.

전체 기간

metric

추적을 시작한 이후의 누적 사용 통계를 표시하여 장기 성장 통찰력을 제공합니다.

시간 기간 선택기를 사용하여 서로 다른 월의 사용량을 비교하고 계절적 추세나 성장 패턴을 식별하세요.

미터 수량 차트

미터 수량 차트는 다음 기능을 통해 시간에 따른 사용 추세를 시각화합니다:

시계열 시각화: 일, 주 또는 월에 걸쳐 사용 패턴 추적
다중 미터 지원: 서로 다른 미터의 데이터를 동시에 보기
추세 분석: 사용 급증, 패턴 및 성장 궤적 식별

차트는 사용량과 선택한 시간 범위에 따라 자동으로 스케일링되어 작은 변동과 큰 사용 변화 모두에 대한 명확한 가시성을 제공합니다.

이벤트 분석

이벤트 탭은 개별 사용 이벤트에 대한 세부적인 가시성을 제공합니다:

이벤트 정보 표시

이벤트 테이블은 다음 열을 통해 개별 사용 이벤트를 명확하게 보여줍니다:

이벤트 이름: 사용 이벤트를 생성한 특정 작업 또는 트리거
이벤트 ID: 각 이벤트 인스턴스에 대한 고유 식별자
고객 ID: 이벤트와 관련된 고객
타임스탬프: 이벤트가 발생한 시간

이 뷰를 통해 고객 기반의 개별 사용 이벤트를 추적하고 모니터링할 수 있으며, 청구 계산 및 사용 패턴에 대한 투명성을 제공합니다.

고객 분석

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

사용 가능한 데이터 열

고객 이메일

string

식별을 위한 고객의 이메일 주소입니다.

구독 ID

string

고객의 구독에 대한 고유 식별자입니다.

무료 한도

number

청구가 적용되기 전에 고객의 요금제에 포함된 무료 단위 수입니다.

단위당 가격

currency

무료 한도를 초과하는 사용에 대한 단위당 비용입니다.

마지막 이벤트

timestamp

고객의 가장 최근 사용 이벤트의 타임스탬프입니다.

총 가격

currency

사용 기반 청구를 위해 고객에게 청구된 총 금액입니다.

소비된 단위

number

고객이 소비한 총 단위 수입니다.

청구 가능한 단위

number

무료 한도를 초과하고 청구되는 단위 수입니다.

테이블 기능

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

집계 예시

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

집계 유형 이해하기

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

실용적인 구현 예시

이 예시는 각 집계 유형의 실제 응용 프로그램을 샘플 이벤트 및 예상 결과와 함께 보여줍니다.

수 집계 - API 호출

시나리오: API 요청의 총 수를 추적합니다.미터 구성:

이벤트 이름: api.call
집계 유형: 수
측정 단위: 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
집계 유형: 합계
속성에 대한 집계: 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.5 GB의 총 전송

최대 집계 - 동시 사용자 수

시나리오: 최고 동시 사용자 수를 기준으로 청구합니다.미터 구성:

이벤트 이름: concurrent.users
집계 유형: 최대
속성에 대한 집계: 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 엔드포인트로 필터링
값 범위로 필터링
복잡한 다중 조건 필터

특정 엔드포인트에 대한 API 호출만 계산합니다:필터 구성:

속성: endpoint
비교자: equals
값: /v1/orders

샘플 이벤트:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}

결과: 필터 기준에 맞는 이벤트가 계산됩니다. 다른 엔드포인트의 이벤트는 무시됩니다.

대용량 파일 업로드만 계산합니다:필터 구성:

속성: file_size
비교자: greater_than
값: 1048576 (1MB의 바이트 수)

샘플 이벤트:

{
  "event_id": "upload_1",
  "customer_id": "cus_123", 
  "event_name": "file.upload",
  "metadata": {
    "file_size": 5242880,
    "file_type": "image"
  }
}

결과: 1MB보다 큰 파일이 계산됩니다. 작은 파일은 무시됩니다.

업무 시간 동안 프리미엄 API 호출을 계산합니다:필터 구성 (AND 논리 사용):

속성: plan_type, 비교자: equals, 값: premium
속성: hour, 비교자: greater_than_or_equal, 값: 9
속성: hour, 비교자: less_than, 값: 17

샘플 이벤트:

{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "plan_type": "premium",
    "hour": 14,
    "endpoint": "/v1/analytics"
  }
}

결과: 업무 시간(오전 9시 - 오후 5시) 동안의 프리미엄 API 호출이 계산됩니다.

문제 해결

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

일반적인 문제

대부분의 사용 기반 청구 문제는 다음 범주에 해당합니다:

이벤트 전송 및 처리 문제
미터 구성 문제
데이터 유형 및 형식 오류
고객 ID 및 인증 문제

디버깅 단계

사용 기반 청구를 문제 해결할 때:

이벤트 분석 탭에서 이벤트 전송을 확인하세요.
미터 구성이 이벤트 구조와 일치하는지 확인하세요.
고객 ID 및 API 인증을 검증하세요.
필터링 조건 및 집계 설정을 검토하세요.

솔루션 및 수정 사항

미터에 이벤트가 표시되지 않음

일반적인 원인:

이벤트 이름이 미터 구성과 정확히 일치하지 않음
이벤트 필터링 조건이 이벤트를 제외하고 있음
고객 ID가 Dodo Payments 계정에 존재하지 않음
이벤트 타임스탬프가 현재 청구 기간 외부에 있음

솔루션:

이벤트 이름의 철자 및 대소문자 구분을 확인하세요.
필터링 조건을 검토하고 테스트하세요.
고객 ID가 유효하고 활성 상태인지 확인하세요.
이벤트 타임스탬프가 최근이고 올바르게 형식화되었는지 확인하세요.

집계가 예상대로 작동하지 않음

일반적인 원인:

속성에 대한 집계 이름이 이벤트 메타데이터 키와 일치하지 않음
메타데이터 값이 잘못된 데이터 유형(문자열 vs 숫자)
필수 메타데이터 속성이 누락됨

솔루션:

메타데이터 키가 속성에 대한 집계 설정과 정확히 일치하는지 확인하세요.
문자열 숫자를 실제 숫자로 변환하세요.
모든 이벤트에 필수 속성을 포함하세요.

필터링이 작동하지 않음

일반적인 원인:

필터 속성 이름이 이벤트 메타데이터와 일치하지 않음
데이터 유형에 대한 잘못된 비교자(문자열 vs 숫자)
문자열 비교에서 대소문자 구분

솔루션:

속성 이름이 정확히 일치하는지 다시 확인하세요.
데이터 유형에 적합한 비교자를 사용하세요.
문자열 필터링 시 대소문자 구분을 고려하세요.

Integration Guides

Cookbooks

API 참조 - 이벤트 수집

API 참조 - 미터 생성

미터 생성

단계별 미터 생성

제품에 미터 연결하기

제품 구성 프로세스

사용 이벤트 전송

이벤트 구조

사용 이벤트 API 예시

사용 기반 청구 분석

개요 분석

활동 메트릭

미터 수량 차트

이벤트 분석

이벤트 정보 표시

고객 분석

사용 가능한 데이터 열

테이블 기능

집계 예시

집계 유형 이해하기

실용적인 구현 예시

이벤트 필터링 예시

문제 해결

일반적인 문제

디버깅 단계

솔루션 및 수정 사항

Integration Guides

Cookbooks

API 참조 - 이벤트 수집

API 참조 - 미터 생성

​미터 생성

​단계별 미터 생성

​제품에 미터 연결하기

​제품 구성 프로세스

​사용 이벤트 전송

​이벤트 구조

​사용 이벤트 API 예시

​사용 기반 청구 분석

​개요 분석

​활동 메트릭

​미터 수량 차트

​이벤트 분석

​이벤트 정보 표시

​고객 분석

​사용 가능한 데이터 열

​테이블 기능

​집계 예시

​집계 유형 이해하기

​실용적인 구현 예시

​이벤트 필터링 예시

​문제 해결

​일반적인 문제

​디버깅 단계

​솔루션 및 수정 사항

미터 생성

단계별 미터 생성

제품에 미터 연결하기

제품 구성 프로세스

사용 이벤트 전송

이벤트 구조

사용 이벤트 API 예시

사용 기반 청구 분석

개요 분석

활동 메트릭

미터 수량 차트

이벤트 분석

이벤트 정보 표시

고객 분석

사용 가능한 데이터 열

테이블 기능

집계 예시

집계 유형 이해하기

실용적인 구현 예시

이벤트 필터링 예시

문제 해결

일반적인 문제

디버깅 단계

솔루션 및 수정 사항