Chargebee Unbilled Charges API 대사 체크리스트 2026, charge 생성·조회부터 invoice 반영까지 확인하는 법

B2B SaaS에서 사용량이나 일회성 금액을 다음 invoice에 포함하려고 하면, 결제 API 응답과 최종 청구서 사이에 중간 객체가 생깁니다. Chargebee의 unbilled_charge가 대표적인 예입니다. charge가 생성됐다는 사실만으로 invoice에 정상 반영됐다고 볼 수 없고, 반대로 invoice에 금액이 있다고 해서 어떤 원본 사용량이나 운영 요청에서 만들어졌는지 자동으로 설명되는 것도 아닙니다.

Chargebee 공식 API 문서에서 unbilled charge는 invoice_immediately를 사용하지 않고 보류된 charge로 설명되며, subscription 또는 customer invoice가 만들어질 때 관련 unbilled charges가 포함될 수 있다고 안내합니다. 다만 실제 동작은 API 버전, site 설정, 제품 카탈로그와 invoice 생성 경로에 따라 달라질 수 있습니다. 따라서 이 글은 unbilled_charge → invoice line item → invoice 연결을 확인하는 운영 대사에 집중합니다.

이 글의 대상은 Chargebee API v2와 제품 usage ledger를 이미 운영 중인 팀입니다. unbilled charge를 사용량 event, 최종 invoice, 결제 성공과 같은 개념으로 합치지 않습니다. 본문에서 말하는 create·list·delete는 내부 운영 흐름을 설명하는 표현이며, 실제 endpoint·메서드·삭제 또는 void 동작의 지원 범위와 파라미터를 일반화하지 않습니다. 사용 중인 Chargebee 사이트, 제품 카탈로그, API 버전의 현재 공식 문서를 반드시 다시 확인해야 합니다.

이 글은 회계·세무·법률 자문이나 청구 금액의 정답을 제공하지 않습니다. 계약, 환불, 크레딧, proration, 매출 인식은 회사의 청구 정책과 전문가 검토를 따라야 합니다.

pause 중 결제와 서비스 접근을 분리하는 정책은 B2B SaaS billing pause와 service access 정책 분리 매트릭스의 범위입니다. 일반적인 사용량 초과와 업셀 분리는 B2B SaaS 사용량 초과·usage-based billing 추적 감사 체크리스트에서 확인할 수 있습니다. 결제 실패와 dunning 자동화는 B2B SaaS 결제 실패·dunning 자동화 체크리스트로, webhook replay와 invoice·entitlement 대사는 결제 webhook replay 검증 로그·대사 리포트 템플릿으로 분리합니다.

Unbilled charge와 invoice를 먼저 구분합니다

Chargebee의 unbilled charge는 고객이나 subscription에 귀속된 청구 후보를 보류해 두는 객체입니다. invoice가 생성될 때 관련 charge가 포함될 수 있지만, 보류 객체와 최종 invoice는 생명주기와 확인 시점이 다릅니다.

운영 화면에서 다음 상태를 같은 billed=true로 합치지 않는 것이 출발점입니다.

단계	의미	확인할 원본
usage_recorded	제품 사용량 또는 일회성 청구 사유가 내부 원장에 생성됨	usage ledger, request ID
charge_requested	Chargebee에 unbilled charge 생성 요청을 보냄	API request log
charge_created	Chargebee charge ID와 응답을 받음	unbilled charge 원문
charge_listed	고객·subscription 범위 조회에서 다시 확인됨	list 결과, 조회 시각
invoice_included	invoice line item에 포함된 것으로 확인됨	invoice와 line item
invoice_finalized	최종 청구서가 확정됨	invoice status, 확정 시각
paid	결제 성공까지 확인됨	transaction·payment 상태

charge_created는 invoice_included가 아니고 invoice_finalized도 아닙니다. 고객이 자동 수집 설정을 사용하지 않는다면 invoice 생성과 결제 성공 사이에도 시간이 남을 수 있습니다. 단계별 상태를 분리해야 고객 문의에 “금액이 청구 후보로 생성됐다”, “invoice에 포함됐다”, “결제가 완료됐다”를 정확히 구분해 답할 수 있습니다.

1. 공통 대사 키를 먼저 보존합니다

금액 차이를 찾기 전에 제품 로그와 Chargebee 원문 객체를 다시 연결할 수 있어야 합니다. 다음 필드를 내부 원장에 보존하는 편이 좋습니다.

• 내부 usage_event_id 또는 billing_request_id
• Chargebee unbilled_charge.id
• customer_id
• subscription_id
• date_from, date_to
• unit_amount, quantity, amount
• currency_code
• discount_amount
• is_voided, voided_at
• created_at, updated_at
• API request ID, response snapshot, retry count
• policy_version와 environment

Chargebee 공식 API 문서는 unbilled charge의 id, customer_id, subscription_id, 기간, 단가, 수량, 총액, 통화, voided 상태와 생성·수정 시각을 설명합니다. 모든 계정에서 모든 필드가 같은 방식으로 채워진다고 가정하지 말고, nullable 여부와 사이트 설정을 실제 응답으로 확인하십시오.

customer_id만 있고 subscription_id가 없는 charge가 허용되는지, customer invoice에 어떻게 포함되는지는 사용 중인 청구 흐름에서 별도 확인해야 합니다. 누락된 subscription ID를 내부에서 임의로 채워 넣으면 나중에 invoice 귀속을 잘못 설명할 수 있습니다.

2. 생성 요청과 생성 결과를 분리합니다

일회성 청구나 사용량 반영 로직은 보통 “요청 생성 → API 응답 → 내부 상태 저장” 순서로 실행됩니다. 네트워크 timeout이 발생했다고 무조건 실패로 기록하면 재시도 중복이 생길 수 있고, 반대로 응답을 받지 못했다고 계속 재전송하면 같은 고객에게 중복 charge가 생길 수 있습니다. 아래는 특정 endpoint의 보편적 동작을 단정하는 절차가 아니라, 현재 계정에서 실제로 호출하는 operation과 응답을 대조하는 방법입니다.

요청 로그에는 다음을 남깁니다.

확인 항목	대사 질문
요청 목적	어떤 usage event·고객 요청에서 만들어졌는가
customer/subscription	청구 대상이 제품 계정과 일치하는가
기간	date_from·date_to가 사용량 발생 기간과 맞는가
금액	minor unit·decimal 표현을 혼동하지 않았는가
통화	currency_code가 price·invoice 통화와 같은가
설명	고객이 invoice에서 이해할 수 있는 description인가
retry	timeout 뒤 같은 요청을 어떻게 판정했는가
mode	test site와 live site가 섞이지 않았는가

API 응답이 성공했다면 charge ID, HTTP 상태, 응답 시각, 원문 응답을 저장합니다. 비밀번호나 API secret은 저장하지 말고, 고객 개인정보가 들어간 description을 분석 로그에 그대로 복제하지 않는 편이 안전합니다.

3. list 조회로 생성 결과를 재확인합니다

생성 응답을 저장하는 것만으로는 운영 대사가 끝나지 않습니다. 해당 site와 API 버전에서 제공되는 조회 operation을 사용하는 경우, customer·subscription·기간 범위에서 해당 charge가 다시 보이는지 확인합니다. 조회 시점과 필터를 저장해야 “없다”는 결론이 실제 누락인지, 잘못된 필터인지 구분할 수 있습니다.

조회 결과는 다음처럼 분류할 수 있습니다.

조회 결과	판정	다음 액션
생성 ID가 동일하게 발견됨	charge_visible	invoice 포함 여부로 진행
생성 응답은 있으나 list에 없음	charge_not_listed	site·필터·지연·삭제 상태 재확인
같은 내부 요청에 여러 ID가 있음	charge_duplicate_candidate	retry와 중복 방지 키 조사
customer 범위에는 있으나 subscription이 다름	subscription_mapping_mismatch	귀속 정책과 원문 확인
voided charge만 남음	charge_voided	대체 charge·proration 근거 확인

list API 결과가 비어 있다고 곧바로 charge 생성 실패라고 하지 마십시오. 기간, customer ID, subscription ID, 페이지네이션, API 버전, test/live site를 먼저 확인하고 조회 시각을 기준으로 다시 요청합니다.

4. 기간과 시간대를 대조합니다

Chargebee API의 charge 기간 필드는 UTC timestamp로 표현될 수 있습니다. 제품 화면이 한국 시간이나 고객 현지 시간으로 표시되면 하루의 시작·끝이 달라 보일 수 있습니다. 월말 사용량과 다음 달 첫 사용량을 합치지 않으려면 원문 timestamp와 표시 timezone을 함께 저장해야 합니다.

대사 표에는 다음 값을 둡니다.

• 제품 이벤트의 occurred_at
• 청구 원장의 billing_period_start, billing_period_end
• Chargebee date_from, date_to
• invoice line item의 period
• charge 생성·수정 시각
• 조회와 대사 작업의 실행 시각

기간 차이는 아래 코드로 좁혀 기록할 수 있습니다.

코드	의미
period_exact	제품·charge·invoice 기간이 정책상 일치
period_boundary_shift	월말·timezone 경계가 다름
period_partial_proration	부분 기간 또는 proration으로 설명 가능
period_missing	원문 기간 또는 내부 기준이 없음
period_unknown	정책과 실제 결과를 아직 판정하지 못함

period_unknown을 정상으로 닫지 마십시오. 청구 기간이 확정되지 않은 charge는 invoice 반영 여부를 판단하기 전 billing owner의 확인 대상으로 남기는 편이 안전합니다.

5. amount와 currency를 여러 표현으로 비교합니다

Chargebee API 문서에는 unit_amount, amount, currency_code와 함께 multi-decimal pricing이 활성화된 경우 decimal 표현이 제공될 수 있다고 설명합니다. 내부 원장과 invoice가 서로 다른 단위로 금액을 저장하면 100배 차이 또는 반올림 차이를 중복 오류로 오인할 수 있습니다.

내부 대사에서는 다음을 별도로 계산합니다.

expected_amount = 내부 정책을 통과한 단가 × 수량 - 할인·크레딧 조정
charge_amount   = Chargebee unbilled charge의 amount 또는 decimal amount
invoice_amount  = invoice line item에 반영된 금액

이 식은 일반적인 대사 구조의 예시이며 tiered pricing, minimum, tax, proration, credit note를 자동으로 포함하지 않습니다. 다음 항목을 원문과 함께 저장하십시오.

• minor unit인지 major unit인지
• quantity와 quantity_in_decimal의 사용 여부
• 단가와 총액의 반올림 규칙
• discount와 credit 적용 시점
• currency와 multi-currency 정책
• tax를 usage charge 자체와 함께 계산하는지 여부

비교 결과	우선 확인할 원인
charge와 invoice가 모두 같음	대사 통과 후 payment 상태 확인
charge만 있고 invoice가 없음	invoice 생성 시점·귀속·보류 정책
invoice 금액이 더 큼	중복 charge·다른 line item·세금·proration
invoice 금액이 더 작음	discount·credit·voided·부분 반영
통화가 다름	customer·price·site currency 설정

6. invoice 포함 여부를 독립적으로 검증합니다

Chargebee 공식 안내는 subscription invoice가 생성될 때 해당 subscription의 unbilled charges가 포함될 수 있고, customer invoice에는 관련 subscription의 charges가 포함될 수 있다고 설명합니다. 이 “포함될 수 있음”을 모든 계정의 자동 보장으로 바꾸지 말고, 실제 invoice line item과 현재 site 설정에서 확인해야 합니다. charge ID가 line item에 직접 노출되는지와 연결 방식도 제품·API 응답에 따라 다를 수 있습니다.

invoice 대사에서 보존할 값은 다음과 같습니다.

• invoice ID와 customer·subscription ID
• invoice 생성·확정 시각
• line item ID와 description
• charge와 연결되는 원본 reference 또는 내부 매핑
• line item period와 amount
• currency, discount, credit, tax 관련 조정
• invoice 상태와 payment transaction 상태

unbilled charge의 ID가 invoice line item에 직접 보이지 않는 제품 흐름이라면, 내부 billing_request_id와 기간·금액·고객·설명 조합으로 매핑하되 매핑 규칙과 신뢰도를 남겨야 합니다. 추정 매핑을 확정 매핑처럼 표시하면 invoice 문의를 재현하기 어렵습니다.

7. voided와 delete를 같은 의미로 쓰지 않습니다

Chargebee API의 unbilled charge에는 is_voided와 voided_at이 있을 수 있으며, 공식 설명은 proration 과정에서 기존 charge가 voided되고 다른 charge로 수정될 수 있음을 안내합니다. 따라서 이전 charge가 목록에서 사라졌다는 이유만으로 삭제·누락으로 단정하지 마십시오.

내부 상태는 최소한 아래처럼 분리하는 편이 좋습니다.

상태	운영상 해석
active_unbilled	아직 유효한 보류 charge 후보
voided_replaced	기존 charge가 무효화되고 대체 charge가 있음
deleted_or_hidden	API 조회에서 더 이상 원문이 보이지 않음
invoice_consumed	invoice line item으로 소비된 것으로 확인
unknown	삭제·void·필터·지연을 판정하지 못함

해당 site와 API 버전에서 삭제 operation을 실제로 지원하고 호출하는 운영 흐름이라면 delete 요청의 actor, reason, request ID, 실행 시각과 삭제 전 snapshot을 남깁니다. “잘못 만든 charge를 삭제하면 끝”이라는 방식은 invoice가 이미 생성됐거나 대체 charge가 만들어진 경우에 원인 추적을 끊을 수 있습니다. 삭제와 is_voided 전환은 같은 동작이라고 가정하지 말고 원문 응답과 현재 공식 문서로 구분하십시오.

8. invoice 생성 전 hard stop을 둡니다

다음 조건 중 하나라도 충족하면 invoice 생성 또는 자동 확정을 바로 진행하지 않고 수동 검토로 보내는 규칙을 둘 수 있습니다.

• customer·subscription 귀속이 확정되지 않음
• 기간이 비어 있거나 제품 billing period와 다름
• currency가 price·invoice와 다름
• 같은 billing_request_id에 charge ID가 여러 개임
• is_voided=true인데 대체 charge를 찾지 못함
• charge 금액과 expected amount 차이가 허용 범위를 넘음
• invoice에 포함됐는지 아직 확인하지 못함
• test/live site 또는 business entity가 섞임
• 삭제·수정 작업의 actor와 이유가 없음

hard stop을 해제할 때는 담당자, 확인한 공식 문서·계정 설정, 원문 ID, 보정 내용과 시간을 evidence에 남깁니다. 자동화가 알아서 예외를 “정상”으로 닫게 두지 않는 것이 중요합니다.

9. 운영 대사 판정 코드를 좁게 유지합니다

금액 차이를 모두 billing_error로 저장하면 다음 담당자가 다시 처음부터 조사해야 합니다. 아래처럼 원인 후보를 분리합니다.

판정 코드	의미
unbilled_charge_missing	내부 원장에는 있으나 Chargebee 생성 결과가 없음
unbilled_charge_duplicate	같은 요청에 중복 charge 후보가 있음
customer_subscription_mismatch	고객·구독 귀속이 내부 기록과 다름
charge_period_mismatch	date_from·date_to가 정책 기간과 다름
charge_amount_mismatch	단가·수량·할인 조합으로 설명되지 않는 차이
charge_not_in_invoice	charge는 보이지만 invoice line item에 없음
charge_voided_without_replacement	voided 후 대체 charge를 찾지 못함
invoice_payment_pending	invoice 포함은 됐지만 결제 성공 전 상태
mapping_unknown	원본 간 연결을 확정할 수 없음

mapping_unknown은 실패도 성공도 아닙니다. SLA와 owner를 부여한 조사 대기 상태로 남겨야 합니다.

10. 일별·월말 체크리스트

생성·조회

• [ ] 내부 usage event 또는 billing request ID가 있다.
• [ ] Chargebee charge ID와 API 원문 응답을 보존했다.
• [ ] customer·subscription·business entity mapping을 확인했다.
• [ ] create 결과와 list 조회 결과를 같은 필터·시각 기준으로 대조했다.
• [ ] retry와 duplicate 후보를 분리했다.

금액·기간

• [ ] date_from, date_to와 billing period를 UTC 기준으로 비교했다.
• [ ] minor unit·decimal 표현·반올림 규칙을 확인했다.
• [ ] unit amount·quantity·amount·discount·credit을 분리했다.
• [ ] currency와 price·invoice의 통화가 일치한다.
• [ ] proration·minimum·tiered pricing을 일반 누락으로 오인하지 않았다.

invoice 반영

• [ ] invoice ID·line item ID와 charge 또는 내부 request를 연결했다.
• [ ] charge가 invoice에 포함됐다는 근거를 실제 line item에서 확인했다.
• [ ] invoice 생성·확정과 payment 성공을 별도 상태로 기록했다.
• [ ] voided charge의 대체 charge와 사유를 확인했다.
• [ ] 예외 코드마다 owner·next review time·evidence가 있다.

결론

Chargebee unbilled charge 대사의 핵심은 “charge가 생성됐는가”가 아니라, 어느 고객의 어느 subscription에 어떤 기간·통화·금액으로 생성됐고, 어떤 invoice line item에 포함됐는가를 재현하는 데 있습니다.

생성 요청, 응답 원문, list 조회, voided 상태, invoice line item, payment 결과를 각각 보존하면 중복·누락·기간 불일치·결제 대기 상태를 분리할 수 있습니다. 특히 unbilled_charge를 최종 invoice나 결제 성공과 같은 상태로 다루지 말고, 제품 정책과 현재 Chargebee site 설정을 기준으로 매핑을 검증하십시오.

공식 출처

아래 공식 문서는 2026년 8월 5일 기준으로 HTTP 200 응답을 확인했습니다. API 버전, 제품 카탈로그, 사이트 설정, 청구 방식에 따라 지원 범위와 필드가 달라질 수 있으므로 실제 적용 전 현재 문서를 다시 확인하십시오.

원문: 원문기사 보기

원문: 원문기사 보기

원문: 원문기사 보기

원문: 원문기사 보기

원문: 원문기사 보기

이 글은 결제 도구 운영 체크리스트이며 회계·세무·법률 판단이나 특정 공급사의 청구 결과를 보장하지 않습니다. 광고·파트너스 영역의 상품 정보와 가격은 최종 구매 전에 해당 판매자의 현재 조건을 다시 확인하십시오.