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

# 자동 확정과 보류

> 서버의 자동 확정이 켜져 있는지 확인하는 법과 켜져 있을 때의 시각, 결과, 보류 조건을 설명합니다.

자동 확정은 MeterEngine 서버 전체에 적용되는 설정이라 도입사가 켜거나 끌 수 없습니다. 지금 쓰는 서버에서 켜져 있는지는 청구 예정액 조회(`GET /v1/invoices/draft`) 응답의 `auto_finalize_enabled`로 확인합니다. 직접 확정하는 방법은 [인보이스 수동 확정](https://docs.meterengine.com/billing/finalize-invoices.md)을 보세요.

## 켜져 있는지 확인하기

**1. 청구 예정액을 조회합니다**

read 권한 키로 `GET /v1/invoices/draft`를 부릅니다. `month`를 빼면 이번 달입니다.

```bash theme={null}
curl "https://meterengine.com/v1/invoices/draft?month=2026-11" \
  -H "Authorization: Bearer me_test_xxxxxxxx"
```

**2. auto\_finalize\_enabled를 봅니다**

`true`면 자동 확정이 켜져 있고, `false`면 꺼져 있습니다. 꺼져 있으면 `auto_finalize_at`은 `null`, `auto_finalize_running`과 고객마다의 `auto_finalize_held`는 `false`입니다.

**3. 콘솔에서도 확인할 수 있습니다**

'청구 검토' 화면에 '다음 자동 확정 2026-12-01 14:00 KST'나 '자동 확정 진행 중'이 보이면 켜져 있는 것입니다. 이 표시가 없으면 꺼져 있거나 그 달에 남은 자동 확정이 없는 것이니 API의 `auto_finalize_enabled`로 구분합니다.

> [tab] 꺼져 있을 때 (false)
>
> 달이 끝난 뒤 콘솔의 '월 전체 확정' 버튼이나 `POST /v1/invoices?month=YYYY-MM`으로 직접 확정합니다. 확정하지 않으면 인보이스가 생기지 않고 결제도 요청할 수 없습니다. 절차는 [인보이스 수동 확정](https://docs.meterengine.com/billing/finalize-invoices.md)을 보세요.

> [tab] 켜져 있을 때 (true)
>
> 매시 정각에 확정 시각(다음 달 1일 14:00 KST)이 지난 달을 고객마다 확정합니다. 단가 없는 사용량이 있는 고객은 보류되고 다시 시도하지 않으므로 직접 확정합니다. 실패한 고객은 다음 정시에 다시 시도합니다. 다음 확정 시각은 `auto_finalize_at`, 보류될 고객은 `auto_finalize_held`로 미리 봅니다. 아래 절에서 자세히 설명합니다.

## 켜져 있을 때의 동작

* **시각:** 매시 정각(KST)에 돌며, 확정 시각인 다음 달 1일 14:00 KST가 지난 달을 다룹니다. 10월분은 2026-11-01 14:00 KST부터 확정됩니다.
* **금액에 드는 이벤트:** 그 달에 발생했고 집계 마감(다음 달 1일 13:00 KST) 전에 받은 이벤트로 확정합니다. 인보이스의 `cutoff_at`은 마감 시각입니다. 마감 규칙은 [시간 규칙](https://docs.meterengine.com/concepts/time-rules.md)을 보세요.
* **대상 고객:** 그 달 집계 마감 전에 등록된 고객입니다. 이미 직접 확정한 고객은 건너뛰므로, 자동 확정과 직접 확정을 함께 써도 인보이스가 겹치지 않습니다.
* **업무 환경:** 업무 환경마다 따로 확정합니다. 테스트 환경과 실제 환경도 각각 확정합니다. 한 환경의 결과는 다른 환경에 영향을 주지 않습니다. 업무 환경은 [업무 환경](https://docs.meterengine.com/concepts/environments.md)을 보세요.

### 고객마다의 결과

| 결과 | 조건 | 그 뒤 |
| - | - | - |
| 확정 | 금액이 0원이 아니고 단가 없는 사용량이 없습니다 | 인보이스가 생깁니다. |
| 확정 없이 끝남 | 그 달 이벤트가 없거나 금액이 0원입니다 | 인보이스를 만들지 않고 다시 보지 않습니다. 0원 고객은 직접 확정해도 인보이스가 생기지 않습니다. |
| 보류 | 금액이 0원이 아닌데 단가 없는 사용량이 있습니다 | 다시 시도하지 않습니다. 직접 확정해야 합니다. |
| 실패 | 확정 중 오류가 났습니다 | 다음 정시에 다시 시도합니다. |

> [!WARNING]
>
> 자동 확정이 켜지면, 확정 시각이 이미 지난 달 가운데 아직 확정하지 않은 고객과 달도 다음 정시에 함께 확정됩니다. 테스트 환경에 확정하지 않고 둔 지난달이 있으면 그 달도 확정되며 되돌릴 수 없습니다.

자동 확정의 결과를 알리는 통보는 없습니다. 확정 결과는 `GET /v1/invoices?month=YYYY-MM`으로 확인합니다. 통보 유형은 [웹훅 이벤트 유형과 data](https://docs.meterengine.com/webhooks/events.md)를 보세요.

## 보류

단가 없는 사용량이 있는 고객을 그대로 확정하면 그 사용량이 청구되지 않습니다. 자동 확정은 이런 고객을 확정하지 않고 보류합니다. 끝난 달에는 단가를 새로 넣을 수 없어 다시 계산해도 결과가 같으므로, 보류된 고객은 다시 시도하지 않습니다. 단가를 넣을 수 있는 기간은 [시간 규칙](https://docs.meterengine.com/concepts/time-rules.md)을 보세요.

### 보류될 고객 미리 보기

청구 예정액 응답의 고객마다 `auto_finalize_held`가 `true`면, 지금 확정 시각이 온다고 할 때 보류될 고객입니다. 그 고객의 `unpriced_usages`에 단가가 없는 미터와 조합, 수량이 나옵니다.

```json 200 응답 (자동 확정이 켜져 있을 때) theme={null}
{
  "month": "2026-11",
  "calculated_at": "2026-11-20T10:00:00+09:00",
  "auto_finalize_enabled": true,
  "auto_finalize_at": "2026-12-01T14:00:00+09:00",
  "auto_finalize_running": false,
  "total_amount": 12000,
  "customers": [
    {
      "customer_id": "0b8e4f2a-7c1d-4e5b-a9f3-2d6c8e1b4a70",
      "customer_name": "에이컴퍼니",
      "amount": 12000,
      "lines": [
        {
          "billable_metric_code": "llm_tokens",
          "target_property": "tokens",
          "dimension_values": { "model": "small" },
          "quantity": 1200,
          "unit_price": 10,
          "amount": 12000,
          "line_type": "per_unit",
          "tier_index": 0,
          "quantity_numerator": 1200,
          "quantity_denominator": 1
        }
      ],
      "unpriced_usages": [
        {
          "billable_metric_code": "llm_tokens",
          "target_property": "tokens",
          "dimension_values": { "model": "large" },
          "quantity": 300
        }
      ],
      "negative_usages": [],
      "auto_finalize_held": true
    }
  ]
}
```

`auto_finalize_held`는 조회한 순간까지 받은 이벤트로 계산합니다. 달이 끝나기 전에는 이벤트와 단가에 따라 바뀝니다. 콘솔 '청구 검토' 화면에서는 이번 달 고객에 '자동 확정 보류: 단가 없는 사용량' 표시가, 끝난 달 고객에 '자동 확정 보류: 수동 확정 필요' 표시가 붙습니다.

### 보류를 피하는 법

**1. 달이 끝나기 전에 보류될 고객을 찾습니다**

이번 달 청구 예정액에서 `auto_finalize_held`가 `true`인 고객을 찾습니다.

**2. 빠진 조합의 단가를 등록합니다**

`unpriced_usages`의 `billable_metric_code`와 `dimension_values` 조합에 이번 달부터 적용되는 단가를 등록합니다. 조합 규칙은 [차원과 속성 조합](https://docs.meterengine.com/pricing/dimensions.md), 단가 등록은 [단가 모델과 버전](https://docs.meterengine.com/pricing/price-models.md)을 보세요.

**3. 다시 조회해 확인합니다**

청구 예정액을 다시 조회해 그 고객의 `unpriced_usages`가 빈 배열이고 `auto_finalize_held`가 `false`인지 확인합니다.

### 보류된 뒤 처리하기

**1. 보류된 고객을 확인합니다**

끝난 달의 청구 예정액을 조회합니다. 자동 확정된 고객은 나오지 않고, 남은 고객 가운데 `auto_finalize_held`가 `true`인 고객이 보류된 고객입니다.

**2. 그 달을 직접 확정합니다**

콘솔의 '월 전체 확정'이나 `POST /v1/invoices?month=YYYY-MM`으로 확정합니다. 이미 확정된 고객은 건너뛰므로 남은 고객만 확정됩니다.
\[!WARNING] 단가 없는 사용량은 청구되지 않은 채로 확정되며, 확정한 뒤에는 되돌릴 수 없습니다.

## 응답의 자동 확정 필드

**auto\_finalize\_enabled** `boolean`

서버의 자동 확정이 켜져 있으면 `true`.

**auto\_finalize\_at** `string | null`

이 달을 다음에 자동 확정하는 시각(KST, `+09:00`). 값은 아래와 같이 정해집니다.

* 그 달의 확정 시각(다음 달 1일 14:00 KST) 전이면 그 시각입니다.
* 확정 시각이 지났고, 그 업무 환경에서 아직 이 달을 다 처리하지 않았거나 마지막 시도가 실패인 고객이 있으면 다음 정시입니다.
* 다 처리했고 실패가 없으면 `null`입니다. 보류된 고객만 남아도 `null`입니다.
* 확정 시각이 지났고, 그 업무 환경의 첫 고객을 등록하기 전에 집계 마감이 지난 달이면 `null`입니다.
* 자동 확정이 꺼져 있으면 `null`입니다.

**auto\_finalize\_running** `boolean`

자동 확정이 지금 돌고 있고 확정 시각이 지난 이 달을 그 업무 환경에서 아직 다 처리하지 않았으면 `true`. 꺼져 있으면 `false`입니다.

**customers\[].auto\_finalize\_held** `boolean`

자동 확정이 켜져 있고, 금액이 0원이 아니면서 단가 없는 사용량이 있어 이 고객을 보류하면 `true`.

**customers\[].unpriced\_usages** `object[]`

단가가 없어 금액에서 빠진 조합의 사용량. 각 항목에 `billable_metric_code`, `target_property`, `dimension_values`, `quantity`가 있습니다. 없으면 빈 배열입니다.

## 확정한 뒤

*  자동 확정이 켜져 있어도 결제는 자동으로 시작되지 않습니다. 확정한 뒤 인보이스마다 결제를 요청해야 합니다. [첫 결제 요청과 결과 확인](https://docs.meterengine.com/payments/charging.md)을 보세요.
* 확정한 인보이스는 되돌릴 수 없습니다. [확정 뒤 바뀌는 것과 안 바뀌는 것](https://docs.meterengine.com/billing/after-finalization.md)을 보세요.


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