> ## 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.

# 기본료와 최소 사용료

> 요금제로 월 기본료와 월 최소 사용료를 더하는 방법과 계산 순서, 적용 대상, 조회할 때의 함정을 설명합니다.

요금제는 사용료 위에 더하는 금액을 정합니다.

* **월 기본료**(`base_fee`): 그 달 사용량이 있는 고객에게 붙는 고정 금액입니다.
* **월 최소 사용료**(`minimum_amount`): 사용료가 이 금액보다 작으면 차액을 더해 최소 이 금액을 청구합니다.

사용료는 미터와 단가로 계산한 금액입니다. 단가는 [단가 모델과 버전](https://docs.meterengine.com/pricing/price-models.md)에서 다룹니다. 요금제가 없으면 사용료만 청구합니다.

고객, 미터, 단가, 요금제는 업무 환경마다 따로 만들어야 합니다. 자세한 내용은 [업무 환경](https://docs.meterengine.com/concepts/environments.md)을 보세요.

## 계산 순서

한 고객의 한 달 청구 예정액은 아래 순서로 만듭니다.

**1. 사용료를 더한다**

고객의 모든 미터, 모든 조합의 사용료 라인을 더합니다. 라인마다 10원 미만은 이미 버린 금액입니다.

**2. 최소 사용료와 비교한다**

사용료 합이 월 최소 사용료보다 작으면 그 차액으로 '최소 사용료 조정' 라인(`line_type`이 `minimum_adjustment`)을 하나 더합니다. 같거나 크면 이 라인은 생기지 않습니다.

**3. 기본료를 더한다**

월 기본료가 0원보다 크면 '기본료' 라인(`line_type`이 `base_fee`)을 하나 더합니다.

결과는 `max(사용료 합, 최소 사용료) + 기본료`입니다. 기본료는 최소 사용료를 채우는 데 쓰이지 않습니다.

| 사용료 합 | 최소 사용료 | 기본료 | 최소 사용료 조정 | 청구 예정액 |
| - | - | - | - | - |
| 100원 | 1,000원 | 500원 | 900원 | 1,500원 |
| 10,700원 | 12,000원 | 500원 | 1,300원 | 12,500원 |
| 15,000원 | 12,000원 | 500원 | 없음 | 15,500원 |

구간 단가가 들어간 예시를 처음부터 끝까지 계산하는 과정은 [금액 계산 따라가기](https://docs.meterengine.com/pricing/calculation-example.md)에 있습니다.

### 10원 미만 버림

금액은 라인마다 10원 미만을 버립니다. 월 기본료와 월 최소 사용료도 청구할 때 10원 미만을 버린 값을 씁니다. 자세한 규칙은 [예정액, 확정액, 수납액](https://docs.meterengine.com/concepts/amounts.md)을 보세요.

* 월 기본료 9,999원으로 저장하면 기본료 라인은 9,990원입니다.
* 월 최소 사용료 15,005원으로 저장하면 15,000원을 기준으로 차액을 계산합니다.
* 월 기본료가 10원보다 작으면(예: 5원) 기본료 라인이 생기지 않습니다.

API는 10원 단위가 아닌 값도 그대로 저장하고 응답에도 저장한 값을 돌려줍니다. 화면과 응답의 값이 청구 금액과 같도록 10원 단위로 넣으세요.

## 요금제가 붙는 고객

> [!WARNING]
>
> 요금제는 그 달 청구 수량이 0보다 큰 조합이 하나라도 있는 고객에게만 붙습니다. 그 달 이벤트가 없는 고객에게는 기본료도 최소 사용료도 청구하지 않습니다. 사용량과 관계없이 매달 고정 금액을 받는 구독 요금은 요금제로 만들 수 없습니다.

사용량이 있는지는 아래 기준으로 봅니다.

* 미터의 단위 변환과 반올림을 거친 수량으로 판단합니다. 수량이 반올림으로 0이 된 조합은 사용량으로 보지 않습니다.
* **단가가 없는 조합의 사용량도 사용량으로 셉니다.** 단가를 등록하지 않은 조합만 쓴 고객도 기본료가 붙고, 사용료가 0원이므로 최소 사용료 전액이 조정 라인으로 청구됩니다. 단가 없는 사용량은 청구 예정액 응답의 `unpriced_usages`에 나옵니다. 단가는 [차원과 속성 조합](https://docs.meterengine.com/pricing/dimensions.md)에서 조합마다 정확히 맞춰 등록하세요.
* 집계한 값이 음수인 조합(예: 상계 이벤트로 합이 음수가 된 조합)은 사용량으로 보지 않습니다. 이 조합은 0원으로 보고 라인에서 빠지며 `negative_usages`에 나옵니다.

사용량이 없어 공급가액이 0원인 고객에게는 확정해도 인보이스가 생기지 않습니다. 자세한 내용은 [인보이스 수동 확정](https://docs.meterengine.com/billing/finalize-invoices.md)을 보세요.

## 공통 요금제와 고객 요금제

| 종류 | `customer_id` | 적용 대상 |
| - | - | - |
| 공통 요금제 | 넣지 않음(`null`) | 고객 요금제가 없는 모든 고객 |
| 고객 요금제 | 고객 id(UUID) | 그 고객 한 명 |

* 고객 요금제가 있으면 그 고객에게는 공통 요금제를 쓰지 않습니다. 두 요금제를 더하지 않고 고객 요금제가 공통 요금제를 대신합니다. 예를 들어 공통 요금제가 기본료 500원, 최소 사용료 1,000원이고 고객 요금제가 기본료 200원, 최소 사용료 400원이면, 사용료 100원인 그 고객의 청구 예정액은 100원 + 조정 300원 + 기본료 200원 = 600원입니다.
* 그 달에 적용되는 고객 요금제 버전이 없으면(첫 버전의 시작 월 전, 모든 버전의 종료 월이 지난 뒤, 가장 늦은 버전이 보관으로 멈춘 뒤) 그 고객에게는 공통 요금제가 적용됩니다.
* 고객 id는 고객 등록 응답의 `id`입니다. 외부 고객 ID가 아닙니다. 자세한 내용은 [고객 등록과 ID 대응](https://docs.meterengine.com/integration/customers.md)을 보세요.

## 적용 기간과 버전

요금제는 월 단위 버전으로 관리합니다. 버전의 규칙은 단가와 같습니다. 월 버전의 일반 규칙은 [단가 모델과 버전](https://docs.meterengine.com/pricing/price-models.md)을 보세요.

| 필드 | 형식 | 설명 |
| - | - | - |
| `effective_from` | `YYYY-MM` | 적용 시작 월(KST)입니다. 생략하면 이번 달입니다. 이번 달보다 앞이면 `409 price_plan_history_immutable`로 거절됩니다. |
| `effective_until` | `YYYY-MM` | 적용 종료 월입니다. **이 달부터 적용되지 않습니다.** 생략하면 계속 적용합니다. 시작 월보다 뒤여야 하고 아니면 `400 validation_error`입니다. |
| `base_fee` | 0 이상의 정수(원) | 월 기본료입니다. 필수입니다. |
| `minimum_amount` | 0 이상의 정수(원) | 월 최소 사용료입니다. 필수입니다. 최소 사용료가 필요 없으면 0을 넣습니다. |

* 이번 달은 한국 시간(KST) 기준입니다. 매월 1일 00:00 KST가 지나면 지난달 요금제는 새로 넣거나 바꿀 수 없습니다. 시각 규칙은 [시간 규칙](https://docs.meterengine.com/concepts/time-rules.md)을 보세요.
* 같은 대상(공통 또는 같은 고객)과 같은 시작 월로 다시 등록하면 그 버전을 덮어쓰고 `201`을 돌려줍니다. 새 버전이 생기지 않습니다.
* 요금은 일할 계산하지 않습니다. 월 중간에 등록해도 그 달 전체에 적용되고, 이번 달에 시작한 버전을 덮어쓰면 이번 달 1일부터의 청구 예정액이 모두 바뀝니다.
* 한 달에 걸리는 버전이 여럿이면 시작 월이 가장 늦은 버전을 씁니다.
* 확정한 인보이스는 요금제를 바꿔도 바뀌지 않습니다.

> [!TIP]
>
> 다음 달부터 값을 바꾸려면 `effective_from`을 다음 달로 해서 새 버전을 등록합니다. 이번 달 청구 예정액은 그대로이고 다음 달부터 새 값이 적용됩니다.

## 요금제 등록하기

요금제 등록에는 admin 권한이 필요합니다. 권한은 [화면과 API, 권한](https://docs.meterengine.com/authentication/scopes.md)을 보세요.

> [tab] 콘솔
>
> **1. 요금 설계 화면을 연다**
>
> 왼쪽 메뉴 '과금과 연동'의 '요금 설계'를 엽니다. 화면 위 '업무 환경'이 요금제를 넣을 환경인지 확인합니다.
>
> **2. 적용 대상을 고른다**
>
> 공통 요금제는 '적용 대상'을 비워 둡니다. 고객 요금제는 '적용 대상'에서 고객을 고르고 '조건 적용'을 누릅니다.
>
> **3. 요금제 버전을 등록한다**
>
> '기본료와 최소 사용료' 구역의 '요금제 버전 등록'을 누르고 '적용 시작 월', '적용 종료 월'(선택), '월 기본료 (원)', '월 최소 사용료 (원)'을 넣어 저장합니다.
>
> **4. 적용 결과를 확인한다**
>
> '적용 월'을 고른 뒤 '기본료와 최소 사용료' 구역에 보이는 값이 그 달 실제 적용 기준입니다. 고객을 골랐는데 고객 요금제가 없으면 '공통 요금제 적용' 표시와 함께 공통 요금제가 보입니다.

> [tab] API
>
> `POST /v1/price-plans`로 등록합니다. 본문에서 `customer_id`를 빼면 공통 요금제입니다.
>
> ```bash curl theme={null}
> curl -X POST https://meterengine.com/v1/price-plans \
>   -H "Authorization: Bearer me_test_xxxxxxxx" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "effective_from": "2026-11",
>     "base_fee": 500,
>     "minimum_amount": 12000
>   }'
> ```
>
> ```javascript Node theme={null}
> const response = await fetch("https://meterengine.com/v1/price-plans", {
>   method: "POST",
>   headers: {
>     Authorization: "Bearer me_test_xxxxxxxx",
>     "Content-Type": "application/json",
>   },
>   body: JSON.stringify({
>     effective_from: "2026-11",
>     base_fee: 500,
>     minimum_amount: 12000,
>   }),
> });
> const plan = await response.json();
> ```
>
> 고객 요금제는 본문에 `"customer_id": "8b0f4c2e-6d1a-4f3b-9a57-2c4e8d9b1f60"`처럼 고객 id를 넣습니다.
>
> ```json 201 응답 theme={null}
> {
>   "id": "3f6c1d2a-9b4e-4c7a-8e15-6d2f0a9b7c34",
>   "customer_id": null,
>   "effective_from": "2026-11",
>   "effective_until": null,
>   "base_fee": 500,
>   "minimum_amount": 12000,
>   "archived_at": null,
>   "archived_from": null
> }
> ```
>
> 요금제 등록 요청에는 `Idempotency-Key`가 없습니다. 같은 본문을 다시 보내면 같은 버전을 같은 값으로 덮어쓰므로 결과가 같습니다. 요청별 중복 처리는 [멱등 규칙](https://docs.meterengine.com/api-basics/idempotency.md)을 보세요.

### 등록할 때의 오류

| 상태 | `code` | 원인과 처리 |
| - | - | - |
| 400 | `validation_error` | `base_fee`나 `minimum_amount`가 없거나 음수이거나, `effective_until`이 시작 월보다 뒤가 아닙니다. `errors`에 필드가 나옵니다. |
| 403 | `permission_denied` | 키에 admin 권한이 없습니다. |
| 404 | `customer_not_found` | `customer_id`의 고객이 이 업무 환경에 없습니다. |
| 409 | `price_plan_history_immutable` | `effective_from`이 이번 달보다 앞입니다. 이번 달 이후로 등록합니다. |
| 409 | `customer_archived` | 보관한 고객입니다. 고객을 복원한 뒤 등록합니다. |
| 409 | `archive_restoration_conflict` | 같은 대상과 같은 시작 월의 버전을 이번 달에 보관했고 그 버전이 이번 달에는 아직 적용됩니다. 그 버전을 복원한 뒤 다시 등록합니다. |

오류 응답 형식은 [오류 응답과 X-Request-ID](https://docs.meterengine.com/api-basics/errors.md)를 보세요.

## 요금제 조회와 함정

`GET /v1/price-plans`로 버전 이력을 조회합니다. read 권한이면 됩니다.

```bash curl theme={null}
curl "https://meterengine.com/v1/price-plans?status=all" \
  -H "Authorization: Bearer me_test_xxxxxxxx"
```

```json 200 응답 theme={null}
{
  "price_plans": [
    {
      "id": "3f6c1d2a-9b4e-4c7a-8e15-6d2f0a9b7c34",
      "customer_id": null,
      "effective_from": "2026-11",
      "effective_until": null,
      "base_fee": 500,
      "minimum_amount": 12000,
      "archived_at": null,
      "archived_from": null
    }
  ]
}
```

| 쿼리 | 설명 |
| - | - |
| `customer_id` | 그 고객의 요금제만 돌려줍니다. 생략하면 공통 요금제만 돌려줍니다. |
| `month` | `YYYY-MM`. 시작 월부터 종료 월 전까지에 그 달이 드는 버전만 돌려줍니다. |
| `status` | `active`(기본값), `archived`, `all`. 보관 여부로 거릅니다. |

결과는 시작 월 내림차순입니다. 아래 경우에 목록을 잘못 읽기 쉽습니다.

> [accordion] 고객을 지정했는데 공통 요금제가 안 보인다
>
> `customer_id`를 주면 그 고객의 요금제만 나오고 공통 요금제는 나오지 않습니다. 고객 요금제가 빈 배열이면 그 고객에게는 공통 요금제가 적용되므로 `customer_id` 없이 한 번 더 조회합니다.

> [accordion] 이번 달 청구에 쓰이는 요금제가 목록에 없다
>
> `status`를 생략하면 보관하지 않은 버전만 나옵니다. 이번 달에 보관한 버전은 이번 달까지 청구에 쓰이지만 기본 목록에는 나오지 않습니다. `month`를 주어도 보관 여부는 따로 거르므로 `status=all`을 함께 붙입니다.

> [accordion] 어느 버전이 그 달에 적용되는지 알고 싶다
>
> `status=all`과 `month=YYYY-MM`으로 조회하고 시작 월이 가장 늦은 버전부터 봅니다.
>
> * `archived_from`이 없거나 그 달보다 뒤이면 그 버전이 적용됩니다.
> * `archived_from`이 `effective_from`과 같으면 시작 전에 취소한 예약 버전입니다. 이 버전은 건너뛰고 그다음으로 늦은 버전을 봅니다.
> * 그 밖에 `archived_from`이 그 달과 같거나 앞이면 그 달에는 요금제가 없습니다. 이때 더 오래된 버전으로 돌아가지 않습니다.
>
> 고객 요금제가 이렇게 멈췄으면 그 고객에게는 공통 요금제가 적용됩니다. 콘솔 '요금 설계' 화면의 '기본료와 최소 사용료' 구역은 이 규칙으로 고른 결과를 보여 줍니다.

## 보관과 복원

요금제 버전을 보관하면 이번 달까지는 적용되고 다음 달부터 멈춥니다. 보관과 복원 규칙은 [바꾸기, 보관, 복원](https://docs.meterengine.com/pricing/changes-and-archiving.md)을 보세요.

API로 바로 확인할 엔드포인트와 필드는 [API 참조](https://docs.meterengine.com/api-reference/introduction.md)의 요금제 항목에 있습니다.


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