정기구독 청구

정기구독의 회차별 청구서​(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 만 받습니다(그 밖의 값은 401 API_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 만 받습니다(그 밖의 값은 401 API_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 로 봅니다). 다른 역할은 401 API_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 를 부여받아야 합니다

함께 보기