정기구독(구독 계약)을 조회하고, 가맹점 서버가 계약을 변경·승인·거절·일시정지·재개·해지·중도인수·양도하는 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)은 주기 스케줄 없이, 가맹점이 필요할 때 금액을 정해 결제합니다.
- 구매자가 결제창에서 자동결제에 동의하고 첫 결제를 마치면, 구독에 재결제 키(
charge_key) 가 발급됩니다. - 가맹점 서버가 첫 결제 주문을
GET /v1/orders/:id로(회원 JWT 없이) 조회하면 응답에charge_key가 들어 있습니다 — 주문. 이 키는 서버에만 보관하세요. 키와 금액만 있으면 결제가 됩니다. - 결제:
POST /v1/order_subscriptions/charge에charge_key와price를 보냅니다. 회원(Bootpay-User-JWT헤더 또는 최상위user_id, 하위호환user.user_id)은 선택이며, 보내면 키 소유 회원과 일치하는지 한 번 더 확인합니다. 결제가 끝나면 청구 회차와 주문이 만들어지고 결과를 바로 돌려줍니다. 다음 결제 예정일은 만들지 않습니다. - 해지:
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 | 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만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원: 선택 —
Bootpay-User-JWT또는user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독에만 동작합니다(아니면 403SUBSCRIPTION_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) — 지정 회원이 구독 소유자가 아니면 403SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404COUPON_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만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원: 선택 —
Bootpay-User-JWT또는user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독에만 동작합니다(아니면 403SUBSCRIPTION_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) — 지정 회원이 구독 소유자가 아니면 403SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404COUPON_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만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원: 선택 —
Bootpay-User-JWT또는user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독에만 동작합니다(아니면 403SUBSCRIPTION_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) — 지정 회원이 구독 소유자가 아니면 403SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404COUPON_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만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원: 선택 —
Bootpay-User-JWT또는user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독에만 동작합니다(아니면 403SUBSCRIPTION_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": "만료된 쿠폰입니다." }jsonok: 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) — 지정 회원이 구독 소유자가 아니면 403SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404COUPON_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만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원: 선택 —
Bootpay-User-JWT또는user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독에만 동작합니다(아니면 403SUBSCRIPTION_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) — 지정 회원이 구독 소유자가 아니면 403SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404COUPON_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만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원: 선택 —
Bootpay-User-JWT또는user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독에만 동작합니다(아니면 403SUBSCRIPTION_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) — 지정 회원이 구독 소유자가 아니면 403SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404COUPON_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만 받습니다(그 밖의 값은 401API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면user입니다 - 회원: 선택 —
Bootpay-User-JWT또는user_id(쇼핑몰 서버 지정)로 회원을 밝히면 그 회원의 구독에만 동작합니다(아니면 403SUBSCRIPTION_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) — 지정 회원이 구독 소유자가 아니면 403SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰은 404COUPON_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 문서 최초 작성
