차원과 속성 조합

같은 토큰이라도 모델마다 값이 다르면 미터에 차원 키를 두고 속성 값 조합마다 단가를 등록합니다. 차원 키는 미터의 dimension_properties이고, 단가의 dimension_values가 그 키마다 값을 정합니다.

조합은 어떻게 나뉘나

MeterEngine은 한 달 동안 한 고객의 이벤트를 미터의 차원 키 값이 같은 것끼리 묶어 따로 집계합니다. 이 묶음을 조합이라고 부릅니다. 금액은 조합마다 그 조합의 단가로 계산합니다. dimension_properties가 ["model"]인 토큰 미터에 한 고객이 이번 달 아래 이벤트를 보냈다고 합시다.

이벤트 `properties`	조합 `dimension_values`
`{"model": "lumen-fast", "input_tokens": 700}`	`{"model": "lumen-fast"}`
`{"model": "lumen-fast", "input_tokens": 500}`	`{"model": "lumen-fast"}`
`{"model": "lumen-pro", "input_tokens": 300}`	`{"model": "lumen-pro"}`
`{"input_tokens": 100}`	`{"model": null}`

이 고객의 사용량은 lumen-fast 1200, lumen-pro 300, 그리고 model 키가 없는 이벤트의 {"model": null} 100으로 나뉩니다.

차원 키가 둘 이상이면 키마다의 값이 모두 같아야 같은 조합입니다. 조합 수는 키마다 나오는 값 수의 곱만큼 늘어납니다. 모델 3개와 지역 4개를 쓰면 단가가 12개 필요합니다.
차원 키가 없는 미터는 조합이 {} 하나뿐입니다.

단가가 적용되는 규칙

키 집합이 미터와 정확히 같아야 한다

단가의 dimension_values 키 집합은 미터의 dimension_properties와 정확히 같아야 합니다. 키가 빠지거나 남으면 400 invalid_price_rate로 거절됩니다. 차원 키가 없는 미터는 {}로 등록합니다.

값이 정확히 같은 단가만 쓴다

이벤트에서 나온 조합과 값이 정확히 같은 단가만 적용합니다. 다른 조합의 단가로 대신 계산하지 않으며, 차원 키가 있는 미터에는 “나머지 모든 값” 단가를 둘 수 없습니다. 맞는 단가가 없는 조합의 사용량은 청구되지 않습니다.

고객 단가가 있으면 그것을 먼저 쓴다

같은 조합에 그 고객 전용 단가가 있으면 그것을, 없으면 공통 단가를 씁니다. 고객 단가는 단가 모델과 버전에서 다룹니다.

값이 같은지 판단하는 방법

이벤트 값	단가 값	같은 조합인가
`"lumen-fast"`	`"lumen-fast"`	예
`"lumen-fast"`	`"Lumen-Fast"`	아니요. 대소문자와 공백까지 같아야 합니다
`9`	`9.0`	예. 숫자는 값으로 비교합니다
`"9"`	`9`	아니요. 문자열과 숫자는 다릅니다
`true`	`"true"`	아니요. 불리언과 문자열은 다릅니다
키 없음 또는 `null`	(등록할 수 없음)	단가 값은 문자열, 숫자, 불리언만 됩니다. 키가 없는 이벤트의 조합은 늘 단가가 없습니다

연동 코드가 같은 차원 값을 어떤 때는 "9", 어떤 때는 9로 보내면 서로 다른 조합이 되어 한쪽은 청구되지 않습니다. 차원 값의 타입과 표기를 하나로 고정하고, 차원 키는 모든 이벤트에 빠짐없이 넣으세요. 값이 객체나 배열이어도 단가를 매길 수 없습니다.

차원별 단가 등록하기

미터의 dimension_properties가 ["model"]일 때 모델마다 단가를 하나씩 등록합니다. 필요 권한은 admin입니다(화면과 API, 권한).

콘솔
API

왼쪽 메뉴 ‘요금 설계’ 화면을 엽니다.
‘무엇을 과금하나요’ 목록에서 미터를 고릅니다.
‘단가 버전 등록’을 누릅니다.
차원 키마다 ‘model 값’에 값을 넣고 ‘model 값 종류’에서 ‘문자열’, ‘숫자’, ‘불리언 (true/false)’ 가운데 이벤트와 같은 타입을 고릅니다.
계산 방식과 단가를 넣고 ‘이 단가 버전 저장’을 누릅니다.
다른 모델도 같은 방법으로 하나씩 등록합니다.

curl -X POST https://meterengine.com/v1/billable-metrics/llm-input-tokens/price-rates \
  -H "Authorization: Bearer me_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "dimension_values": { "model": "lumen-fast" },
    "model": "per_unit",
    "unit_price": 2
  }'

const response = await fetch(
  "https://meterengine.com/v1/billable-metrics/llm-input-tokens/price-rates",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer me_test_xxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      dimension_values: { model: "lumen-fast" },
      model: "per_unit",
      unit_price: 2,
    }),
  },
);
const priceRate = await response.json();

model은 이벤트의 차원 키가 아니라 단가 계산 방식(per_unit, graduated, volume)을 뜻하는 필드입니다. 차원 키 이름이 model이어도 둘은 서로 다른 자리에 들어갑니다.

새 차원 값(예: 새 모델)을 서비스에 내놓기 전에 그 조합의 단가를 이번 달로 먼저 등록하세요. 단가는 이번 달 이후로만 넣을 수 있어 달이 바뀐 뒤에는 지난달 그 조합의 사용량에 단가를 매길 수 없습니다(시간 규칙). 이번 달 안에 등록하면 그 달에 이미 받은 사용량에도 적용됩니다.

단가가 빠진 조합 찾기

단가가 없는 조합의 사용량은 보내는 순간에는 오류가 나지 않습니다. 아래에서 찾습니다.

어디서	무엇이 보이나
`GET /v1/invoices/draft?month=YYYY-MM`	고객마다 `unpriced_usages`에 미터 code, 대상 속성, 조합, 수량이 나옵니다
콘솔 ‘이벤트 매핑 진단’ 화면	사유 ‘적용 단가 없음’으로 해당 이벤트가 나오고 ‘단가 등록하기’로 ‘요금 설계’ 화면에 갈 수 있습니다
콘솔 ‘청구 검토’ 화면	조회 조건 전체의 청구 예정액과 ‘단가 없는 조합’ 수가 나옵니다
`unbilled_usage_detected` 웹훅	매일 보내는 청구 제외 통보에 `unpriced_usages`가 실립니다(웹훅 이벤트 유형과 data)

청구 예정액 조회에 필요한 권한은 read입니다.

curl

curl "https://meterengine.com/v1/invoices/draft?month=2026-11" \
  -H "Authorization: Bearer me_test_xxxxxxxx"

lumen-fast에만 단가 2원이 있을 때 위 고객의 응답은 아래와 같습니다. lumen-pro와 {"model": null} 조합은 라인에 없고 unpriced_usages에만 나옵니다.

200 응답

{
  "month": "2026-11",
  "calculated_at": "2026-11-05T10:00:00+09:00",
  "auto_finalize_enabled": false,
  "auto_finalize_at": null,
  "auto_finalize_running": false,
  "total_amount": 2400,
  "customers": [
    {
      "customer_id": "8b0f4c2e-6d1a-4f3b-9a57-2c4e8d9b1f60",
      "customer_name": "서윤의 작업실",
      "amount": 2400,
      "lines": [
        {
          "billable_metric_code": "llm-input-tokens",
          "target_property": "input_tokens",
          "dimension_values": { "model": "lumen-fast" },
          "quantity": 1200,
          "unit_price": 2,
          "amount": 2400,
          "line_type": "per_unit",
          "tier_index": 0,
          "quantity_numerator": 1200,
          "quantity_denominator": 1
        }
      ],
      "unpriced_usages": [
        {
          "billable_metric_code": "llm-input-tokens",
          "target_property": "input_tokens",
          "dimension_values": { "model": null },
          "quantity": 100
        },
        {
          "billable_metric_code": "llm-input-tokens",
          "target_property": "input_tokens",
          "dimension_values": { "model": "lumen-pro" },
          "quantity": 300
        }
      ],
      "negative_usages": [],
      "auto_finalize_held": false
    }
  ]
}

위 예시의 미터는 unit_size가 1입니다. 응답 필드 전체는 API 참조의 GET /v1/invoices/draft를 보세요.

단가 없는 사용량이 남아 있어도 인보이스는 확정됩니다. 확정하면 그 사용량은 청구되지 않은 채 굳으므로 확정 전에 unpriced_usages가 비었는지 확인하세요(인보이스 수동 확정). 자동 확정이 켜진 서버에서는 청구 예정액이 0원이 아니면서 단가 없는 사용량이 있는 고객의 자동 확정이 보류되고, 그 고객의 auto_finalize_held가 true가 됩니다(자동 확정과 보류).

차원을 정할 때 주의할 것

차원 키는 이벤트를 받기 전에 정합니다. 이벤트가 들어온 미터는 이름만 바꿀 수 있어 나중에 차원 키를 더하거나 뺄 수 없습니다(미터 설계).
단가를 가를 필요가 없는 속성은 차원 키로 두지 않습니다. 사용자 ID처럼 값이 많은 속성을 차원 키로 두면 값마다 단가가 필요하고, 단가가 없는 값은 모두 청구에서 빠집니다.
단가가 같은 값끼리 묶고 싶다면 연동 코드에서 묶은 값(예: "tier": "standard")을 따로 속성으로 보내고 그 속성을 차원 키로 씁니다.

시작하기

개념

계정과 조직

인증

API 사용 기본

가격 설계

고객과 이벤트 연동

확인과 진단

청구 확정

결제 연동

웹훅

참고

차원과 속성 조합

조합은 어떻게 나뉘나

단가가 적용되는 규칙

값이 같은지 판단하는 방법

차원별 단가 등록하기

단가가 빠진 조합 찾기

차원을 정할 때 주의할 것

다음 단계

단가 모델과 버전

이벤트가 청구에 안 보일 때

​조합은 어떻게 나뉘나

​단가가 적용되는 규칙

​값이 같은지 판단하는 방법

​차원별 단가 등록하기

​단가가 빠진 조합 찾기

​차원을 정할 때 주의할 것

​다음 단계

단가 모델과 버전

이벤트가 청구에 안 보일 때

조합은 어떻게 나뉘나

단가가 적용되는 규칙

값이 같은지 판단하는 방법

차원별 단가 등록하기

단가가 빠진 조합 찾기

차원을 정할 때 주의할 것

다음 단계