미터 설계

미터는 “어떤 이벤트의 어떤 값을 어떻게 모아 한 달 청구 수량으로 만들지”를 정한 규칙입니다. 미터만으로는 금액이 생기지 않습니다. 미터에 단가를 등록해야 청구 예정액에 금액이 잡힙니다. 단가는 단가 모델과 버전에서 다룹니다. 고객, 미터, 단가는 업무 환경마다 따로 만들어야 합니다. 테스트 환경에서 만든 미터는 실제 환경에 없습니다. 자세한 내용은 업무 환경을 보세요.

이벤트가 한 건이라도 들어온 미터는 이름만 바꿀 수 있습니다. 보낸 이벤트는 지울 수 없으므로 시험 삼아 보낸 이벤트 한 건으로도 계산 기준이 굳습니다. 이 페이지의 설계 순서대로 정의를 확정한 뒤 이벤트를 보내세요.

이벤트와 미터의 대응

이벤트 하나에서 여러 미터가 각자 수량을 뽑을 수 있습니다. 아래는 AI 서비스가 생성 요청 한 번마다 보내는 이벤트입니다.

이벤트 예시

{
  "transaction_id": "gen_20261105_000123",
  "customer_id": "8b0f4c2e-6d1a-4f3b-9a57-2c4e8d9b1f60",
  "type": "llm_generation",
  "timestamp": "2026-11-05T10:00:00+09:00",
  "properties": {
    "model": "lumen-fast",
    "input_tokens": 1200,
    "output_tokens": 800
  }
}

이 이벤트 하나로 아래 미터를 모두 만들 수 있습니다.

미터 code	이벤트의 `type`	집계	집계 대상 속성	차원 키	과금 단위 크기
`llm-input-tokens`	`llm_generation`	`sum`	`input_tokens`	`model`	1000
`llm-output-tokens`	`llm_generation`	`sum`	`output_tokens`	`model`	1000
`llm-requests`	`llm_generation`	`count`	없음	`model`	1

미터의 event_type과 이벤트의 type이 글자까지 같아야 그 미터에 집계됩니다. 대소문자도 구분합니다.
같은 이벤트와 같은 속성으로 미터를 여러 개 만들 수 있고, 각 미터에 단가를 등록하면 각각 청구됩니다.
차원 키(dimension_properties)는 속성 값마다 다른 단가를 매길 때 씁니다. 위 예시는 model 값마다 단가가 다릅니다. 차원은 차원과 속성 조합에서 자세히 다룹니다.

미터 필드

필드	필수	설명
`code`	예	미터를 가리키는 값입니다. API 경로에 들어가며 등록한 뒤 바꿀 수 없습니다. 같은 업무 환경 안에서 유일해야 하고, `search`, `options`, `export`는 쓸 수 없습니다.
`name`	예	콘솔과 인보이스에 보이는 이름입니다. 언제든 바꿀 수 있습니다.
`event_type`	예	집계할 이벤트의 `type` 값입니다.
`aggregation`	예	집계 방식입니다. 아래 표를 보세요. 대소문자를 구분하지 않습니다.
`target_property`	`count` 외에는 예	이벤트 `properties`에서 집계할 키입니다. `count`에는 넣지 않습니다.
`dimension_properties`	아니요	단가를 가르는 `properties` 키의 배열입니다. 생략하면 빈 배열입니다. 같은 키를 두 번 넣거나 빈 키를 넣을 수 없습니다.
`unit_size`	아니요	집계량을 나눌 양수입니다. 기본값은 1입니다.
`rounding_mode`	아니요	`none`, `ceil`(올림), `floor`(내림), `round`(반올림, 사사오입) 가운데 하나입니다. 기본값은 `none`입니다.
`rounding_precision`	아니요	반올림할 소수 자릿수 0~12입니다. 기본값은 0이고, `rounding_mode`가 `none`이면 0으로 저장됩니다.
`percentile`	`percentile`만 예	0~100의 백분위입니다. `percentile` 집계에만 넣습니다.

code는 URL 경로에 그대로 들어가므로 영문 소문자, 숫자, 하이픈으로 정해 두면 다루기 쉽습니다.

콘솔의 미터 등록 창과 API 참조에는 code가 도입사 안에서 유일하다고 적혀 있지만, 실제로는 업무 환경마다 따로 정합니다. 테스트 환경과 실제 환경에 같은 code의 미터를 만들 수 있습니다.

집계 방식

한 달 동안 한 고객이 보낸 이벤트를 차원 값 조합마다 모아 아래 방식으로 계산합니다.

`aggregation`	콘솔 표기	계산	집계에 드는 값
`sum`	합계 (SUM)	값을 모두 더합니다	JSON number
`count`	이벤트 수 (COUNT)	이벤트 건수를 셉니다	속성과 관계없이 모든 이벤트
`count_distinct`	고유 값 수 (COUNT DISTINCT)	중복을 뺀 값의 수를 셉니다	JSON 문자열, number, 불리언
`min`	최솟값 (MIN)	가장 작은 값	JSON number
`max`	최댓값 (MAX)	가장 큰 값	JSON number
`avg`	평균 (AVG)	산술평균	JSON number
`first`	첫 값 (FIRST)	`timestamp`가 가장 이른 이벤트의 값. 시각이 같으면 `transaction_id` 순서	JSON number
`last`	마지막 값 (LAST)	`timestamp`가 가장 늦은 이벤트의 값. 시각이 같으면 `transaction_id` 순서	JSON number
`median`	중앙값 (MEDIAN)	50백분위 값	JSON number
`percentile`	백분위수 (PERCENTILE)	지정한 백분위의 값. 두 값 사이면 선형 보간	JSON number

숫자로 집계하는 미터는 값이 JSON number일 때만 셉니다. "input_tokens": "1200"처럼 문자열로 보내거나 키를 빠뜨린 이벤트는 저장은 되지만 집계에서 빠지고 오류 응답도 오지 않습니다. 이런 이벤트는 GET /v1/unbilled-events의 non_numeric_value와 콘솔 ‘이벤트 매핑 진단’ 화면의 ‘집계할 수량 확인 필요’에 나타납니다. 연동 코드에서 숫자 값을 number로 고정해 보내세요.

단위 크기와 반올림

집계량은 unit_size로 나눈 뒤 rounding_mode와 rounding_precision을 적용해 청구 수량이 됩니다. 이 변환은 이벤트마다가 아니라 한 달, 한 고객, 한 차원 값 조합의 집계 결과에 한 번 적용합니다. 예를 들어 unit_size 1000, rounding_mode ceil, rounding_precision 0인 토큰 미터에 한 고객이 같은 모델로 400토큰 이벤트를 세 번 보내면 다음과 같습니다.

집계량: 400 + 400 + 400 = 1200
청구 수량: 1200 / 1000 = 1.2, 올림하면 2

이벤트마다 올림했다면 3이 되었겠지만 MeterEngine은 합친 뒤 한 번만 올립니다. 반대로 같은 고객이 서로 다른 모델 두 개로 400토큰씩 보내면 조합마다 따로 올려 각각 1, 합해서 2가 됩니다. rounding_mode가 none이면 나눗셈 결과를 반올림하지 않고 정확한 분수로 유지해 금액을 계산합니다. 1/3처럼 끝나지 않는 소수도 근사하지 않습니다.

미터 만들기

이벤트 형식을 먼저 정한다

연동 코드가 보낼 type, 집계할 숫자 속성, 단가를 가를 속성을 정합니다. 숫자 값은 JSON number로, 차원 값은 문자열이든 숫자든 한 가지 타입으로 고정합니다.

미터를 등록한다

콘솔 또는 API로 등록합니다. 필요 권한은 admin입니다(화면과 API, 권한).

콘솔
API

화면 위 ‘업무 환경’이 원하는 환경(예: ‘테스트 환경’)인지 확인합니다.
왼쪽 메뉴 ‘미터’ 화면에서 ‘미터 등록’을 누릅니다.
‘코드’, ‘이름’, ‘이벤트 타입’, ‘집계 함수’를 넣고, 집계 함수가 ‘이벤트 수 (COUNT)‘가 아니면 ‘집계 대상 속성’을 넣습니다.
단가를 속성 값마다 다르게 매길 거라면 ‘차원 키’에 키를 쉼표로 나눠 넣습니다.
‘결과 변환’에서 ‘과금 단위 크기’와 ‘반올림 방식’을 정합니다. 창 아래 ‘계산 미리보기’로 식을 확인합니다.
‘저장’을 누릅니다.

curl -X POST https://meterengine.com/v1/billable-metrics \
  -H "Authorization: Bearer me_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-metric-llm-input-tokens" \
  -d '{
    "code": "llm-input-tokens",
    "name": "입력 토큰",
    "event_type": "llm_generation",
    "aggregation": "sum",
    "target_property": "input_tokens",
    "dimension_properties": ["model"],
    "unit_size": 1000,
    "rounding_mode": "none",
    "rounding_precision": 0
  }'

const response = await fetch("https://meterengine.com/v1/billable-metrics", {
  method: "POST",
  headers: {
    Authorization: "Bearer me_test_xxxxxxxx",
    "Content-Type": "application/json",
    "Idempotency-Key": "create-metric-llm-input-tokens",
  },
  body: JSON.stringify({
    code: "llm-input-tokens",
    name: "입력 토큰",
    event_type: "llm_generation",
    aggregation: "sum",
    target_property: "input_tokens",
    dimension_properties: ["model"],
    unit_size: 1000,
    rounding_mode: "none",
    rounding_precision: 0,
  }),
});
const metric = await response.json();

성공하면 201과 함께 등록한 미터가 옵니다.

201 응답

{
  "code": "llm-input-tokens",
  "name": "입력 토큰",
  "event_type": "llm_generation",
  "aggregation": "sum",
  "target_property": "input_tokens",
  "dimension_properties": ["model"],
  "archived_at": null,
  "active_from": "0001-01",
  "inactive_from": null,
  "unit_size": 1000,
  "rounding_mode": "none",
  "rounding_precision": 0,
  "percentile": null,
  "version": 0
}

Idempotency-Key는 선택입니다. 네트워크 오류로 다시 보낼 때 같은 키와 같은 본문을 쓰면 처음 응답을 그대로 돌려받습니다. 규칙은 멱등 규칙을 보세요.

단가를 등록한다

미터만 있고 단가가 없으면 청구 예정액이 0원입니다. 단가 모델과 버전에서 이번 달 단가를 등록합니다.

시험 이벤트로 수량을 확인한다

테스트 환경에 이벤트를 보내고 GET /v1/usage?month=YYYY-MM나 콘솔 ‘사용량’ 화면에서 미터별 수량을 확인합니다. 확인 방법은 보낸 데이터 확인하기를 보세요. 이 이벤트를 받은 뒤부터 그 업무 환경에서 이 미터는 이름만 바꿀 수 있습니다.

미터를 등록하기 전에 받은 같은 type의 이벤트도 미터를 만든 뒤에는 함께 집계됩니다. 다만 단가는 이번 달 이후로만 넣을 수 있어(시간 규칙) 아직 확정하지 않은 지난달의 사용량은 단가 없는 사용량으로 남고 청구되지 않습니다.

미터 오류

상태	`code`	원인
400	`validation_error`	`code`, `name`, `event_type`, `aggregation` 가운데 빈 값이 있거나 `rounding_precision`이 0~12 밖입니다. 수정 요청에서 `If-Match`가 큰따옴표로 감싼 version이 아니거나 `PATCH`에 `If-Match`가 없어도 이 code이며, 이때 `errors`의 `field`는 `If-Match`입니다.
400	`invalid_billable_metric`	집계 방식과 대상 속성, 단위, 반올림, 백분위 설정이 맞지 않거나, 차원 키에 중복이나 빈 키가 있거나, `code`가 `search`, `options`, `export`입니다. 어느 필드인지는 `errors`에 있습니다.
409	`billable_metric_already_exists`	같은 업무 환경에 같은 `code`의 미터가 있습니다.
409	`idempotency_conflict`	같은 `Idempotency-Key`를 다른 본문에 썼습니다.
409	`billable_metric_has_events`	이벤트가 있는 미터의 계산 기준을 바꾸려 했습니다.
409	`resource_archived`	보관한 미터를 고치려 했습니다. 복원한 뒤 고칩니다.
409	`resource_version_conflict`	`If-Match`의 version이 지금 version과 다릅니다. 다시 조회한 뒤 고칩니다.
404	`billable_metric_not_found`	그런 `code`의 미터가 이 업무 환경에 없습니다.

오류 응답 형식과 다시 보낼지 판단하는 기준은 오류 응답과 X-Request-ID를 보세요.

이벤트가 들어온 뒤의 수정

PUT /v1/billable-metrics/{code}는 미터를 요청 본문으로 통째로 덮어씁니다. 본문에서 빠뜨린 선택 필드는 기본값으로 돌아가므로, GET /v1/billable-metrics/{code}로 받은 값을 그대로 두고 바꿀 필드만 고쳐 보내세요. 다른 사람과 동시에 고칠 때는 GET /v1/billable-metrics/{code} 응답의 version을 큰따옴표로 감싸(예: "3") If-Match 헤더에 넣고 PATCH /v1/billable-metrics/{code}를 쓰면, 그 사이 다른 수정이 있었을 때 409 resource_version_conflict로 막힙니다. GET 응답의 ETag 헤더 값이 이 형식이라 그대로 넣어도 됩니다. 같은 업무 환경에 미터의 event_type 이벤트가 한 건이라도 있으면 name만 바꿀 수 있습니다. event_type, aggregation, target_property, dimension_properties, unit_size, rounding_mode, rounding_precision, percentile을 바꾸면 409 billable_metric_has_events입니다. 미터를 만들기 전에 받은 이벤트도 여기에 포함됩니다. 이름만 바꿀 때도 나머지 필드를 지금 값 그대로 함께 보내세요. 예를 들어 dimension_properties를 빠뜨리면 빈 배열로 바꾸는 요청이 되어, 이벤트가 있는 미터에서는 409 billable_metric_has_events로 거절됩니다. 보낸 이벤트는 고치거나 지울 수 없습니다. 잘못 보낸 값을 바로잡는 방법은 사용량 이벤트 보내기를 보세요.

계산 기준을 바꿔야 할 때

이벤트가 들어온 미터의 계산 기준은 바꿀 수 없으므로 새 미터를 만들고 옛 미터를 보관합니다. 미터를 보관하면 이번 달까지는 집계하고 다음 달부터 멈춥니다. 그래서 바꾸는 달에는 옛 미터와 새 미터가 같은 이벤트를 함께 셉니다. 두 번 청구되지 않도록 새 미터는 다음 달부터 금액이 생기게 합니다.

지난달 확정을 먼저 끝낸다

새 미터는 만들기 전에 받은 이벤트까지 집계하므로, 아직 확정하지 않은 지난달에도 새 미터의 사용량이 단가 없는 사용량으로 나타납니다. 지난달 단가는 넣을 수 없으니 지난달 인보이스를 확정한 뒤에 바꿉니다(인보이스 수동 확정).

새 미터를 만든다

새 code로 바뀐 계산 기준의 미터를 등록합니다. event_type은 옛 미터와 같아도 됩니다.

새 미터에 0원 버전과 실제 단가 버전을 등록한다

이번 달을 시작 월로 하는 0원 단가와, 다음 달을 시작 월로 하는 실제 단가를 등록합니다(예: 이번 달이 2026-11이면 effective_from 2026-11에 0원, 2026-12에 실제 단가). 이번 달에 단가를 비워 두면 새 미터의 사용량이 단가 없는 사용량으로 잡혀 청구 예정액의 unpriced_usages와 ‘이벤트 매핑 진단’ 화면에 나타납니다. 자동 확정이 켜진 서버에서는 청구 예정액이 0원이 아닌 그 고객의 자동 확정도 보류됩니다. 0원 단가를 두면 이번 달 새 미터 라인은 0원으로 계산됩니다.

옛 미터를 보관한다

‘미터’ 화면의 ‘보관’ 또는 DELETE /v1/billable-metrics/{code}로 보관합니다. 옛 미터는 이번 달까지 청구되고 다음 달부터 집계에서 빠집니다.

보관과 복원의 세부 규칙은 바꾸기, 보관, 복원을 보세요.

다음 단계

차원과 속성 조합

속성 값마다 다른 단가를 매기는 방법

단가 모델과 버전

미터에 단가를 등록하는 방법

시작하기

개념

계정과 조직

인증

API 사용 기본

가격 설계

고객과 이벤트 연동

확인과 진단

청구 확정

결제 연동

웹훅

참고

이벤트와 미터의 대응

미터 필드

집계 방식

단위 크기와 반올림

미터 만들기

미터 오류

이벤트가 들어온 뒤의 수정

계산 기준을 바꿔야 할 때

다음 단계

차원과 속성 조합

단가 모델과 버전

​이벤트와 미터의 대응

​미터 필드

​집계 방식

​단위 크기와 반올림

​미터 만들기

​미터 오류

​이벤트가 들어온 뒤의 수정

​계산 기준을 바꿔야 할 때

​다음 단계

차원과 속성 조합

단가 모델과 버전

이벤트와 미터의 대응

미터 필드

집계 방식

단위 크기와 반올림

미터 만들기

미터 오류

이벤트가 들어온 뒤의 수정

계산 기준을 바꿔야 할 때

다음 단계