정기구독 요청

구매자가 진행 중인 정기구독에 대해 낸 요청​(일시정지·재개·중도해지·중도인수·이전·플랜 변경 등)을 조회하고, 가맹점이 승인·거절합니다. 요청 한 건이 이 문서의 리소스 한 건입니다.

/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(쇼핑몰 서버 지정). 둘 다 없으면 400 REQUIRED_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(쇼핑몰 서버 지정). 둘 다 없으면 400 REQUIRED_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 문서 최초 작성

함께 보기