정기구독의 회차별 청구서(bill)를 다룹니다. 구독 한 건은 결제 주기마다 청구서를 하나씩 만들고, 예약된 결제일에 그 청구서로 결제합니다. 청구서에는 회차 금액·수량·서비스 기간·결제 결과·조정 항목(추가 금액·할인)이 들어 있습니다.
경로는 밑줄(order_subscription_bills)을 씁니다. 구독 자체는 정기구독 문서를 봅니다.
청구 상태 (status)
응답에서는 문자열로 나갑니다. 필터(status)에는 숫자와 문자열 모두 쓸 수 있습니다.
| 문자열 | 숫자 | 뜻 |
|---|---|---|
bill_ready |
2 | 결제 예정 |
bill_completed |
1 | 결제 완료 |
bill_pending |
5 | 결제 진행 중 |
bill_failure_delayed |
6 | 결제 실패 후 재시도 대기 |
bill_paused |
11 | 일시정지로 보류 |
bill_cancelled |
10 | 취소 |
bill_terminated |
20 | 해지로 종료 |
bill_failed |
-1 | 결제 실패 |
bill_recreate_cancelled |
-2 | 재생성으로 취소 |
bill_schedule_cancelled_by_payment_failure |
-11 | 결제 실패로 예약 취소 |
bill_error |
-100 | 오류 |
청구서 필드
목록·상세 모두 같은 형태입니다. 값이 없는 필드는 빠집니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| order_subscription_bill_id | string | 청구서 ID |
| user_id | string | 구독 회원 |
| order_id / order_number | string | 연결된 주문 ID / 주문번호 |
| order_name | string | 주문명 |
| duration | integer | 회차 |
| status | string | 청구 상태 (위 표) |
| price / tax_free_price | number | 청구 금액 / 그중 비과세 |
| origin_price / origin_tax_free_price | number | 조정 전 금액 |
| one_unit_price / one_unit_tax_free_price | number | 단가 |
| quantity | integer | 수량 |
| unit | string | 통화 (KRW 등) |
| membership_type | string | personal / business / business_department |
| product_type | string | 상품 유형 (delivery_products 등) |
| reserve_payment_at | string | 결제 예정 시각 |
| purchased_at | string | 결제 완료 시각 |
| service_start_at / service_end_at | string | 이 회차의 서비스 기간 |
| revoked_at | string | 취소·회수 시각 |
| retry_count / total_retry_count | integer | 재시도 횟수 |
| last_error_at / last_error_message | string | 마지막 결제 실패 시각·메시지 |
| cancelled_price / cancelled_tax_free_price / cancelled_quantity / cancelled_fee | 취소된 금액·수량·수수료 | |
| cancel_request_type | integer | 취소 요청 유형 |
| use_delivery / amount_delivery_fee | boolean / number | 배송 여부 / 배송비. 배송비 0 은 지불 방식에 따라 착불일 수 있습니다 |
| billing_key_data | object | 결제에 쓴 빌링키 정보 |
| usage_api_status / usage_api_items / usage_api_summary | 사용량 기반 구독의 사용량 조회 결과 | |
| order_subscription_adjustments | array | 조정 항목 (추가 금액·할인) |
| products | array | 청구 상품 |
| order_subscription_transaction | object | null | 성공한 결제 거래 |
| order_subscription_transaction_id | string | 성공한 결제 거래 ID |
| order_subscription_bill_histories | array | 청구서 변경 이력 |
| order_purchase | object | null | 회차 배송·구매 정보 |
| order_subscription_failed_orders | array | 결제 실패한 주문과 실패 정보(error_data) |
GET /v1/order_subscription_bills
청구서 목록을 최신순으로 조회합니다. 보통 구독 한 건의 회차 목록을 볼 때 씁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_subscription_bill_list·supervisor:order_subscription_bill_list—Bootpay-Role은user·supervisor만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | order_subscription_id | string | 구독 ID 또는 구독의 가맹점 고유값. ex_uid·external_uid·uid 로 보내도 됩니다 |
||
| query | status | string | integer | array | 청구 상태. 여러 개는 status[]=bill_ready&status[]=bill_failed 또는 status=2,-1 |
||
| query | page | integer | 1 | 페이지 | |
| query | limit | integer | 20 | 페이지 크기. 100 을 넘기면 20 건으로 조회합니다 |
order_subscription_id가 이 프로젝트에 없는 값이면 구독 조건이 빠지고 프로젝트 전체 청구서가 나옵니다. 구독 ID 가 맞는지 먼저 확인하세요.- 해석할 수 없는
status값은400 INVALID_PARAMETER입니다.
응답
200 OK
{
"list": [
{
"order_subscription_bill_id": "66c2...",
"duration": 3,
"status": "bill_ready",
"order_name": "월간 원두 구독",
"price": 19900,
"tax_free_price": 0,
"quantity": 1,
"unit": "KRW",
"reserve_payment_at": "2026-10-25T09:00:00+09:00",
"service_start_at": "2026-10-25T00:00:00+09:00",
"service_end_at": "2026-11-24T23:59:59+09:00",
"order_subscription_adjustments": [],
"products": [],
"order_subscription_transaction": null,
"order_subscription_transaction_id": null,
"order_subscription_bill_histories": [],
"order_purchase": null,
"order_subscription_failed_orders": []
}
],
"count": 12
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list[] | object | 위 청구서 필드 |
| count | integer | 조건에 맞는 전체 개수 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | INVALID_PARAMETER |
status 값을 해석할 수 없음 |
공통 오류(인증·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-08-27
status에 문자열 값(bill_ready등) 허용. 숫자도 계속 동작 - 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다
GET /v1/order_subscription_bills/:id
청구서 한 건을 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_subscription_bill_detail·supervisor:order_subscription_bill_detail—Bootpay-Role은user·supervisor만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 청구서 ID (order_subscription_bill_id) |
응답
200 OK — 위 청구서 필드 형태의 객체 하나
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ORDER_SUBSCRIPTION_BILL_NOT_FOUND |
없는 청구서 ID |
| 401 | ORDER_SUBSCRIPTION_BILL_DENIED |
다른 프로젝트의 청구서 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다
PUT /v1/order_subscription_bills/:id
결제 예정 청구서의 수량·옵션·조정 항목을 바꿔 금액을 다시 계산합니다. PATCH 도 같습니다.
현재 이 API 는 동작하지 않습니다.
- 대상 청구서를 경로의
:id가 아니라 본문의order_subscription_bill_id로 찾습니다. 본문에 없으면404 ORDER_SUBSCRIPTION_BILL_NOT_FOUND입니다.- 청구서를 찾더라도 수정 처리에 필요한 값(결제 예정일·서비스 기간·메모)을 넘기지 않아
500 SERVER_ERROR로 끝나고, 아무것도 바뀌지 않습니다.청구서 수정이 필요하면 부트페이 관리자 화면을 이용하세요.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:order_subscription_bill_update—Bootpay-Role: supervisor로 부릅니다(생략하면 supervisor 로 봅니다). 다른 역할은 401API_ROLE_NOT_SUPPORT - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 청구서 ID (현재 대상 선택에는 쓰이지 않음) | |
| body | order_subscription_bill_id | string | O | 수정할 청구서 ID | |
| body | quantity | integer | 수량 | ||
| body | product_option_snapshot_id | string | 바꿀 상품 옵션 스냅샷 ID | ||
| body | order_subscription_adjustments | array | 조정 항목. 항목: name, price, tax_free_price. 이름이 없고 금액이 모두 0 인 행은 버립니다 |
응답
200 OK, 본문 없음 (정상 동작 시)
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ORDER_SUBSCRIPTION_BILL_NOT_FOUND |
본문의 order_subscription_bill_id 가 없거나 없는 청구서 |
| 401 | ORDER_SUBSCRIPTION_BILL_DENIED |
다른 프로젝트의 청구서 |
| 500 | SERVER_ERROR |
청구서를 찾은 경우 현재 항상 (위 안내 참고) |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다
