구매자가 진행 중인 정기구독에 대해 낸 요청(일시정지·재개·중도해지·중도인수·이전·플랜 변경 등)을 조회하고, 가맹점이 승인·거절합니다. 요청 한 건이 이 문서의 리소스 한 건입니다.
/v1/order_subscriptions/requests 와의 차이
같은 요청 데이터를 다루는 API 가 두 벌 있습니다.
이 문서 (/v1/order-subscription-requests) |
정기구독의 /v1/order_subscriptions/requests |
|
|---|---|---|
| 요청 만들기 | 없음 | 있음 (일시정지·해지·인수·이전 등 요청 생성, 비용 계산) |
| 목록 | 회원 모드 + 관리 모드(project_id 를 보낼 때) |
관리 모드만 |
| 상세 | 요청 + 해당 구독의 추가 청구(supplemental_charges) |
요청 상세 |
| 승인·거절 | PUT /:id 에 approval: approve | reject |
없음 (이 문서의 PUT /:id 를 씁니다) |
| scope 이름 | *:order_subscription_request_* |
supervisor:order_subscription_* |
요청을 만들 때는 /v1/order_subscriptions/requests 쪽을 씁니다.
요청 유형·상태
응답의 request_type·request_status·payment_status 는 아래 문자열로 나갑니다. 요청 파라미터에는 숫자와 문자열 모두 쓸 수 있습니다.
| request_type | 숫자 | 뜻 |
|---|---|---|
request_pause |
11 | 일시정지 |
request_resume |
12 | 재개 |
request_transfer |
21 | 이전·승계 |
request_purchase |
31 | 중도 인수 |
request_termination |
41 | 중도 해지 |
request_termination_restore |
42 | 해지 철회 |
request_migrate_plan |
51 | 플랜 변경 |
request_expired_purchase |
101 | 만기 후 구매 |
request_expired_return |
111 | 만기 후 반납 |
request_expired_extend |
121 | 만기 후 연장 |
| request_status | 숫자 | 뜻 |
|---|---|---|
request_requested |
0 | 요청됨 (처리 대기) |
request_approved |
1 | 승인 |
request_approved_auto |
2 | 자동 승인 |
request_rejected |
-1 | 거절 |
request_withdrawn |
-2 | 구매자가 철회 |
| payment_status | 뜻 |
|---|---|
order_pending |
결제 대기 |
payment_completed |
결제 완료 |
payment_failed |
결제 실패 |
요청 항목 필드
목록·상세에 나오는 요청 한 건의 필드입니다. 값이 없는 필드는 빠집니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| order_subscription_request_history_id | string | 요청 ID (:id 에 넣는 값) |
| order_subscription_id | string | 구독 ID |
| project_id / seller_id | string | 프로젝트·판매자 ID |
| user_id / user_group_id | string | 요청한 회원·회원 그룹 |
| request_type / request_status / payment_status | string | 위 표 |
| requested_at / actioned_at / withdrawn_at | string | 요청·처리·철회 시각 |
| request_reason / action_reason | string | 요청 사유 / 처리(승인·거절) 사유 |
| admin_id / admin_email / admin_name | string | 처리한 관리자 |
| paused_at / pause_expected_resume_at / pause_resumed_at | string | 일시정지 시작 / 예상 재개 / 실제 재개 |
| new_user_id / new_username / new_user_email / new_user_phone | string | 이전·승계 받는 사람 |
| termination_fee / last_bill_refund_price / final_fee / final_tax_free | number | 해지 수수료 / 마지막 회차 환불액 / 최종 청구액 / 그중 비과세 |
| termination_fee_label / termination_fee_type / termination_fee_value | 해지 비용 이름·부과 방식·값 | |
| termination_remaining_duration / termination_remaining_price | number | 남은 기간(초) / 남은 금액 |
termination_fee_changed 외 termination_fee_changed_* |
해지 수수료를 관리자가 바꾼 경우의 변경 전 값·사유·시각 | |
| terminated_at / service_end_at | string | 해지일 / 서비스 종료일 |
| migrate_plan_target_product_id / migrate_plan_target_product_option_id | string | 플랜 변경 대상 상품·옵션 |
| migrate_plan_strategy | string | 적용 시점 (next_cycle) |
| migrate_plan_snapshot | object | 변경 전·후 상품 (before·after: product_id, product_name, product_image, price, payment_cycle_type) |
| unit | integer | 통화 (1 KRW) |
| metadata | object | 부가 정보 |
| ip | string | 요청 IP |
| created_at / updated_at | string | 생성·수정 시각 |
GET /v1/order-subscription-requests
요청 목록을 조회합니다. project_id 를 보내는지에 따라 두 모드로 나뉩니다.
- 관리 모드 (
project_id있음): 프로젝트 전체 요청을 구독 단위로 묶어 검색하고, 상태별 합계를 함께 돌려줍니다.project_id값은 모드 전환에만 쓰고, 조회 범위는 항상 인증된 프로젝트입니다. - 회원 모드 (
project_id없음): 회원 본인의 최근 요청. 회원은 JWT 또는 user_id 로 정합니다(필수).
회원 모드에
project_id를 실수로 넣으면 관리 모드(프로젝트 전체 요청)가 됩니다. 구매자 화면용 호출에는 넣지 마세요.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope
- 관리 모드:
supervisor:order_subscription_request_list - 회원 모드:
user:order_subscription_request_list Bootpay-Role헤더를 보내면 앞의 역할 부분이 그 값으로 바뀝니다
- 관리 모드:
- 회원
- 관리 모드: 필요 없음.
user_id는 필터로만 씁니다 - 회원 모드: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정). 둘 다 없으면 400REQUIRED_PARAMETER_IS_MISSING— 회원 JWT
- 관리 모드: 필요 없음.
요청
관리 모드
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | project_id | string | O | 아무 값이나. 있으면 관리 모드 | |
| query | s_at | string | 오늘 | 조회 시작일 (YYYY-MM-DD). 요청 생성일 기준 |
|
| query | e_at | string | 오늘 | 조회 종료일 (YYYY-MM-DD) |
|
| query | order_subscription_id | string | 구독 ID 또는 구독의 가맹점 고유값 | ||
| query | user_id | string | 이 회원의 요청만 거릅니다. 24자리면 회원 ID, 그 밖은 이 몰의 외부 회원 ID(ex_uid). user_ex_uid·user_external_uid·user_uid 도 받음. 이 몰의 회원이 아니거나 탈퇴한 회원이면 404 |
||
| query | user_group_id | string | 회원 그룹 ID 또는 uid |
||
| query | request_type | string | integer | 요청 유형 하나 (예: request_termination 또는 41) |
||
| query | status | string | integer | 요청 상태 하나 (예: request_requested 또는 0). 구독 상태가 아니라 요청 상태입니다 |
||
| query | keyword | string | 검색어 | ||
| query | page | integer | 1 | 페이지 | |
| query | limit | integer | 20 | 페이지 크기. 100 을 넘으면 100 건만 옵니다 |
s_at·e_at을 보내지 않으면 오늘 생성된 요청만 나옵니다. 기간을 꼭 지정하세요.order_subscription_id·user_group_id가 이 프로젝트에 없으면 그 조건은 빠지고 조회됩니다.user_id는404 USER_NOT_FOUND입니다.- 해석할 수 없는
status·request_type값은400 INVALID_PARAMETER입니다.
회원 모드
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | user_id | string | 조건부 | 회원 ID 또는 이 몰의 외부 회원 ID(ex_uid). user_ex_uid·user_external_uid·user_uid 로도 받습니다. 회원 JWT 를 보내면 생략합니다 |
|
| query | limit | integer | 20 | 최근 몇 건 (최대 100). 페이지는 없습니다 |
응답
200 OK — 관리 모드
{
"list": [
{
"order_subscription_id": "66a1...",
"status": "subscribing",
"request_histories": [
{
"order_subscription_request_history_id": "66f1...",
"order_subscription_id": "66a1...",
"request_type": "request_termination",
"request_status": "request_requested",
"requested_at": "2026-09-23T09:10:00+09:00",
"request_reason": "이사",
"termination_fee": 30000,
"final_fee": 30000
}
]
}
],
"count": 1,
"sum_pending": 0,
"sum_trial": 0,
"sum_active": 12,
"sum_pause": 1,
"sum_hold_on": 0,
"sum_auto_end": 0,
"sum_terminated": 3,
"sum_first_payment_error": 0,
"sum_cancel_request": 1,
"ing_pause": 0,
"ing_resume": 0,
"ing_transfer": 0,
"ing_purchase": 0,
"ing_termination": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list[] | object | 요청이 걸린 구독 요약. 필드는 정기구독 목록 항목과 같습니다 |
| list[].request_histories | array | 이 페이지에 포함된 그 구독의 요청들 (위 요청 항목 필드) |
| count | integer | 조건에 맞는 요청 수 |
| sum_* | integer | 같은 기간·조건의 구독 상태별 개수 (대기·체험·구독중·일시정지·보류·자동종료·해지·첫 결제 실패·해지 요청) |
| ing_pause, ing_resume, ing_transfer, ing_purchase, ing_termination | integer | 처리 대기 중인 요청의 유형별 개수. 만기 후 요청이 있으면 expired_purchase·expired_return·expired_extend 도 붙습니다 |
- 목록은 요청 한 건마다 구독 항목 하나입니다. 한 구독에 요청이 여러 건이면 같은 구독이 여러 번 나오고, 각 항목의
request_histories에는 그 구독의 요청이 모두 들어 있습니다. 화면에 그릴 때는order_subscription_id로 중복을 걸러 주세요.
200 OK — 회원 모드
{
"list": [ { "order_subscription_request_history_id": "66f1...", "request_type": "request_pause" } ],
"count": 1
}json회원 모드의 count 는 이번에 돌려준 개수입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | INVALID_PARAMETER |
status·request_type 값을 해석할 수 없음 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
회원 모드인데 회원 JWT·user_id 가 모두 없음 (payload.field: user_id) |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 (두 모드 모두) |
| 403 | USER_NOT_MATCH |
회원 모드에서 JWT 와 user_id 가 서로 다른 회원 |
| 401 | USER_SESSION_INVALID · USER_JWT_INVALID |
회원 모드에서 보낸 JWT 가 무효·만료 |
| 500 | SERVER_ERROR |
s_at·e_at 이 날짜 형식이 아님 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원 모드가 JWT 또는
user_id로 동작 (이전에는 항상500). 관리 모드user_id가 이 몰의 회원이 아니면404 USER_NOT_FOUND(이전에는 필터가 빠져 전체 조회) - 2026-09-23 문서 최초 작성
- 2026-08-27
status·request_type에 문자열 값 허용 (숫자도 계속 동작).status필터가 요청 상태에 제대로 걸리도록 수정
GET /v1/order-subscription-requests/:id
요청 한 건과, 그 구독에 붙은 추가 청구 목록을 조회합니다.
project_id 없이 호출하면(회원 모드) 지정한 회원의 요청만 볼 수 있습니다. 회원은 JWT 또는 user_id 로 정합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
project_id있음 →supervisor:order_subscription_request_detail, 없음 →user:order_subscription_request_detail(Bootpay-Role로 역할 부분 변경 가능) - 회원:
project_id를 보내면 필요 없음. 없으면 JWT 또는 user_id 필수 —Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정). 둘 다 없으면 400REQUIRED_PARAMETER_IS_MISSING— 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 요청 ID (order_subscription_request_history_id) |
|
| query | project_id | string | 아무 값이나. 있으면 프로젝트의 모든 요청을 볼 수 있습니다 | ||
| query | user_id | string | 조건부 | 회원 모드의 회원 지정. 회원 JWT 를 보내면 생략합니다 |
응답
200 OK
{
"order_subscription_request_history_id": "66f1...",
"order_subscription_id": "66a1...",
"request_type": "request_migrate_plan",
"request_status": "request_requested",
"requested_at": "2026-09-23T09:10:00+09:00",
"migrate_plan_strategy": "next_cycle",
"migrate_plan_snapshot": {
"before": { "product_id": "65...", "product_name": "베이직", "price": 9900, "payment_cycle_type": 21 },
"after": { "product_id": "65...", "product_name": "프로", "price": 19900, "payment_cycle_type": 21 }
},
"supplemental_charges": []
}json위 요청 항목 필드에 더해 다음이 붙습니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| supplemental_charges | array | 이 구독의 추가 청구 내역 (최신순) |
| migrate_plan_snapshot | object | 플랜 변경 요청일 때만. 저장된 값이 비어 있으면 현재 구독·대상 상품으로 채워 줍니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ORDER_SUBSCRIPTION_REQUEST_HISTORY_NOT_FOUND |
이 프로젝트에 없는 요청, 회원 모드에서 다른 회원의 요청 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
회원 모드인데 회원 JWT·user_id 가 모두 없음 |
| 404 | USER_NOT_FOUND |
회원 모드 user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 403 | USER_NOT_MATCH |
회원 모드에서 JWT 와 user_id 가 서로 다른 회원 |
변경 이력
- 2026-09-28 회원 모드가 JWT 또는
user_id로 동작 (이전에는 항상500) - 2026-09-23 문서 최초 작성
PUT /v1/order-subscription-requests/:id
처리 대기 중인 요청을 승인하거나 거절합니다. 요청 유형에 맞는 처리(일시정지 적용, 해지 진행, 인수 결제 대기 전환, 플랜 변경 예약 등)가 함께 일어납니다. PATCH 도 같습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:order_subscription_request_update(Bootpay-Role로 역할 부분 변경 가능) - 회원 JWT: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 요청 ID | |
| body | approval | string | O | approve 또는 reject (대소문자 무관). action 은 예약어라 이 이름을 씁니다 |
|
| body | reason | string | 거절 시 O | 처리 사유. action_reason 으로 보내도 됩니다 |
|
| body | price | number | 인수 승인 시 O | 중도 인수 금액 | |
| body | tax_free_price | number | 인수 금액 중 비과세 | ||
| body | termination_fee | number | 해지 승인 시 확정할 해지 수수료 | ||
| body | last_bill_refund_price | number | 해지 승인 시 마지막 회차 환불액 | ||
| body | final_fee | number | 해지 승인 시 최종 청구액 | ||
| body | service_end_at | string | 해지 승인 시 서비스 종료일 |
유형별로 승인·거절할 수 있는 요청
| request_type | 승인 | 거절 |
|---|---|---|
| 일시정지(11) | O | O (사유 필수) |
| 재개(12) | O (즉시 재개) | 아무것도 바꾸지 않고 200 으로 끝납니다 |
| 중도 해지(41) | O | O (사유 필수) |
| 중도 인수(31) | O (price 필수) |
O (사유 필수) |
| 이전·승계(21) | O | O (사유 필수) |
| 플랜 변경(51) | O | O (사유 필수) |
| 그 외(42, 101, 111, 121) | 400 ORDER_SUBSCRIPTION_REQUEST_TYPE_INVALID |
같음 |
응답
200 OK
응답 본문 형식은 요청 유형마다 다르고 보장하지 않습니다. 성공 여부는 HTTP 상태로 판단하고, 결과는 GET /v1/order-subscription-requests/:id 로 다시 조회하세요.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | ORDER_SUBSCRIPTION_REQUEST_TYPE_INVALID |
approval 이 approve/reject 가 아님, 또는 승인·거절할 수 없는 유형 |
| 404 | ORDER_SUBSCRIPTION_REQUEST_HISTORY_NOT_FOUND |
이 프로젝트에 없는 요청 |
| 400 | ORDER_SUBSCRIPTION_REQUEST_HISTORY_ALREADY_PROCESSED |
이미 처리됐거나 철회된 요청 |
| 400 | ORDER_SUBSCRIPTION_REJECT_REASON_BLANK |
거절인데 사유 없음 |
| 400 | ORDER_SUBSCRIPTION_PAUSE_APPROVE_ERROR / ORDER_SUBSCRIPTION_PAUSE_REJECT_ERROR |
일시정지를 지금 승인·거절할 수 없는 상태 |
| 400 | ORDER_SUBSCRIPTION_RESUME_REQUEST_ERROR |
재개할 수 없는 상태 |
| 400 | ORDER_SUBSCRIPTION_TERMINATE_REQUEST_ERROR / ORDER_SUBSCRIPTION_TERMINATE_REJECT_ERROR |
해지를 지금 승인·거절할 수 없는 상태 |
| 400 | ORDER_SUBSCRIPTION_PURCHASE_REQUEST_ERROR / ORDER_SUBSCRIPTION_PURCHASE_REJECT_ERROR |
인수를 지금 승인·거절할 수 없는 상태 |
| 400 | ORDER_SUBSCRIPTION_PURCHASE_PRICE_REQUIRED |
인수 승인인데 price 없음 |
| 404 | ORDER_SUBSCRIPTION_NOT_FOUND |
플랜 변경 승인 시 구독이 없음 |
| 500 | SERVER_ERROR |
이전·승계 요청을 처리할 수 없는 상태이거나 거절 사유가 없을 때 |
변경 이력
- 2026-09-23 문서 최초 작성
