> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 차원과 속성 조합

> 모델이나 지역처럼 이벤트 속성 값마다 다른 단가를 매기는 방법과, 단가가 빠진 조합을 찾는 방법을 설명합니다.

같은 토큰이라도 모델마다 값이 다르면 미터에 차원 키를 두고 속성 값 조합마다 단가를 등록합니다. 차원 키는 미터의 `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개 필요합니다.
* 차원 키가 없는 미터는 조합이 `{}` 하나뿐입니다.

## 단가가 적용되는 규칙

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

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

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

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

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

같은 조합에 그 고객 전용 단가가 있으면 그것을, 없으면 공통 단가를 씁니다. 고객 단가는 [단가 모델과 버전](https://docs.meterengine.com/pricing/price-models.md)에서 다룹니다.

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

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

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

## 차원별 단가 등록하기

미터의 `dimension_properties`가 `["model"]`일 때 모델마다 단가를 하나씩 등록합니다. 필요 권한은 admin입니다([화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md)).

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

> [tab] API
>
> ```bash curl theme={null}
> 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
>   }'
> ```
>
> ```javascript Node theme={null}
> 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`이어도 둘은 서로 다른 자리에 들어갑니다.

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

## 단가가 빠진 조합 찾기

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

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

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

```bash curl theme={null}
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`에만 나옵니다.

```json 200 응답 theme={null}
{
  "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 참조](https://docs.meterengine.com/api-reference/introduction.md)의 `GET /v1/invoices/draft`를 보세요.

> [!WARNING]
>
> 단가 없는 사용량이 남아 있어도 인보이스는 확정됩니다. 확정하면 그 사용량은 청구되지 않은 채 굳으므로 확정 전에 `unpriced_usages`가 비었는지 확인하세요([인보이스 수동 확정](https://docs.meterengine.com/billing/finalize-invoices.md)). 자동 확정이 켜진 서버에서는 청구 예정액이 0원이 아니면서 단가 없는 사용량이 있는 고객의 자동 확정이 보류되고, 그 고객의 `auto_finalize_held`가 `true`가 됩니다([자동 확정과 보류](https://docs.meterengine.com/billing/auto-finalization.md)).

## 차원을 정할 때 주의할 것

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

## 다음 단계

> [card] [단가 모델과 버전](https://docs.meterengine.com/pricing/price-models.md)
>
> 단일 단가, 구간 단가, 월 버전과 고객 단가

> [card] [이벤트가 청구에 안 보일 때](https://docs.meterengine.com/troubleshooting/events-not-billed.md)
>
> 증상별로 원인을 좁히는 방법


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.