정기구독

정기구독(구독 계약)을 조회하고, 가맹점 서버가 계약을 변경·승인·거절·일시정지·재개·해지·중도인수·양도하는 API 입니다. 회차 금액 조정, 구독 쿠폰, 수시결제(온디맨드) 재결제, 회차 결제 취소, 구매자 대신 올리는 변경 요청도 이 문서에 있습니다.

  • 모든 API 는 프로젝트 인증이 필요합니다 — 인증. 구매자를 대신하는 요청(/requests/ing/*)도 가맹점 서버가 구독 ID 로 호출합니다. 이때 로그인한 회원을 JWT 또는 user_id 로 함께 보내면 그 회원의 구독인지 확인합니다(선택) — 구매자 화면에서 부를 때는 함께 보내기를 권장합니다. 수시결제(/charge)도 같은 방식으로 키 소유 회원을 대조할 수 있습니다.
  • scope 의 역할 부분(user: / supervisor:)은 Bootpay-Role 헤더 값이 우선하고, 헤더가 없으면 각 엔드포인트에 적힌 역할을 씁니다.
  • 오류 형식은 오류를 봅니다. 결제가 따라가는 호출(승인·수시결제·해지)은 네트워크 오류 재시도에 대비해 멱등 키를 보내는 것을 권장합니다.
  • 회차별 청구서는 정기구독 청구, 요청 승인·거절은 정기구독 요청, 구독 상품 설정은 구독 설정을 봅니다.

구독 상태

응답의 status 는 아래 문자열로 나옵니다. 조회 필터에는 문자열과 숫자를 모두 쓸 수 있습니다.

status 숫자 뜻
contract_requested_completed 0 신청 완료, 활성화 전
free_trial -1 무료 체험 중
subscribing 1 구독 중
temporarily_paused -2 일시정지
paused_due_to_issue -3 결제 실패 등 문제로 멈춤
first_payment_error -10 첫 결제 오류
rejected -12 승인 거절됨
auto_terminated 15 만기 자동 종료
manual_terminated 20 구매자 해지
admin_terminated -11 관리자(가맹점) 해지
mid_term_transfer_approved 25 중도인수 처리됨
mid_term_transfer_requested 26 중도인수 요청됨

승인 상태 approval_status 는 approval_pending(0), approval_requested(1), approval_approved_auto(2), approval_approved_manual(3), approval_failed(-1), approval_rejected(-2), approval_hold_on(-3) 입니다.

상태별로 허용되는 호출

서버가 상태를 검사하는 호출만 적었습니다. O 는 허용, – 는 거절입니다.

구독 상태 관리자 일시정지 PUT :id/pause 관리자 재개 PUT :id/resume 관리자 해지 PUT :id/terminate 관리자 중도인수 PUT :id/purchase 구매자 일시정지 ing/pause 구매자 재개 ing/resume 구매자 중도인수 ing/purchase 구매자 해지 ing/termination 수시결제 charge
contract_requested_completed O – O O – – – O –
free_trial O – O O – – – O (체험 취소) –
subscribing O – O O O – O O O (수시결제 구독만)
temporarily_paused – O O O – O – O –
paused_due_to_issue O – O O – – – O –
first_payment_error, rejected O – O O – – – – –
mid_term_transfer_requested O – O O – – – – –
mid_term_transfer_approved O – O – – – – – –
auto_terminated, manual_terminated, admin_terminated O – – O – – – – –
  • 승인·거절​(PUT :id/approve, PUT :id/reject)은 status 가 아니라 approval_status 를 봅니다. approval_pending·approval_requested·approval_hold_on 일 때만 됩니다.
  • 관리자 호출은 구독 설정(일시정지 허용 여부 등)을 무시하고 즉시 처리합니다. 관리자 일시정지·중도인수는 해지된 구독도 막지 않으니, 호출 전에 상태를 확인하세요.
  • 구매자 요청(/requests/ing/*)은 구독 상품 설정(허용 여부·사유 필수·횟수·기간)을 모두 검사하고, 설정에 따라 즉시 처리하거나 가맹점 승인 대기로 둡니다. 승인 대기 중인 같은 종류 요청이 있으면 거절됩니다.
  • paused_due_to_issue 는 PUT :id/resume 으로 풀 수 없습니다(재개는 temporarily_paused 만 받습니다).
  • 금액 조정·쿠폰·계약 변경(PUT :id)은 구독 상태를 검사하지 않습니다. 대신 이미 결제된 회차는 바꿀 수 없습니다.
  • 양도(PUT :id/transfer, ing/transfer)는 현재 모든 상태에서 500 을 반환합니다. 아래 해당 절을 봅니다.

수시결제(온디맨드) 흐름

수시결제 구독(subscription_type = on_demand_subscription)은 주기 스케줄 없이, 가맹점이 필요할 때 금액을 정해 결제합니다.

  1. 구매자가 결제창에서 자동결제에 동의하고 첫 결제를 마치면, 구독에 재결제 키(charge_key) 가 발급됩니다.
  2. 가맹점 서버가 첫 결제 주문을 GET /v1/orders/:id 로(회원 JWT 없이) 조회하면 응답에 charge_key 가 들어 있습니다 — 주문. 이 키는 서버에만 보관하세요. 키와 금액만 있으면 결제가 됩니다.
  3. 결제: POST /v1/order_subscriptions/charge 에 charge_key 와 price 를 보냅니다. 회원(Bootpay-User-JWT 헤더 또는 최상위 user_id, 하위호환 user.user_id)은 선택이며, 보내면 키 소유 회원과 일치하는지 한 번 더 확인합니다. 결제가 끝나면 청구 회차와 주문이 만들어지고 결과를 바로 돌려줍니다. 다음 결제 예정일은 만들지 않습니다.
  4. 해지: DELETE /v1/order_subscriptions/charge 로 키를 폐기합니다. 이후 그 키로는 결제할 수 없습니다.

키는 URL 이나 쿼리에 넣지 말고 본문으로만 보냅니다.

응답 객체

여러 엔드포인트가 같은 모양의 객체를 돌려줍니다.

구독 상세 — GET /v1/order_subscriptions/:id 와 변경 API 대부분이 돌려줍니다. 주요 필드:

필드 타입 설명
order_subscription_id string 구독 ID
order_number string 구독 주문번호
user_id string 회원 ID
status string 구독 상태 (위 표)
approval_status / approval_reason / approval_at string 승인 상태·사유·시각
subscription_type string regular_subscription, delivery_subscription, rental_lease_subscription, usage_based_subscription, on_demand_subscription
subscription_billing_type string pay_per_item, pay_all_at_once 등
subscription_payment_cycle_type string 결제 주기 (1week ~ 1year)
order_name / product_name string 구독명·상품명
price / origin_price / tax_free_price / setup_price number 회차 금액·원가·비과세·설치비
quantity integer 수량
unit string 통화 (KRW 등)
username / user_phone / user_email string 계약자 정보
current_duration / payment_last_duration / total_subscription_duration integer 현재 회차·마지막 결제 회차·총 약정 회차(-1 이면 무제한)
service_start_at / service_end_at / payment_next_at string 서비스 시작·종료, 다음 결제 예정 (ISO 8601)
paused_at / pause_expected_resume_at / pause_resumed_at / pause_count 일시정지 정보
use_free_trial / free_trial_day / trial_start_at / trial_end_at 무료 체험 정보
use_delivery / delivery_type / amount_delivery_fee 배송 정보
products / options / chosen_product_options array 구독 당시 상품·옵션 스냅샷
order_subscription_bills array 회차별 청구서 — 정기구독 청구
order_subscription_adjustments array 회차 금액 조정 (order_subscription_adjustment_id, price, tax_free_price, name, type, duration, is_unlimited)
request_histories array 변경 요청 이력
user / user_group / department_corporate object 회원(마스킹)·그룹·부서 정보
user_address object 배송지
use_pause / use_termination / pause_max_count 구독 설정 요약

구독 요약 — 승인·거절·관리자 일시정지·재개·해지가 돌려줍니다. 구독 상세의 기본 필드(order_subscription_id, status, approval_status, price 등)에 products, options, order_subscription_adjustments, user_address, chosen_product_options, applied_coupons, first_order_subscription_bill(선결제 구독일 때)이 붙습니다.

GET /v1/order_subscriptions

구독 목록을 조회합니다. 기간을 주지 않으면 오늘 만들어진 구독만 나옵니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_list
  • 회원 JWT(Bootpay-User-JWT): 필요 없음. 보내도 회원으로 쓰지 않습니다(user_id 는 필터)

요청

위치 이름 타입 필수 기본값 설명
query page integer 1 1 이상
query limit integer 20 1~100 (100 초과는 100)
query s_at string 오늘 00:00 생성일 시작. search_date_from 도 같습니다
query e_at string 오늘 23:59 생성일 끝. search_date_to 도 같습니다
query keyword string 검색어. 구독 ID 를 넣으면 그 구독만
query status string 구독 상태 하나. 문자열(subscribing) 또는 숫자(1)
query order_number string 구독 주문번호
query user_id string 이 회원의 구독만 거릅니다. 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). user_ex_uid·user_external_uid·user_uid 도 받음. 이 몰의 회원이 아니거나 탈퇴한 회원이면 404
query user_group_id string 회원 그룹 ID 또는 외부 ID (user_group_ex_uid 도 받음)
query request_type string 요청 유형 필터. 현재 이 값을 보내면 500 이 납니다 — 요청 목록은 정기구독 요청을 쓰세요

page·limit 은 페이지네이션과 달리 보정하지 않습니다. page 는 1 이상, limit 은 1 이상을 보내세요.

응답

200 OK

{
  "list": [
    {
      "order_subscription_id": "66f1...",
      "order_number": "66f1...",
      "order_name": "월간 원두 구독",
      "status": "subscribing",
      "approval_status": "approval_approved_auto",
      "price": 29000,
      "payment_next_at": "2026-10-01T00:00:00+09:00",
      "has_failed_bill": false,
      "products": [],
      "options": [],
      "user": {},
      "request_histories": []
    }
  ],
  "count": 1,
  "sum_active": 1,
  "sum_pause": 0,
  "total": 1,
  "ing_pause": 0,
  "ing_termination": 0
}json
필드 타입 설명
list array 구독 목록. 구독 상세의 기본 필드 일부와 products, options, onetime_order_purchase, user, user_group, department_corporate, request_histories(대기 중인 요청)
list[].has_failed_bill boolean subscribing 인데 결제 실패한 회차가 있으면 true (구독 중일 때만 있음)
count integer 조건에 맞는 전체 개수
user / user_group object user_id·user_group_id 로 거른 경우 그 회원·그룹
sum_pending, sum_trial, sum_active, sum_pause, sum_hold_on, sum_auto_end, sum_terminated, sum_first_payment_error, sum_cancel_request, total integer 같은 조건의 상태별 건수
ing_pause, ing_resume, ing_transfer, ing_purchase, ing_termination integer 같은 조건의 승인 대기 요청 건수

값이 없는(null) 키는 응답에서 빠집니다.

오류

HTTP error_code 언제
400 INVALID_PARAMETER status 에 해석할 수 없는 문자열
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 user_id 가 이 몰의 회원이 아니면 404 USER_NOT_FOUND (이전에는 필터가 빠져 프로젝트 전체 구독을 돌려줌)
  • 2026-08-27 status 에 상태 문자열도 받음
  • 2026-09-23 문서 최초 작성

GET /v1/order_subscriptions/:id

구독 하나를 상세 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID 또는 가맹점이 지정한 외부 ID

응답

200 OK — 구독 상세 객체 (위 응답 객체 참고)

{
  "order_subscription_id": "66f1...",
  "order_number": "66f1...",
  "status": "subscribing",
  "subscription_type": "regular_subscription",
  "price": 29000,
  "current_duration": 3,
  "total_subscription_duration": 12,
  "order_subscription_bills": [],
  "order_subscription_adjustments": [],
  "request_histories": [],
  "service_status": { "service_status": 1 },
  "use_pause": true,
  "use_termination": true
}json

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id

계약 내용을 바꿉니다. 보낸 항목만 바뀌고 나머지는 그대로입니다. 전체 변경이 한 번에 반영되거나 하나도 반영되지 않으며, 변경 이력에 한 줄로 남고 구독 변경 웹훅이 발송됩니다. PATCH 도 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_update
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID 또는 외부 ID
body product_id string 바꿀 상품 ID
body product_option_id string 바꿀 상품 옵션 ID
body order_name string 구독명
body total_subscription_duration integer 총 약정 회차
body quantity integer 수량 (1 이상)
body price number 회차 기준금액. 0 보다 커야 하며 결제 예정 회차부터 반영
body address_id string 회원 주소록의 배송지 ID
body username string 계약자 이름 (미결제 청구서에도 반영)
body phone string 계약자 전화번호
body email string 계약자 이메일
body use_free_trial boolean 무료 체험 사용. false 를 보내면 끕니다
body free_trial_day integer 무료 체험 일수
body service_start_at string 서비스 시작일
body service_end_at string 서비스 종료일
body memo string 변경 이력에 남길 사유

응답

200 OK — 바뀐 뒤의 구독 상세 객체

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_INVALID 이 프로젝트에 없는 구독
400 PRODUCT_QTY_INVALID quantity 가 1 미만
400 ORDER_SUBSCRIPTION_PRICE_INVALID price 가 0 이하
404 PRODUCT_NOT_FOUND 바꿀 상품을 찾을 수 없음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-08-24 price·memo 추가, 전체 변경을 한 번에 반영
  • 2026-08-26 use_free_trial: false 로 무료 체험을 끌 수 있게 수정
  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/approve

승인 대기 중인 구독을 승인합니다.

  • 무료 체험 구독: free_trial 로 바뀌고, 체험 종료 다음 날이 서비스 시작일·첫 결제일이 됩니다.
  • 선결제 구독: 첫 회차를 즉시 결제​​한 뒤 subscribing 으로 바뀝니다. 결제가 실패하면 구독은 paused_due_to_issue·approval_hold_on 이 되고 결제 오류가 그대로 반환됩니다.
  • 후불 구독: subscribing 으로 바뀌고 첫 청구서만 만듭니다.

승인 알림과 승인 웹훅이 발송됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_approve
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID (외부 ID 는 받지 않음)
body reason string 승인 사유

응답

200 OK — 구독 요약 객체

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_ALREADY_PROCESSED approval_status 가 대기·요청·보류가 아님
500 ORDER_SUBSCRIPTION_PREPAID_FAILED 선결제 승인 중 예상하지 못한 오류 (구독은 보류 상태가 됨)

선결제 첫 회차 결제 실패는 결제 오류 코드가 그대로 옵니다. 공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/reject

승인 대기 중인 구독을 거절합니다. status 가 rejected 가 되고, 선결제된 첫 회차는 취소되며 잡아 둔 재고는 복구됩니다. 거절 알림과 웹훅이 발송됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_reject
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID (외부 ID 는 받지 않음)
body reason string 거절 사유 (구매자 알림에 쓰임)

응답

200 OK — 구독 요약 객체

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_ALREADY_PROCESSED approval_status 가 대기·요청·보류가 아님

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/pause

가맹점이 구독을 즉시 일시정지합니다. 구독 설정의 일시정지 허용 여부는 보지 않습니다. 진행 중인 청구 회차도 멈추고 일시정지 웹훅이 발송됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_pause
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID (외부 ID 는 받지 않음)
body paused_at string O 일시정지 시작 시각
body expected_resume_at string O 재개 예정 시각. 지금 이후 1년 이내. 빠뜨리면 500 이 나므로 반드시 보내세요
body reason string 사유

응답

200 OK — 구독 요약 객체 (status: temporarily_paused)

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 TIME_INVALID paused_at·expected_resume_at 을 시각으로 읽을 수 없음 (paused_at 누락 포함)
400 ORDER_SUBSCRIPTION_ALREADY_PAUSE 이미 temporarily_paused
400 ORDER_SUBSCRIPTION_EXPECTED_RESUME_AT_INVALID expected_resume_at 이 과거이거나 1년 뒤보다 늦음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/resume

가맹점이 일시정지된 구독을 즉시 재개합니다. 멈춘 기간만큼 구독 기간이 늘어나고, 멈춘 청구 회차가 복원되며 재개 웹훅이 발송됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_resume
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID (외부 ID 는 받지 않음)
body reason string 사유

응답

200 OK — 구독 요약 객체 (status: subscribing)

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_RESUME_UNABLE temporarily_paused 가 아님 (paused_due_to_issue 포함)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/terminate

가맹점이 구독을 즉시 해지합니다. 구독 설정의 해지 허용·승인 여부는 보지 않습니다. status 는 admin_terminated 가 되고, 정산 금액에 따라 결제 취소(환불)를 진행하며 해지 웹훅이 발송됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_terminate
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID (외부 ID 는 받지 않음)
body reason string 해지 사유
body termination_fee number 0 중도해지 수수료
body last_bill_refund_price number 0 마지막 회차 환불 금액
body final_fee number 0 최종 정산액. 양수면 추가 청구, 음수면 환불
body service_end_at string 서비스 이용 종료 시각
body cancel_date string 해지 기준일

금액 3종은 보내지 않으면 0 으로 처리​​됩니다. 서버 계산값을 쓰려면 먼저 GET /v1/order_subscriptions/requests/ing/calculate_termination_fee 로 받은 값을 그대로 보내세요.

응답

200 OK — 구독 요약 객체 (status: admin_terminated)

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_TERMINATE_CANNOT_ABLE 이미 auto_terminated·manual_terminated·admin_terminated
400 TIME_INVALID service_end_at·cancel_date 를 시각으로 읽을 수 없음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/purchase

가맹점이 렌탈·리스 구독을 즉시 중도인수 처리합니다. 구독 설정의 중도인수 허용 여부는 보지 않습니다. status 가 mid_term_transfer_approved 가 됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_purchase
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID 또는 외부 ID
body price number 서버 계산값 인수 금액
body tax_free_price number 서버 계산값 인수 비과세 금액
body reason string 사유

서버 계산값은 (총 약정 회차 − 결제한 회차) × 회차 금액 × 인수 수수료율(설정값, 없으면 0.2) 입니다.

응답

200 OK — 구독 상세 객체

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
500 SERVER_ERROR 이미 mid_term_transfer_approved 인 구독 (알려진 결함 — 400 이 아니라 500 으로 옵니다)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/transfer

구독을 다른 회원에게 양도(승계)합니다.

현재 동작하지 않습니다. 이 호출은 구독이 있으면 항상 500 SERVER_ERROR 를 반환하고 아무것도 바꾸지 않습니다. 수정되면 이 문서의 변경 이력에 적습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_transfer
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID 또는 외부 ID
body new_user_id string O 새 소유 회원. 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 이 몰의 탈퇴하지 않은 회원이어야 합니다
body new_username string O 새 계약자 이름
body new_user_email string O 새 계약자 이메일
body new_user_phone string O 새 계약자 전화번호
body new_user_address string 새 배송지
body wallet_id string 새 결제수단 ID
body reason string 사유

응답

200 OK — 구독 상세 객체 (정상 동작 시)

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING new_user_id 누락 (payload.field: new_user_id)
404 USER_NOT_FOUND new_user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
500 SERVER_ERROR 구독이 있으면 항상 (알려진 결함)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 new_user_id 를 이 몰의 회원으로 확인 — 아니면 404 USER_NOT_FOUND (이전에는 아무 값이나 받음)
  • 2026-09-23 문서 최초 작성

POST /v1/order_subscriptions/:id/adjustments

회차 금액 조정(할인·추가금)을 추가합니다. 회차 범위 전체를 먼저 검증하고, 하나라도 걸리면 아무것도 저장하지 않습니다. 이미 만들어진 미결제 청구서에도 바로 반영됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_adjustment_create
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID 또는 외부 ID
body price number O 조정 금액. 음수는 할인, 양수는 추가금. 0 은 거절
body tax_free_price number 0 조정 비과세 금액
body name string 항목명
body type integer price>0 이면 2, 아니면 1 1 할인, 2 추가금, 3 주기 할인, 4 주기 추가비용, 5 매회차 추가비용
body duration_from integer 1 시작 회차. duration 도 같습니다
body duration_to integer duration_from 끝 회차
body is_unlimited boolean false true 면 duration_from 회차부터 계약 끝까지 적용되는 조정 1건 (duration_to 무시)

회차 상한은 총 약정 회차, 무제한 구독은 60 회차입니다. 같은 회차에 이름·종류가 같은 조정은 중복으로 거절됩니다. 조정 후 회차 금액이 음수가 되면 거절됩니다.

응답

200 OK — 구독 상세 객체 (order_subscription_adjustments 에 추가된 항목 포함)

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_INVALID 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_ADJUST_PRICE_INVALID price 가 없거나 0
400 SUBSCRIPTION_ADJUSTMENT_DURATION_INVALID 회차가 0 이하, 시작 > 끝, 상한 초과
400 SUBSCRIPTION_ADJUSTMENT_PAYMENT_COMPLETED 이미 결제된 회차가 범위에 있음
400 SUBSCRIPTION_ADJUSTMENT_DUPLICATE 같은 회차에 같은 조정이 있음

조정 후 금액이 음수가 되는 경우의 오류도 400 으로 옵니다. 공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-08-24 duration_from·duration_to·is_unlimited 범위 지정, 사전 검증 후 일괄 저장
  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/:id/adjustments

한 회차의 개별 조정을 보낸 목록으로 통째로 교체​​합니다. 무제한 조정은 교체 대상이 아니며 그대로 남습니다. 해당 회차 청구서도 다시 계산합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_adjustment_update
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID 또는 외부 ID
body duration integer 1 대상 회차
body adjustments array O 새 조정 목록. 빈 배열이면 개별 조정을 모두 지웁니다
body adjustments[].name string 항목명
body adjustments[].price number 0 조정 금액
body adjustments[].tax_free_price number 0 조정 비과세 금액
body adjustments[].type integer 같은 이름의 기존 종류 조정 종류

is_unlimited: true 인 항목은 무시합니다.

응답

200 OK — 구독 상세 객체

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_INVALID 이 프로젝트에 없는 구독
400 SUBSCRIPTION_ADJUSTMENT_PAYMENT_COMPLETED 이미 결제된 회차

교체 후 회차 금액이 음수가 되는 경우의 오류도 400 으로 옵니다. adjustments 를 빠뜨리면 500 이 납니다. 공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-08-16 type 을 안 보내면 기존 항목 종류를 승계, price 미전송은 0
  • 2026-09-23 문서 최초 작성

DELETE /v1/order_subscriptions/:id/adjustments

조정 하나를 지웁니다. 무제한 조정을 지우면, 이미 결제된 회차에는 같은 금액의 개별 조정을 남겨 결제 내역과 맞춥니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_adjustment_delete
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID 또는 외부 ID
query / body order_subscription_adjustment_id string O 지울 조정 ID

응답

200 OK — 구독 상세 객체

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_INVALID 이 프로젝트에 없는 구독
404 SUBSCRIPTION_ADJUSTMENT_NOT_FOUND 이 구독에 없는 조정 ID
400 SUBSCRIPTION_ADJUSTMENT_PAYMENT_COMPLETED 이미 결제된 회차의 조정

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

GET /v1/order_subscriptions/:order_subscription_id/coupons

구독에 적용 중인 쿠폰 목록을 조회합니다. 최근 적용 순입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_coupon_list · supervisor:order_subscription_coupon_list — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원: 선택 — Bootpay-User-JWT 또는 user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독​​에만 동작합니다(아니면 403 SUBSCRIPTION_DENIED). 밝히지 않으면 가맹점 대리 호출로 이 몰의 구독 전체가 대상입니다. JWT 를 보내면 엄격하게 검증합니다(무효면 401) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path order_subscription_id string O 구독 ID
body/query user_id string 회원 지정(_id 또는 외부 회원 ID ex_uid). JWT 와 함께 보내면 같은 회원이어야 합니다

응답

200 OK

{
  "ok": true,
  "items": [
    {
      "subscription_coupon_binding_id": "66f2...",
      "order_subscription_id": "66f1...",
      "coupon_id": "66f0...",
      "coupon_template_id": "66e9...",
      "coupon_name_snapshot": "첫 달 30% 할인",
      "discount_type_snapshot": 2,
      "discount_value_snapshot": 30,
      "total_discount_amount": 8700,
      "apply_mode": "first_bill_only",
      "apply_count": null,
      "discount_target": "subscription_amount",
      "status": "active",
      "applied_at": "2026-09-01T10:00:00+09:00"
    }
  ]
}json
필드 타입 설명
items[].subscription_coupon_binding_id string 적용 ID. 해제할 때 씁니다
items[].apply_mode string first_bill_only, n_bills(apply_count 회차), all_bills
items[].discount_target string subscription_amount(구독 금액) 또는 shipping(배송비)
items[].total_discount_amount number 할인 합계
items[].discount_per_bill array 회차별 할인
items[].adjustment_ids array 이 쿠폰이 만든 회차 금액 조정 ID

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독 또는 다른 프로젝트의 구독
403 SUBSCRIPTION_DENIED (6008) 밝힌 회원이 이 구독의 소유자가 아님
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(없는 회원·탈퇴 회원)
403 USER_NOT_MATCH (2302) JWT 회원과 user_id 회원이 다름

공통 오류(인증·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-04-14 추가
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 구독·쿠폰만 대상 — 다른 프로젝트 ID 는 404
  • 2026-09-28 회원 선택 지정(JWT 또는 user_id) — 지정 회원이 구독 소유자가 아니면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404 COUPON_NOT_FOUND
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

POST /v1/order_subscriptions/:order_subscription_id/coupons

구독에 쿠폰을 적용합니다. 쿠폰은 사용 처리되고, 할인은 회차 금액 조정으로 들어가며 쿠폰 적용 웹훅이 발송됩니다. 구독 금액 쿠폰과 배송비 쿠폰만 쓸 수 있습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_coupon_create · supervisor:order_subscription_coupon_create — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원: 선택 — Bootpay-User-JWT 또는 user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독​​에만 동작합니다(아니면 403 SUBSCRIPTION_DENIED). 밝히지 않으면 가맹점 대리 호출로 이 몰의 구독 전체가 대상입니다. JWT 를 보내면 엄격하게 검증합니다(무효면 401) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path order_subscription_id string O 구독 ID
body/query user_id string 회원 지정(_id 또는 외부 회원 ID ex_uid). JWT 와 함께 보내면 같은 회원이어야 합니다
body coupon_id string O 적용할 쿠폰 ID (발급된 쿠폰)

적용 전에 미리보기로 할인액을 확인하세요.

응답

200 OK

{ "ok": true }json

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독 또는 다른 프로젝트의 구독
403 SUBSCRIPTION_DENIED (6008) 밝힌 회원이 이 구독의 소유자가 아님
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(없는 회원·탈퇴 회원)
403 USER_NOT_MATCH (2302) JWT 회원과 user_id 회원이 다름
404 COUPON_NOT_FOUND 없는 쿠폰, 다른 프로젝트의 쿠폰, 또는 이 구독의 소유자가 아닌 회원에게 발급된 쿠폰(회원 지정 여부와 무관, 쿠폰 상태는 바뀌지 않음)
400 COUPON_ALREADY_USED 사용 가능 상태가 아닌 쿠폰
400 COUPON_EXPIRED 유효기간이 지난 쿠폰
400 COUPON_TYPE_NOT_APPLICABLE_TO_SUBSCRIPTION 구독·배송비 쿠폰이 아님
400 COUPON_NOT_APPLICABLE_FOR_USAGE_BASED_SUBSCRIPTION 사용량 구독
400 COUPON_SHIPPING_NOT_APPLICABLE_FOR_RECURRING_DELIVERY 정기배송 구독에 배송비 쿠폰
400 COUPON_SHIPPING_REQUIRES_USE_DELIVERY 배송이 없는 구독에 배송비 쿠폰
400 COUPON_MIN_ORDER_AMOUNT_NOT_MET 최소 주문 금액 미달
400 COUPON_POLICY_EXCLUSIVE_VIOLATION 이미 적용된 쿠폰과 함께 쓸 수 없음
400 COUPON_POLICY_GROUP_ONLY_VIOLATION 그룹 전용 쿠폰 조건 불충족
400 COUPON_N_BILLS_EXCEEDS_MAX 적용 회차 수가 1~24 밖
400 COUPON_APPLY_MODE_NOT_SUPPORTED 지원하지 않는 적용 방식

공통 오류(인증·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-04-14 복수형 경로 추가, 같은 종류 쿠폰 1개 제한
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 구독·쿠폰만 대상 — 다른 프로젝트 ID 는 404
  • 2026-09-28 회원 선택 지정(JWT 또는 user_id) — 지정 회원이 구독 소유자가 아니면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404 COUPON_NOT_FOUND
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

POST /v1/order_subscriptions/:order_subscription_id/coupon

단수형 옛 경로입니다. POST /v1/order_subscriptions/:order_subscription_id/coupons 와 요청·응답·오류가 같습니다. 신규 연동은 복수형을 쓰세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_coupon_create · supervisor:order_subscription_coupon_create — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원: 선택 — Bootpay-User-JWT 또는 user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독​​에만 동작합니다(아니면 403 SUBSCRIPTION_DENIED). 밝히지 않으면 가맹점 대리 호출로 이 몰의 구독 전체가 대상입니다. JWT 를 보내면 엄격하게 검증합니다(무효면 401) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path order_subscription_id string O 구독 ID
body/query user_id string 회원 지정(_id 또는 외부 회원 ID ex_uid). JWT 와 함께 보내면 같은 회원이어야 합니다
body coupon_id string O 적용할 쿠폰 ID

응답

200 OK

{ "ok": true }json

오류

복수형 경로와 같습니다.

변경 이력

  • 2026-04-14 복수형 경로가 생기면서 유지만 함(deprecated)
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 구독·쿠폰만 대상 — 다른 프로젝트 ID 는 404
  • 2026-09-28 회원 선택 지정(JWT 또는 user_id) — 지정 회원이 구독 소유자가 아니면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404 COUPON_NOT_FOUND
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

POST /v1/order_subscriptions/:order_subscription_id/coupons/preview

쿠폰을 적용하면 얼마가 할인되는지 저장 없이 계산합니다. 검증에 실패해도 200 으로 응답하고 ok: false 와 사유를 돌려줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_coupon_preview · supervisor:order_subscription_coupon_preview — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원: 선택 — Bootpay-User-JWT 또는 user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독​​에만 동작합니다(아니면 403 SUBSCRIPTION_DENIED). 밝히지 않으면 가맹점 대리 호출로 이 몰의 구독 전체가 대상입니다. JWT 를 보내면 엄격하게 검증합니다(무효면 401) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path order_subscription_id string O 구독 ID
body/query user_id string 회원 지정(_id 또는 외부 회원 ID ex_uid). JWT 와 함께 보내면 같은 회원이어야 합니다
body coupon_id string O 쿠폰 ID
body exclude_applied boolean false true 면 이미 적용된 쿠폰과의 병용 검사를 건너뛰고 원가 기준으로 다시 계산

응답

200 OK

{
  "ok": true,
  "coupon_id": "66f0...",
  "coupon_name": "첫 달 30% 할인",
  "coupon_type": 4,
  "discount_type": 2,
  "discount_value": 30,
  "discount_target": "subscription_amount",
  "applied_duration": 1,
  "apply_mode": "first_bill_only",
  "apply_count": null,
  "discount_amount": 8700,
  "breakdown": {
    "origin_price": 29000,
    "times_benefit_sum": 0,
    "display_price": 29000,
    "coupon_discount": 8700,
    "setup_fee": 0,
    "delivery_fee": 3000,
    "total_first_bill": 23300
  },
  "per_bill_breakdown": [
    { "bill_no": 1, "is_unlimited": false, "base": 29000, "coupon_amount": 8700, "label": "1회차" }
  ]
}json
필드 타입 설명
ok boolean 적용 가능 여부
applied_duration integer 할인이 시작되는 회차
discount_amount integer 할인 합계
breakdown object 첫 청구 금액 분해. total_first_bill 은 0 미만이 되지 않습니다
per_bill_breakdown array 회차별 할인 (배송비 쿠폰은 빈 배열)
error_code integer ok: false 일 때 숫자 오류 코드
error_message string ok: false 일 때 사유

실패 응답 예:

{ "ok": false, "error_code": 11502, "error_message": "만료된 쿠폰입니다." }json

ok: false 의 error_code 는 다른 오류 응답과 달리 숫자​​입니다. 사유는 적용 API 의 오류 표와 같습니다.

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독 또는 다른 프로젝트의 구독
403 SUBSCRIPTION_DENIED (6008) 밝힌 회원이 이 구독의 소유자가 아님
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(없는 회원·탈퇴 회원)
403 USER_NOT_MATCH (2302) JWT 회원과 user_id 회원이 다름
404 COUPON_NOT_FOUND 없는 쿠폰, 다른 프로젝트의 쿠폰, 또는 이 구독의 소유자가 아닌 회원에게 발급된 쿠폰(회원 지정 여부와 무관, 쿠폰 상태는 바뀌지 않음)

공통 오류(인증·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-04-14 exclude_applied·per_bill_breakdown 추가
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 구독·쿠폰만 대상 — 다른 프로젝트 ID 는 404
  • 2026-09-28 회원 선택 지정(JWT 또는 user_id) — 지정 회원이 구독 소유자가 아니면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404 COUPON_NOT_FOUND
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

POST /v1/order_subscriptions/:order_subscription_id/coupon/preview

단수형 옛 경로입니다. POST /v1/order_subscriptions/:order_subscription_id/coupons/preview 와 요청·응답·오류가 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_coupon_preview · supervisor:order_subscription_coupon_preview — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원: 선택 — Bootpay-User-JWT 또는 user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독​​에만 동작합니다(아니면 403 SUBSCRIPTION_DENIED). 밝히지 않으면 가맹점 대리 호출로 이 몰의 구독 전체가 대상입니다. JWT 를 보내면 엄격하게 검증합니다(무효면 401) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path order_subscription_id string O 구독 ID
body/query user_id string 회원 지정(_id 또는 외부 회원 ID ex_uid). JWT 와 함께 보내면 같은 회원이어야 합니다
body coupon_id string O 쿠폰 ID
body exclude_applied boolean false 복수형과 같음

응답

복수형 경로와 같습니다.

오류

복수형 경로와 같습니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 구독·쿠폰만 대상 — 다른 프로젝트 ID 는 404
  • 2026-09-28 회원 선택 지정(JWT 또는 user_id) — 지정 회원이 구독 소유자가 아니면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404 COUPON_NOT_FOUND
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

DELETE /v1/order_subscriptions/:order_subscription_id/coupons/:id

적용된 쿠폰 하나를 해제합니다. 쿠폰 해제 웹훅이 발송됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_coupon_delete · supervisor:order_subscription_coupon_delete — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원: 선택 — Bootpay-User-JWT 또는 user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독​​에만 동작합니다(아니면 403 SUBSCRIPTION_DENIED). 밝히지 않으면 가맹점 대리 호출로 이 몰의 구독 전체가 대상입니다. JWT 를 보내면 엄격하게 검증합니다(무효면 401) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path order_subscription_id string O 구독 ID
body/query user_id string 회원 지정(_id 또는 외부 회원 ID ex_uid). JWT 와 함께 보내면 같은 회원이어야 합니다
path id string O 적용 ID (subscription_coupon_binding_id). 쿠폰 ID 가 아닙니다

응답

200 OK

{ "ok": true }json

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독 또는 다른 프로젝트의 구독
403 SUBSCRIPTION_DENIED (6008) 밝힌 회원이 이 구독의 소유자가 아님
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(없는 회원·탈퇴 회원)
403 USER_NOT_MATCH (2302) JWT 회원과 user_id 회원이 다름
404 SUBSCRIPTION_COUPON_BINDING_NOT_FOUND 이 구독에 적용 중인 해당 적용 ID 가 없음

공통 오류(인증·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-04-14 적용 ID 로 특정 쿠폰만 해제
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 구독·쿠폰만 대상 — 다른 프로젝트 ID 는 404
  • 2026-09-28 회원 선택 지정(JWT 또는 user_id) — 지정 회원이 구독 소유자가 아니면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404 COUPON_NOT_FOUND
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

DELETE /v1/order_subscriptions/:order_subscription_id/coupon

단수형 옛 경로입니다. binding_id 를 보내면 그 적용만, 보내지 않으면 적용 중인 쿠폰 중 첫 번째​​를 해제합니다. 쿠폰이 여러 개일 수 있으니 복수형 경로를 쓰세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_coupon_delete · supervisor:order_subscription_coupon_delete — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원: 선택 — Bootpay-User-JWT 또는 user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독​​에만 동작합니다(아니면 403 SUBSCRIPTION_DENIED). 밝히지 않으면 가맹점 대리 호출로 이 몰의 구독 전체가 대상입니다. JWT 를 보내면 엄격하게 검증합니다(무효면 401) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path order_subscription_id string O 구독 ID
body/query user_id string 회원 지정(_id 또는 외부 회원 ID ex_uid). JWT 와 함께 보내면 같은 회원이어야 합니다
query / body binding_id string 해제할 적용 ID

응답

200 OK

{ "ok": true }json

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독 또는 다른 프로젝트의 구독
403 SUBSCRIPTION_DENIED (6008) 밝힌 회원이 이 구독의 소유자가 아님
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(없는 회원·탈퇴 회원)
403 USER_NOT_MATCH (2302) JWT 회원과 user_id 회원이 다름
404 SUBSCRIPTION_COUPON_BINDING_NOT_FOUND 적용 중인 쿠폰이 없음

공통 오류(인증·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 구독·쿠폰만 대상 — 다른 프로젝트 ID 는 404
  • 2026-09-28 회원 선택 지정(JWT 또는 user_id) — 지정 회원이 구독 소유자가 아니면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404 COUPON_NOT_FOUND
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

POST /v1/order_subscriptions/charge

수시결제 구독을 재결제 키로 즉시 결제합니다. 위 수시결제 흐름​​을 먼저 봅니다.

결제 전에 키·소유 회원·결제수단·구독·상품·금액 상한을 차례로 검사합니다. 통과하면 청구 회차를 만들고 등록된 결제수단으로 바로 결제한 뒤 주문을 만듭니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_charge
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 최상위 user_id(쇼핑몰 서버 지정). 보내면 키 소유 회원과 대조합니다. 결제·해지 대상 회원은 항상 키 소유 회원입니다 — 회원 JWT
  • Idempotency-Key 권장 — 멱등 키

요청

위치 이름 타입 필수 기본값 설명
body charge_key string O 재결제 키. 본문으로만 보냅니다
body price integer 구독 금액 결제 금액. 0 이상, 키의 1회 상한(기본: 구독 금액) 이하
body tax_free_price integer 0 비과세 금액
body user_id string 로그인한 회원. 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 키 소유 회원과 대조
body user object 하위호환. 보내면 키 소유 회원과 대조
body user.user_id string 하위호환. 회원 ID, 로그인 ID, 이메일 중 하나
body metadata object 이 결제에 남길 가맹점 데이터
{
  "charge_key": "ck_...",
  "price": 12000,
  "metadata": { "reason": "추가 충전" }
}json

응답

200 OK

{
  "bill_id": "66f3...",
  "transaction_id": "66f3...",
  "order_id": "66f3...",
  "order_number": "66f3...",
  "receipt_id": "66f3...",
  "price": 12000,
  "purchased_at": "2026-09-23T14:00:00+09:00"
}json
필드 타입 설명
bill_id string 이번 결제의 청구 회차 ID
transaction_id string 결제 트랜잭션 ID
order_id string 만들어진 주문 ID
order_number string 주문번호
receipt_id string 부트페이 영수증 ID
price number 결제 금액
purchased_at string 결제 시각

값이 없는 키는 빠집니다.

202 Accepted — 결제사 처리가 지연되면 오류 형식으로 SUBSCRIPTION_TRANSACTION_PENDING 과 payload.bill_id 가 옵니다. 결과는 웹훅으로 확정됩니다. 같은 결제를 다시 요청하지 말고 웹훅이나 청구 회차 조회로 확인하세요.

오류

HTTP error_code 언제
400 CHARGE_KEY_NOT_FOUND 없는 키이거나 다른 프로젝트의 키
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 (키 검사 전)
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
401 USER_SESSION_INVALID · USER_JWT_INVALID 보낸 JWT 가 무효·만료
429 CHARGE_KEY_RATE_LIMITED 소유 회원 불일치가 반복돼 키가 잠김
400 CHARGE_KEY_USER_MISMATCH JWT·user_id·user.user_id 의 회원이 키 소유 회원과 다르거나 소유 회원이 탈퇴함 (실패 누적)
400 CHARGE_KEY_REVOKED 해지된 키
400 CHARGE_KEY_WALLET_INVALID 키가 사용 불가 상태이거나 결제수단이 삭제·만료됨
400 CHARGE_KEY_SUBSCRIPTION_INVALID 구독이 수시결제 구독이 아니거나 subscribing 이 아님, 또는 상품이 삭제·판매중지됨
400 CHARGE_KEY_PRICE_OVER_LIMIT price 가 음수이거나 1회 상한 초과
202 SUBSCRIPTION_TRANSACTION_PENDING 결제사 처리 지연 (payload.bill_id)
500 SUBSCRIPTION_TRANSACTION_PAYMENT_BOOTPAY_ERROR 결제 실패. message 에 결제사 사유, payload.bill_id 포함
500 SUBSCRIPTION_TRANSACTION_PAYMENT_ERROR 결제 후 회차가 완료 상태가 아님 (payload.bill_id)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원 JWT·최상위 user_id 로도 키 소유 회원을 대조 (선택, 기존 user.user_id 도 유지)
  • 2026-07-13 추가
  • 2026-07-24 user 를 선택 입력으로 변경 (키와 금액만으로 결제), 비회원 소유 키도 결제 가능
  • 2026-09-23 문서 최초 작성

DELETE /v1/order_subscriptions/charge

재결제 키를 해지합니다. 이미 해지된 키를 다시 해지해도 같은 성공 응답을 줍니다. 해지 후 그 키로 결제하면 CHARGE_KEY_REVOKED 가 옵니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_charge_revoke
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 최상위 user_id(쇼핑몰 서버 지정). 보내면 키 소유 회원과 대조합니다. 결제·해지 대상 회원은 항상 키 소유 회원입니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body charge_key string O 재결제 키
body user_id string 로그인한 회원. 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 키 소유 회원과 대조
body user object 하위호환. 보내면 키 소유 회원과 대조
body user.user_id string 하위호환. 회원 ID, 로그인 ID, 이메일 중 하나

응답

200 OK

{ "revoked": true }json

오류

HTTP error_code 언제
400 CHARGE_KEY_NOT_FOUND 없는 키이거나 다른 프로젝트의 키
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 (키 검사 전)
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
401 USER_SESSION_INVALID · USER_JWT_INVALID 보낸 JWT 가 무효·만료
429 CHARGE_KEY_RATE_LIMITED 키가 잠김
400 CHARGE_KEY_USER_MISMATCH JWT·user_id·user.user_id 의 회원이 소유 회원과 다름 또는 소유 회원 탈퇴

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원 JWT·최상위 user_id 로도 키 소유 회원을 대조 (선택, 기존 user.user_id 도 유지)
  • 2026-07-13 추가
  • 2026-09-23 문서 최초 작성

POST /v1/order_subscriptions/bill/cancel

결제가 끝난 청구 회차 하나를 전액 또는 부분 취소합니다. 회차가 속한 주문의 결제를 즉시 취소합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_cancel
  • 회원 JWT(Bootpay-User-JWT): 필요 없음
  • Idempotency-Key 권장 — 멱등 키

요청

위치 이름 타입 필수 기본값 설명
body order_subscription_bill_id string O 청구 회차 ID (id 도 받음)
body cancel_price number 조건부 취소 금액. cancel_products 가 없으면 필수
body cancel_tax_free_price number 0 취소 비과세 금액
body cancel_products array 상품 단위 취소. 있으면 금액을 항목에서 합산
body cancel_products[].cancel_quantity integer 1 취소 수량
body cancel_products[].total_price number 항목 취소 금액. 없으면 price × cancel_quantity
body cancel_products[].price number 단가
body cancel_products[].tax_free_price number 단위 비과세 금액
body cancel_id string 가맹점 취소 ID. 결제 취소의 멱등 키로도 쓰입니다
body cancel_requester string 관리자 취소 요청자
body cancel_message string 구독 Bill 취소 취소 사유

cancel_products 도 cancel_price 도 없으면 400 이 아니라 500 이 납니다. 둘 중 하나는 꼭 보내세요.

응답

200 OK — 결제 취소 결과 (부트페이 취소 응답)

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_BILL_NOT_FOUND 없는 청구 회차
403 ORDER_SUBSCRIPTION_BILL_DENIED 다른 프로젝트의 청구 회차
400 ORDER_SUBSCRIPTION_BILL_STATUS_NOT_DONE 결제 완료 상태가 아닌 회차
500 BOOTPAY_CANT_ACCESS 결제 서버 인증 실패
500 BOOTPAY_CANCEL_REQUEST_FAILED 결제 취소 실패 (payload 에 결제 서버 응답)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

POST /v1/order_subscriptions/requests/ing/pause

구매자 대신 일시정지를 요청합니다. 구독 설정을 모두 검사하고, 설정에 따라 즉시 일시정지하거나 가맹점 승인 대기로 둡니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_request_ing_pause
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 보내면 그 회원의 구독에만 요청합니다. 안 보내면 가맹점 대리 호출로 처리합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body user_id string 로그인한 회원(선택). 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 구독 소유 회원과 대조
body order_subscription_id string O 구독 ID
body reason string O 사유
body expected_resume_at string O 재개 예정 시각
body paused_at string 지금 일시정지 시작 시각

응답

200 OK — 구독 상세 객체

오류

HTTP error_code 언제
403 SUBSCRIPTION_DENIED 보낸 회원(JWT·user_id)의 구독이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_PAUSE_REQUEST_DUPLICATE 승인 대기 중인 일시정지 요청이 있음
400 ORDER_SUBSCRIPTION_PAUSE_UNABLE subscribing 이 아니거나 설정상 일시정지 불가
404 SUBSCRIPTION_SETTING_NOT_FOUND 구독 설정이 없음
400 SUBSCRIPTION_PAUSE_NOT_ALLOWED 일시정지를 허용하지 않는 상품
400 SUBSCRIPTION_RESUME_REASON_REQUIRED reason 누락
400 SUBSCRIPTION_PAUSE_RESUME_DATE_REQUIRED expected_resume_at 누락
400 SUBSCRIPTION_PAUSE_STATUS_INVALID 요청 기간을 더하면 일시정지 불가
400 SUBSCRIPTION_PAUSE_DURATION_TOO_LONG 1회 최대 일시정지 기간 초과
400 SUBSCRIPTION_PAUSE_COUNT_EXCEEDED 일시정지 횟수 초과
400 SUBSCRIPTION_PAUSE_TOTAL_DAYS_EXCEEDED 총 일시정지 일수 초과

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원(JWT 또는 user_id)을 함께 보내면 구독 소유 회원과 대조 (선택)
  • 2026-09-23 문서 최초 작성

PUT /v1/order_subscriptions/requests/ing/resume

구매자 대신 재개를 요청합니다. 재개는 설정과 관계없이 항상 즉시 처리됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_request_ing_resume
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 보내면 그 회원의 구독에만 요청합니다. 안 보내면 가맹점 대리 호출로 처리합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body user_id string 로그인한 회원(선택). 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 구독 소유 회원과 대조
body order_subscription_id string O 구독 ID
body reason string 사유

응답

200 OK — 구독 상세 객체 (status: subscribing)

오류

HTTP error_code 언제
403 SUBSCRIPTION_DENIED 보낸 회원(JWT·user_id)의 구독이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_RESUME_REQUEST_DUPLICATE 처리 대기 중인 재개 요청이 있음
400 ORDER_SUBSCRIPTION_RESUME_UNABLE temporarily_paused 가 아님

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원(JWT 또는 user_id)을 함께 보내면 구독 소유 회원과 대조 (선택)
  • 2026-09-23 문서 최초 작성

GET /v1/order_subscriptions/requests/ing/calculate_purchase_price

구매자 중도인수 전에 인수 금액을 계산합니다.

현재 동작하지 않습니다. 구독이 있으면 항상 500 SERVER_ERROR 를 반환합니다. 중도인수 요청(POST .../ing/purchase)에 보낼 금액은 (총 약정 회차 − 결제한 회차) × 회차 금액 × 인수 수수료율, 비과세는 회차 비과세 × 남은 회차 × 수수료율로 계산합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_request_ing_calculate_purchase_price
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 보내면 그 회원의 구독에만 요청합니다. 안 보내면 가맹점 대리 호출로 처리합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query user_id string 로그인한 회원(선택). 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 구독 소유 회원과 대조
query order_subscription_id string O 구독 ID

응답

정상 동작 시 200 OK — 구독 상세 객체에 purchase 가 붙습니다: use_purchase, use_purchase_fee_auto, current_duration, remaining_duration, remaining_price, purchase_fee_rate, calculated_price, calculated_tax_free_price, can_purchase, is_unlimited.

오류

HTTP error_code 언제
403 SUBSCRIPTION_DENIED 보낸 회원(JWT·user_id)의 구독이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
500 SERVER_ERROR 구독이 있으면 항상 (알려진 결함)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원(JWT 또는 user_id)을 함께 보내면 구독 소유 회원과 대조 (선택)
  • 2026-09-23 문서 최초 작성

POST /v1/order_subscriptions/requests/ing/purchase

구매자 대신 렌탈·리스 중도인수를 요청합니다. 보낸 금액이 서버 계산값과 정확히 같아야 합니다. 설정이 자동 승인이면 바로 mid_term_transfer_approved 가 되고, 아니면 가맹점 승인 대기로 둡니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_request_ing_purchase
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 보내면 그 회원의 구독에만 요청합니다. 안 보내면 가맹점 대리 호출로 처리합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body user_id string 로그인한 회원(선택). 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 구독 소유 회원과 대조
body order_subscription_id string O 구독 ID
body price number O 인수 금액 (서버 계산값과 같아야 함)
body tax_free_price number O 인수 비과세 금액 (서버 계산값과 같아야 함)
body reason string 사유

응답

200 OK — 구독 상세 객체

오류

HTTP error_code 언제
403 SUBSCRIPTION_DENIED 보낸 회원(JWT·user_id)의 구독이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_PURCHASE_REQUEST_DUPLICATE 승인 대기 중인 중도인수 요청이 있음
400 ORDER_SUBSCRIPTION_PURCHASE_STATUS_INVALID subscribing 이 아니거나 중도인수를 허용하지 않는 상품
400 ORDER_SUBSCRIPTION_PURCHASE_PRICE_INVALID price 가 계산값과 다름
400 ORDER_SUBSCRIPTION_PURCHASE_TAX_FREE_PRICE_INVALID tax_free_price 가 계산값과 다름

무제한 회차 구독은 중도인수할 수 없으며, 현재 이 경우 500 이 납니다. 공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원(JWT 또는 user_id)을 함께 보내면 구독 소유 회원과 대조 (선택)
  • 2026-09-23 문서 최초 작성

GET /v1/order_subscriptions/requests/ing/calculate_termination_fee

구매자 해지 전에 중도해지 수수료와 환불액을 계산합니다. 해지 요청에 보낼 금액을 여기서 받습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_request_ing_calculate_termination_fee
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 보내면 그 회원의 구독에만 요청합니다. 안 보내면 가맹점 대리 호출로 처리합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query user_id string 로그인한 회원(선택). 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 구독 소유 회원과 대조
query order_subscription_id string 조건부 구독 ID. 없으면 order_number 필수
query order_number string 조건부 구독 주문번호

응답

200 OK

{
  "termination": {
    "order_subscription_id": "66f1...",
    "use_termination": true,
    "use_termination_approval": false,
    "use_termination_reason": true,
    "use_termination_fee": true,
    "termination_fee_label": "잔여 금액의 10%",
    "termination_fee_type": 1,
    "termination_fee_value": 10,
    "use_last_bill_refund": true,
    "remaining_duration": 9,
    "remaining_price": 261000,
    "termination_fee": 26100,
    "last_bill_refund_price": 14500,
    "final_fee": 11600,
    "final_tax_free": 0,
    "subscription_type": 5,
    "price": 29000,
    "unit": 1,
    "order_name": "정수기 렌탈",
    "subscription_payment_cycle_type": 21,
    "origin_service_start_at": "2026-01-01T00:00:00+09:00",
    "origin_service_end_at": "2026-12-31T23:59:59+09:00",
    "service_end_at": "2026-09-30",
    "last_bill_info": {},
    "is_unlimited": false,
    "cancel_date": null
  },
  "has_pending_request": false
}json
필드 타입 설명
termination.termination_fee number 중도해지 수수료
termination.last_bill_refund_price number 마지막 결제 회차 환불액
termination.final_fee number termination_fee − last_bill_refund_price. 양수면 추가 청구, 음수면 환불
termination.remaining_duration / remaining_price 남은 회차·잔여 금액 (무제한 구독은 null·0)
termination.service_end_at string 해지 후 서비스 이용 가능일
termination.use_termination_approval boolean true 면 해지 요청이 가맹점 승인 대기로 들어감
has_pending_request boolean 승인 대기 중인 요청이 있는지

이 응답의 termination_fee_type·subscription_type·unit·subscription_payment_cycle_type 은 숫자로 나옵니다. 구독 설정이 없으면 termination 대신 구독 상세와 termination.error 가 옵니다.

오류

HTTP error_code 언제
403 SUBSCRIPTION_DENIED 보낸 회원(JWT·user_id)의 구독이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_TERMINATE_UNABLE 해지할 수 있는 상태가 아님

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원(JWT 또는 user_id)을 함께 보내면 구독 소유 회원과 대조 (선택)
  • 2026-09-23 문서 최초 작성

POST /v1/order_subscriptions/requests/ing/termination

구매자 대신 중도해지를 요청합니다. 무료 체험 중이면 체험을 취소합니다. 그 밖에는 설정에 따라 즉시 해지(manual_terminated)하거나 가맹점 승인 대기로 둡니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_request_ing_termination
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 보내면 그 회원의 구독에만 요청합니다. 안 보내면 가맹점 대리 호출로 처리합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body user_id string 로그인한 회원(선택). 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 구독 소유 회원과 대조
body order_subscription_id string 조건부 구독 ID 또는 외부 ID. 없으면 order_number 필수
body order_number string 조건부 구독 주문번호
body termination_fee number 조건부 계산값이 0 이 아니면 필수
body last_bill_refund_price number 조건부 계산값이 0 이 아니면 필수
body final_fee number 조건부 계산값이 0 이 아니면 필수
body service_end_at string 서비스 이용 종료일
body reason string 조건부 상품 설정이 사유 필수면 필수

금액은 GET .../ing/calculate_termination_fee 응답의 값을 보내세요.

응답

200 OK — 구독 상세 객체

오류

HTTP error_code 언제
403 SUBSCRIPTION_DENIED 보낸 회원(JWT·user_id)의 구독이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
400 ORDER_SUBSCRIPTION_TERMINATE_CANNOT_ABLE 이미 해지·종료된 구독
400 ORDER_SUBSCRIPTION_TERMINATE_UNABLE 해지할 수 있는 상태가 아님
400 ORDER_SUBSCRIPTION_TERMINATION_REQUEST_DUPLICATE 승인 대기 중인 해지 요청이 있음
404 SUBSCRIPTION_SETTING_NOT_FOUND 구독 설정이 없음
400 SUBSCRIPTION_TERMINATION_NOT_ALLOWED 해지를 허용하지 않는 상품
400 SUBSCRIPTION_TERMINATION_REASON_REQUIRED 사유 필수인데 reason 누락
400 SUBSCRIPTION_TERMINATION_FEE1_INVALID termination_fee 누락
400 SUBSCRIPTION_TERMINATION_FEE2_INVALID last_bill_refund_price 누락
400 SUBSCRIPTION_TERMINATION_FEE3_INVALID final_fee 누락
400 ORDER_SUBSCRIPTION_FREE_TRIAL_STATUS_INVALID 무료 체험 취소 처리 중 상태 불일치

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원(JWT 또는 user_id)을 함께 보내면 구독 소유 회원과 대조 (선택)
  • 2026-09-23 문서 최초 작성

POST /v1/order_subscriptions/requests/ing/transfer

구매자 대신 양도(승계)를 요청합니다.

현재 동작하지 않습니다. 구독이 있으면 항상 500 SERVER_ERROR 를 반환하고 아무것도 바꾸지 않습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_request_ing_transfer
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 보내면 그 회원의 구독에만 요청합니다. 안 보내면 가맹점 대리 호출로 처리합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body user_id string 로그인한 회원(선택). 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 보내면 구독 소유 회원과 대조
body order_subscription_id string O 구독 ID
body new_user_id string O 새 소유 회원. 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). 이 몰의 탈퇴하지 않은 회원이어야 합니다
body new_username string O 새 계약자 이름
body new_user_email string O 새 계약자 이메일
body new_user_phone string O 새 계약자 전화번호
body new_user_address string 새 배송지
body wallet_id string 새 결제수단 ID
body reason string 사유

응답

200 OK — 구독 상세 객체 (정상 동작 시)

오류

HTTP error_code 언제
403 SUBSCRIPTION_DENIED 보낸 회원(JWT·user_id)의 구독이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
400 REQUIRED_PARAMETER_IS_MISSING new_user_id 누락 (payload.field: new_user_id)
404 USER_NOT_FOUND new_user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 이 프로젝트에 없는 구독
500 SERVER_ERROR 구독이 있으면 항상 (알려진 결함)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 new_user_id 를 이 몰의 회원으로 확인 — 아니면 404 USER_NOT_FOUND
  • 2026-09-28 회원(JWT 또는 user_id)을 함께 보내면 구독 소유 회원과 대조 (선택)
  • 2026-09-23 문서 최초 작성

GET /v1/order_subscriptions/requests

구독 변경 요청 내역을 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_request_list
  • 회원 JWT(Bootpay-User-JWT): 필요 없음. 보내도 회원으로 쓰지 않습니다(user_id 는 필터)

요청

위치 이름 타입 필수 기본값 설명
query order_subscription_id string 구독 ID 또는 외부 ID
query page integer 1 1 이상
query limit integer 20 1~100
query s_at string 오늘 요청 생성일 시작
query e_at string 오늘 요청 생성일 끝
query keyword string 검색어
query status string 요청 상태: request_requested, request_approved, request_approved_auto, request_rejected, request_withdrawn (숫자도 받음)
query request_type string 요청 유형: request_pause, request_resume, request_transfer, request_purchase, request_termination 등 (숫자도 받음)
query user_id string 이 회원의 요청만 거릅니다. 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). user_ex_uid·user_external_uid·user_uid 도 받음. 이 몰의 회원이 아니거나 탈퇴한 회원이면 404
query user_group_id string 회원 그룹 ID 또는 외부 ID

응답

200 OK

필드 타입 설명
list array 요청이 있는 구독 목록. 항목마다 request_histories 에 그 구독의 요청
count integer 조건에 맞는 요청 수
sum_* integer 상태별 구독 수
ing_pause, ing_resume, ing_transfer, ing_purchase, ing_termination integer 승인 대기 요청 수

오류

HTTP error_code 언제
400 INVALID_PARAMETER status·request_type 에 해석할 수 없는 문자열
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 user_id 가 이 몰의 회원이 아니면 404 USER_NOT_FOUND (이전에는 필터가 빠져 프로젝트 전체 요청을 돌려줌)
  • 2026-09-28 경로 수정 — 이전에는 GET /v1/order_subscriptions/:id 가 먼저 매칭되어 항상 404 ORDER_SUBSCRIPTION_NOT_FOUND 였음
  • 2026-09-02 status 를 요청 상태 문자열로도 받도록 변경
  • 2026-09-23 문서 최초 작성

GET /v1/order_subscriptions/requests/:id

구독 변경 요청 하나를 조회합니다.

현재 동작하지 않습니다. 요청이 있으면 500 SERVER_ERROR 를 반환합니다. 요청 상세는 정기구독 요청을 쓰세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_subscription_request_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 요청 ID

응답

정상 동작 시 200 OK — 요청 상세

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_REQUEST_HISTORY_NOT_FOUND 이 프로젝트에 없는 요청
500 SERVER_ERROR 요청이 있으면 항상 (알려진 결함)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

함께 보기