자동 확정과 보류

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

켜져 있는지 확인하기

청구 예정액을 조회합니다

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

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

auto_finalize_enabled를 봅니다

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

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

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

꺼져 있을 때 (false)
켜져 있을 때 (true)

달이 끝난 뒤 콘솔의 ‘월 전체 확정’ 버튼이나 POST /v1/invoices?month=YYYY-MM으로 직접 확정합니다. 확정하지 않으면 인보이스가 생기지 않고 결제도 요청할 수 없습니다. 절차는 인보이스 수동 확정을 보세요.

매시 정각에 확정 시각(다음 달 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은 마감 시각입니다. 마감 규칙은 시간 규칙을 보세요.
대상 고객: 그 달 집계 마감 전에 등록된 고객입니다. 이미 직접 확정한 고객은 건너뛰므로, 자동 확정과 직접 확정을 함께 써도 인보이스가 겹치지 않습니다.
업무 환경: 업무 환경마다 따로 확정합니다. 테스트 환경과 실제 환경도 각각 확정합니다. 한 환경의 결과는 다른 환경에 영향을 주지 않습니다. 업무 환경은 업무 환경을 보세요.

고객마다의 결과

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

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

자동 확정의 결과를 알리는 통보는 없습니다. 확정 결과는 GET /v1/invoices?month=YYYY-MM으로 확인합니다. 통보 유형은 웹훅 이벤트 유형과 data를 보세요.

보류

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

보류될 고객 미리 보기

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

200 응답 (자동 확정이 켜져 있을 때)

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

보류를 피하는 법

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

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

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

unpriced_usages의 billable_metric_code와 dimension_values 조합에 이번 달부터 적용되는 단가를 등록합니다. 조합 규칙은 차원과 속성 조합, 단가 등록은 단가 모델과 버전을 보세요.

다시 조회해 확인합니다

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

보류된 뒤 처리하기

보류된 고객을 확인합니다

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

그 달을 직접 확정합니다

콘솔의 ‘월 전체 확정’이나 POST /v1/invoices?month=YYYY-MM으로 확정합니다. 이미 확정된 고객은 건너뛰므로 남은 고객만 확정됩니다.

단가 없는 사용량은 청구되지 않은 채로 확정되며, 확정한 뒤에는 되돌릴 수 없습니다.

응답의 자동 확정 필드

boolean

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

string | null

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

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

boolean

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

boolean

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

object[]

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

확정한 뒤

자동 확정이 켜져 있어도 결제는 자동으로 시작되지 않습니다. 확정한 뒤 인보이스마다 결제를 요청해야 합니다. 첫 결제 요청과 결과 확인을 보세요.
확정한 인보이스는 되돌릴 수 없습니다. 확정 뒤 바뀌는 것과 안 바뀌는 것을 보세요.

시작하기

개념

계정과 조직

인증

API 사용 기본

가격 설계

고객과 이벤트 연동

확인과 진단

청구 확정

결제 연동

웹훅

참고

자동 확정과 보류

켜져 있는지 확인하기

켜져 있을 때의 동작

고객마다의 결과

보류

보류될 고객 미리 보기

보류를 피하는 법

보류된 뒤 처리하기

응답의 자동 확정 필드

확정한 뒤

​켜져 있는지 확인하기

​켜져 있을 때의 동작

​고객마다의 결과

​보류

​보류될 고객 미리 보기

​보류를 피하는 법

​보류된 뒤 처리하기

​응답의 자동 확정 필드

​확정한 뒤

켜져 있는지 확인하기

켜져 있을 때의 동작

고객마다의 결과

보류

보류될 고객 미리 보기

보류를 피하는 법

보류된 뒤 처리하기

응답의 자동 확정 필드

확정한 뒤