마이페이지 (주문·구독)

구매자 마이페이지의 주문 내역·구독 관리를 서버에서 호출하는 API 입니다. 스토어프론트 마이페이지와 같은 경로 구조를 씁니다.

두 묶음 모두 회원을 JWT 또는 user_id 로 정합니다. 회원 JWT(Bootpay-User-JWT) 헤더나 user_id(또는 user_ex_uid·user_external_uid·user_uid) 중 하나를 보내면 그 회원의 주문·구독만 보고 바꿉니다. 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다. 규칙은 인증 — 호출 구조를 봅니다.

경로 회원을 정하는 방법 둘 다 없을 때
/v1/my-page/order... (일반 주문) JWT 또는 user_id 필수 401 USER_SESSION_INVALID
/v1/my-page/order-subscription... (구독) JWT 또는 user_id 필수 400 REQUIRED_PARAMETER_IS_MISSING (payload.field: user_id)

반드시 쇼핑몰 서버에서 호출하세요. 이 API 는 secret key 로 인증하는 가맹점 권한 API 입니다. 브라우저(프론트엔드)에서 직접 부르지 말고 브라우저 → 쇼핑몰 서버(Next.js Route Handler·Server Action, Nuxt server route 등) → Bootpay commerce 로 호출합니다. user_id 는 브라우저가 보낸 값을 쓰지 말고, 서버가 자기 로그인 세션에서 꺼낸 회원 ID 를 넣습니다. 회원 확인은 쇼핑몰 서버의 책임입니다.

구독 일시정지·재개​​는 이 묶음이 아니라 POST /v1/order_subscriptions/requests/ing/pause·PUT /v1/order_subscriptions/requests/ing/resume를 씁니다. /v1/my-page/order-subscription/:id/pause·resume 경로는 없습니다.

GET /v1/my-page/order

본인의 일반 주문 목록(구독 주문 제외)을 결제일 최신순으로 돌려줍니다. 기간을 주지 않으면 최근 6개월​​입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_list
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 둘 다 없으면 401 USER_SESSION_INVALID — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query user_id string 조건부 회원 ID 또는 이 몰의 외부 회원 ID(external_uid). user_ex_uid·user_external_uid·user_uid 로도 받습니다. 회원 JWT 를 보내면 생략합니다
query s_at string 6개월 전 결제일 시작 (예: 2026-03-01). 그날 0시부터
query e_at string 오늘 결제일 끝. 그날 끝까지
query keyword string 주문 검색어
query mt integer 주문자 유형. 1 개인 · 2 사업자 · 3 사업자(부서)
query page integer 1 페이지 번호. 1 보다 작으면 1
query limit integer 10 페이지 크기. 1 보다 작으면 1. 최대값 보정 없음
  • s_at·e_at 을 날짜로 읽을 수 없으면 500 SERVER_ERROR 입니다.
  • 스토어프론트의 배송 상태·클레임 필터는 이 API 에서 받지 않습니다. 항상 전체 조건으로 조회합니다.

응답

200 OK

{
  "list": ["k2Jd9...(암호화된 문자열)"],
  "count": 23,
  "counts": {
    "fulfillment": { "all": 23, "preparing": 2, "shipping": 1, "partially_delivered": 0, "delivered": 18 },
    "claims": { "all": 23, "in_progress": 1 }
  }
}json
필드 타입 설명
list array of string 이번 페이지 주문. 각 항목이 JSON 객체가 아니라 암호화된 문자열​​입니다. 스토어프론트 화면 전용 형식이라 서버 연동에서 주문 내용을 쓰려면 GET /v1/my-page/order/:id 로 한 건씩 조회하세요
count integer 조건에 맞는 전체 주문 수
counts.fulfillment object 배송 상태별 건수. all · preparing 준비중 · shipping 배송중 · partially_delivered 부분 배송 · delivered 배송완료
counts.claims object all 전체 · in_progress 취소·반품·교환 진행 중

오류

HTTP error_code 언제
500 SERVER_ERROR s_at·e_at 형식 오류
401 USER_SESSION_INVALID 회원 JWT·user_id 가 모두 없거나 JWT 세션이 끝남
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원

회원 JWT 오류는 회원 JWT, 인증·scope 오류는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경. 둘 다 없으면 기존처럼 401
  • 2026-09-21 회원 JWT 필수로 변경 (이전에는 JWT 없이 호출하면 500)
  • 2026-09-23 문서 최초 작성

GET /v1/my-page/order/:id

본인 주문 한 건의 상세를 돌려줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_detail
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 둘 다 없으면 401 USER_SESSION_INVALID — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query user_id string 조건부 회원 ID 또는 이 몰의 외부 회원 ID(external_uid). user_ex_uid·user_external_uid·user_uid 로도 받습니다. 회원 JWT 를 보내면 생략합니다
path id string O 주문번호​(order_number). 주문 ID(order_id)가 아닙니다

응답

200 OK — 주문 기본 필드에 결과 화면용 정보가 더해진 객체입니다. 값이 null 인 추가 필드는 빠집니다.

{
  "order_id": "6650e1a0a1b2c3d4e5f60001",
  "order_number": "2405240001",
  "order_name": "유기농 원두 1kg",
  "price": 25000,
  "status": 1,
  "progress_status": 3,
  "purchased_at": "2026-05-24T10:12:00+09:00",
  "use_delivery": true,
  "amount_delivery_fee": 3000,
  "user": { },
  "user_address": {
    "address_embedded_id": "6650e1a0a1b2c3d4e5f60009",
    "name": "홍길동",
    "zipcode": "06236",
    "address": "서울 강남구 테헤란로 1",
    "address_detail": "101호",
    "tel_1": "01012345678"
  },
  "products": [],
  "result_data": { },
  "address_change_policy": { "allowed": true, "reason": "allowed", "version": "a1b2c3" },
  "order_purchases": [],
  "is_shipping_ready": false,
  "is_delivery_delayed": false,
  "coupon_discount_amount": 0,
  "point_earned_amount": 250,
  "amount_charged_point": 0
}json

주요 필드:

필드 타입 설명
order_id · order_number · order_name string 주문 ID·주문번호·주문명
price · origin_price · product_price · tax_free_price · cancelled_price number 금액
status · receipt_status · progress_status integer 주문·결제·진행 상태
purchased_at · created_at · purchase_confirmed_at string 결제·생성·구매확정 시각
use_delivery · delivery_type · amount_delivery_fee 외 amount_delivery_* 배송 여부와 배송비. amount_delivery_fee 가 0 이어도 착불 주문이면 무료가 아닙니다
user · user_address · user_group object 주문자·배송지·회원 그룹
products array 주문 상품
result_data object 결제 결과(입금 대기 주문이면 입금 안내)
bank_transfer object 무통장 입금 주문일 때만 — 은행·계좌·예금주·기한
address_change_policy object 배송지 변경 가능 여부. allowed·reason·version(가능할 때만)
claim_type · claim_status · cancelled_request_history 취소·반품·교환 상태
shipping_ready_at · is_shipping_ready · is_delivery_delayed 배송준비 전환·배송 지연 여부
order_purchases array 발주(배송 단위) 목록
coupon_discount_amount · shipping_coupon_discount_amount · applied_coupon_ids · applied_coupon_snapshots 적용 쿠폰
point_earned_amount · pending_point_amount · point_issued_at · amount_charged_point 적립·사용 적립금

구독 주문의 주문번호를 넣으면 user·user_address·result_data 대신 order_subscriptions 가 들어간 구독용 형식으로 응답합니다.

오류

HTTP error_code 언제
404 ORDER_NOT_FOUND 없는 주문번호, 다른 회원의 주문, 다른 몰의 주문
401 USER_SESSION_INVALID 회원 JWT·user_id 가 모두 없거나 JWT 세션이 끝남
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경. 둘 다 없으면 기존처럼 401
  • 2026-09-21 회원 JWT 필수로 변경
  • 2026-09-23 문서 최초 작성

PUT /v1/my-page/order/:id

본인 주문의 배송지를 출고 전에 바꿉니다. PATCH 도 같은 동작입니다.

바꿀 수 있는지는 서버가 판정합니다. 상세 조회의 address_change_policy.allowed 가 true 인 주문만 바꿀 수 있고, 새 주소의 배송비가 결제된 배송비와 다르면 거절합니다(이 API 는 추가 결제·환불을 하지 않습니다).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_update
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정). 둘 다 없으면 401 USER_SESSION_INVALID — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body/query user_id string 조건부 회원 ID 또는 이 몰의 외부 회원 ID(external_uid). user_ex_uid·user_external_uid·user_uid 로도 받습니다. 회원 JWT 를 보내면 생략합니다
path id string O 주문번호(order_number)
body field string O address 만 지원합니다. 다른 값이면 아무것도 바꾸지 않고 200 에 본문 null
body address.name string O 받는 분
body address.zipcode string O 우편번호 5자리 숫자
body address.address string O 주소
body address.address_detail string 상세주소
body address.tel_1 string O 연락처. 숫자만 남겨 9~11자리
{
  "field": "address",
  "address": {
    "name": "홍길동",
    "zipcode": "06236",
    "address": "서울 강남구 테헤란로 1",
    "address_detail": "101호",
    "tel_1": "010-1234-5678"
  }
}json

응답

200 OK — 저장된 배송지와 새 정책. 화면에는 이 값만 반영하세요.

{
  "user_address": {
    "address_embedded_id": "6650e1a0a1b2c3d4e5f60009",
    "name": "홍길동",
    "zipcode": "06236",
    "address": "서울 강남구 테헤란로 1",
    "address_detail": "101호",
    "tel_1": "01012345678",
    "is_jeju": false,
    "is_remote": false
  },
  "address_change_policy": { "allowed": true, "reason": "allowed", "version": "d4e5f6" }
}json

오류

HTTP error_code 언제
404 ORDER_NOT_FOUND 없는 주문번호, 다른 회원·다른 몰의 주문
401 USER_SESSION_INVALID 회원 JWT·user_id 가 모두 없거나 JWT 세션이 끝남
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
409 ORDER_TOO_LATE_TO_CHANGE_ADDRESS 이미 출고 단계로 넘어감
409 ORDER_ADDRESS_CHANGE_NOT_ALLOWED 배송지 변경 대상이 아님 (구독·배송 없음·택배 아님·기존 주소 없음)
409 ORDER_ADDRESS_CHANGE_CLAIM_IN_PROGRESS 취소·반품·교환 진행 중
409 ORDER_ADDRESS_CHANGE_ALREADY_SHIPPED 일부 발주가 이미 발송됨
409 ORDER_ADDRESS_CHANGE_DELIVERY_FEE_DIFF 새 주소의 배송비가 결제된 배송비와 다름
409 ORDER_ADDRESS_CHANGE_DELIVERY_FEE_UNVERIFIABLE 새 주소의 배송비를 계산할 수 없음
409 ORDER_ADDRESS_CHANGE_POLICY_STALE 저장하는 사이 주문 상태가 바뀜. 다시 조회 후 시도
400 ORDER_ADDRESS_FIELD_BLANK 받는 분·주소·우편번호 누락
400 ORDER_ADDRESS_ZIPCODE_INVALID 우편번호가 5자리 숫자가 아님
400 ORDER_ADDRESS_TEL_INVALID 연락처가 9~11자리가 아님
500 SERVER_ERROR field=address 인데 address 객체가 없음

409 응답의 payload.address_change_policy 에 현재 정책이 실립니다.

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경. 둘 다 없으면 기존처럼 401
  • 2026-09-18 구매자 배송지 변경 검증(소유권·출고 상태·배송비) 추가
  • 2026-09-23 문서 최초 작성

POST /v1/my-page/order-subscription/:id/recover

결제 실패로 보류(HOLD_ON) 된 구독을 복구합니다. 중단된 회차가 있으면 지금 결제를 시도하고, 성공하면 구독을 다시 활성화합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_recover
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(또는 user_ex_uid·user_external_uid·user_uid, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400 REQUIRED_PARAMETER_IS_MISSING — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID (order_subscription_id)
body/query user_id string 조건부 회원 ID 또는 이 몰의 외부 회원 ID(external_uid). user_ex_uid·user_external_uid·user_uid 로도 받습니다. 회원 JWT 를 보내면 생략합니다

응답

200 OK — 구독 정보에 결과 필드가 더해집니다.

{
  "order_subscription_id": "6651a0c2a1b2c3d4e5f60333",
  "order_number": "S2405250001",
  "status": 1,
  "recovered": true
}json
필드 타입 설명
recovered boolean 복구 성공 여부. 결제 실패면 false 이고 구독은 보류 상태로 남습니다 (HTTP 는 200)
error_message string recovered: false 일 때 결제 실패 사유
(그 밖) 구독 기본 필드(목록 항목과 같은 이름)와 products·options·user_address·applied_coupons 등

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING 회원 JWT·user_id 가 모두 없음
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독, 다른 몰의 구독
403 SUBSCRIPTION_DENIED 지정한 회원의 구독이 아님
400 ORDER_SUBSCRIPTION_RECOVER_UNABLE 보류 상태가 아니거나, 결제 실패로 중단된 회차가 없음

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id 로 정할 수 있게 변경(이전에는 user_id 만, JWT 는 무시). 탈퇴한 회원의 user_id 는 404 USER_NOT_FOUND
  • 2026-09-28 회원 파라미터가 없으면 500 대신 400 REQUIRED_PARAMETER_IS_MISSING, 이 몰에 없는 회원은 404 USER_NOT_FOUND
  • 2026-09-23 문서 최초 작성

GET /v1/my-page/order-subscription/:id/recovery-info

구독을 다시 살리려면 무엇을 해야 하는지 알려줍니다. 상태에 따라 응답 모양이 다릅니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_recovery_info
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(또는 user_ex_uid·user_external_uid·user_uid, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400 REQUIRED_PARAMETER_IS_MISSING — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID
body/query user_id string 조건부 회원 지정. recover 와 같음. 회원 JWT 를 보내면 생략합니다

응답

200 OK

보류(HOLD_ON) — 복구 결제 필요:

{
  "action_type": "recover",
  "subscription_status": -3,
  "hold_on_since": "2026-05-20T00:00:00+09:00",
  "hold_on_days": 5,
  "failed_bill": {
    "bill_id": "6651c0c2a1b2c3d4e5f60888",
    "duration": 3,
    "amount": 29000,
    "failed_at": "2026-05-20T00:00:00+09:00",
    "last_error_message": "잔액이 부족합니다"
  },
  "current_billing_key": { "card_company": "신한", "card_no": "5361********1234" }
}json

일시정지(PAUSE) — 재개:

{
  "action_type": "resume",
  "subscription_status": -2,
  "paused_since": "2026-05-01T00:00:00+09:00",
  "paused_days": 24,
  "pause_expected_resume_at": "2026-06-01T00:00:00+09:00",
  "approval_required": false,
  "has_pending_request": false
}json

활성(ACTIVE) + 결제 실패 회차 있음 — 재결제: action_type: "retry_bill", has_failed_bill: true, failed_bill(위와 같은 필드), current_billing_key.

그 밖의 상태, 또는 활성인데 실패 회차가 없으면 빈 객체 {} 입니다.

필드 설명
action_type recover → recover, retry_bill → retry-bill, resume → 재개 신청
failed_bill.bill_id retry-bill 에 넘길 회차 ID
current_billing_key 결제에 쓰일 카드 요약. 정보가 없으면 빠집니다
approval_required 재개에 판매자 승인이 필요한지

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING 회원 JWT·user_id 가 모두 없음
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독, 다른 몰의 구독
403 SUBSCRIPTION_DENIED 지정한 회원의 구독이 아님

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id 로 정할 수 있게 변경(이전에는 user_id 만, JWT 는 무시). 탈퇴한 회원의 user_id 는 404 USER_NOT_FOUND
  • 2026-09-28 회원 파라미터가 없으면 500 대신 400 REQUIRED_PARAMETER_IS_MISSING, 이 몰에 없는 회원은 404 USER_NOT_FOUND
  • 2026-09-23 문서 최초 작성

POST /v1/my-page/order-subscription/:id/retry-bill

활성 구독에서 결제에 실패한 회차 하나를 지금 다시 결제합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_retry_bill
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(또는 user_ex_uid·user_external_uid·user_uid, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400 REQUIRED_PARAMETER_IS_MISSING — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID
body/query user_id string 조건부 회원 지정. recover 와 같음. 회원 JWT 를 보내면 생략합니다
body bill_id string O 다시 결제할 회차 ID (recovery-info 의 failed_bill.bill_id)

응답

200 OK — 결제 실패도 HTTP 200 으로 옵니다. retried 로 판단하세요.

성공:

{
  "retried": true,
  "bill_id": "6651c0c2a1b2c3d4e5f60888",
  "bill_status": "paid",
  "amount": 29000,
  "paid_at": "2026-05-25T10:00:00+09:00",
  "message": "결제가 완료되었습니다."
}json

실패:

{
  "retried": false,
  "bill_id": "6651c0c2a1b2c3d4e5f60888",
  "bill_status": "failed",
  "error_message": "잔액이 부족합니다",
  "message": "결제에 실패했습니다. 결제수단을 변경 후 다시 시도해주세요."
}json
필드 타입 설명
retried boolean 결제 성공 여부
bill_status string paid 또는 failed
amount · paid_at 성공 시 결제 금액·시각
error_message string 실패 사유
message string 화면에 보여줄 안내

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING 회원 JWT·user_id 가 모두 없음
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독, 다른 몰의 구독
403 SUBSCRIPTION_DENIED 지정한 회원의 구독이 아님
400 SUBSCRIPTION_NOT_ACTIVE 활성 상태가 아닌 구독
404 ORDER_SUBSCRIPTION_BILL_NOT_FOUND 이 구독의 회차가 아닌 bill_id
400 ORDER_SUBSCRIPTION_BILL_NOT_FAILED 결제 실패 상태가 아닌 회차

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id 로 정할 수 있게 변경(이전에는 user_id 만, JWT 는 무시). 탈퇴한 회원의 user_id 는 404 USER_NOT_FOUND
  • 2026-09-28 회원 파라미터가 없으면 500 대신 400 REQUIRED_PARAMETER_IS_MISSING, 이 몰에 없는 회원은 404 USER_NOT_FOUND
  • 2026-09-23 문서 최초 작성

GET /v1/my-page/order-subscription

지정한 회원의 구독 목록을 생성일 최신순으로 돌려줍니다. 기간을 주지 않으면 최근 6개월​​에 생성된 구독입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_list
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(또는 user_ex_uid·user_external_uid·user_uid, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400 REQUIRED_PARAMETER_IS_MISSING — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query user_id string 조건부 회원 지정. recover 와 같음. 회원 JWT 를 보내면 생략합니다
query s_at string 6개월 전 생성일 시작 (예: 2026-03-01)
query e_at string 오늘 생성일 끝
query mt integer 주문자 유형. 1 개인 · 2 사업자 · 3 사업자(부서)
query page integer 1 페이지 번호. 1 이상으로 보내세요 (0 이하면 500)
query limit integer 10 페이지 크기. 1 이상으로 보내세요

응답

200 OK

{
  "list": [
    {
      "order_subscription_id": "6651a0c2a1b2c3d4e5f60333",
      "order_number": "S2405250001",
      "order_name": "원두 정기배송",
      "status": 1,
      "price": 29000,
      "quantity": 1,
      "current_duration": 3,
      "total_subscription_duration": 12,
      "payment_next_at": "2026-06-25T00:00:00+09:00",
      "products": [],
      "options": [],
      "order_subscription_adjustments": [],
      "chosen_product_options": [],
      "created_at": "2026-03-25T09:00:00+09:00",
      "has_failed_bill": false
    }
  ],
  "count": 2
}json
필드 타입 설명
list[].order_subscription_id string 구독 ID — 복구·재결제·변경 API 의 :id
list[].order_number string 구독 주문번호 — 상세 조회 API 의 :id
list[].status integer 구독 상태
list[].payment_next_at string 다음 결제 예정 시각
list[].products · options · chosen_product_options array 상품·옵션 스냅샷
list[].order_subscription_adjustments array 금액 조정(쿠폰 할인 등)
list[].has_failed_bill boolean 활성 구독에만 있음. 결제 실패 회차가 있으면 true → recovery-info
count integer 전체 건수

이 밖에 결제 주기·배송·일시정지·무료체험 관련 구독 기본 필드가 함께 옵니다.

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING 회원 JWT·user_id 가 모두 없음
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
500 SERVER_ERROR s_at·e_at 형식 오류, page 0 이하

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id 로 정할 수 있게 변경(이전에는 user_id 만, JWT 는 무시). 탈퇴한 회원의 user_id 는 404 USER_NOT_FOUND
  • 2026-09-28 회원 파라미터가 없으면 500 대신 400 REQUIRED_PARAMETER_IS_MISSING, 이 몰에 없는 회원은 404 USER_NOT_FOUND
  • 2026-09-23 문서 최초 작성

GET /v1/my-page/order-subscription/:id

지정한 회원의 구독 한 건의 상세를 돌려줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_detail
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(또는 user_ex_uid·user_external_uid·user_uid, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400 REQUIRED_PARAMETER_IS_MISSING — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 주문번호​(order_number). 구독 ID 가 아닙니다
query user_id string 조건부 회원 지정. recover 와 같음. 회원 JWT 를 보내면 생략합니다

응답

200 OK

{
  "subscription_data": {
    "order_subscription_id": "6651a0c2a1b2c3d4e5f60333",
    "order_number": "S2405250001",
    "status": 1,
    "order_subscription_bills": [],
    "service_status": { },
    "request_histories": [],
    "user_address": { },
    "subscription_policy": {
      "use_pause": true,
      "use_pause_approval": false,
      "pause_max_count": 2,
      "use_termination": true
    }
  }
}json
필드 타입 설명
subscription_data object 구독 상세. 목록 항목의 필드에 회차(order_subscription_bills)·요청 이력(request_histories)·배송지·서비스 상태 등이 더해집니다
subscription_data.subscription_policy object 구매자에게 보여줄 계약 정책(결제 실패 처리·연체료·일시정지·중도해지 규칙). 설정이 없으면 null

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING 회원 JWT·user_id 가 모두 없음
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 주문번호, 지정한 회원의 구독이 아님

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id 로 정할 수 있게 변경(이전에는 user_id 만, JWT 는 무시). 탈퇴한 회원의 user_id 는 404 USER_NOT_FOUND
  • 2026-09-28 user_id 로 회원을 받아 그 회원의 구독 상세가 조회됨(이전에는 항상 404)
  • 2026-09-22 응답에 subscription_policy 추가
  • 2026-09-23 문서 최초 작성

PUT /v1/my-page/order-subscription/:id

지정한 회원 구독의 배송지를 바꿉니다. PATCH 도 같은 동작입니다. 구매자가 바꿀 수 있는 것은 배송지(field=address)뿐입니다. 수량·회차·무료체험·서비스 기간 같은 계약 정보는 가맹점 서버의 PUT /v1/order_subscriptions/:id로 바꿉니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_update
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(또는 user_ex_uid·user_external_uid·user_uid, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400 REQUIRED_PARAMETER_IS_MISSING — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 구독 ID (order_subscription_id)
body/query user_id string 조건부 회원 ID 또는 이 몰의 외부 회원 ID(external_uid). user_ex_uid·user_external_uid·user_uid 로도 받습니다. 회원 JWT 를 보내면 생략합니다
body field string O address
body address.zipcode string O 우편번호
body address.address string O 주소
body address.address_detail string 상세주소
body address.name string 받는 분
body address.tel_1 string 연락처

보낸 값으로 구독 배송지를 통째로 바꿉니다. 보내지 않은 선택 항목은 비워집니다. 일반 주문 배송지 변경과 달리 출고 상태·배송비는 검사하지 않습니다.

응답

204 No Content (본문 없음).

오류

HTTP error_code 언제
400 INVALID_PARAMETER field 가 address 가 아님 (payload.allowed 에 허용 값)
400 REQUIRED_PARAMETER_IS_MISSING address.zipcode·address.address 누락 (payload.field)
400 REQUIRED_PARAMETER_IS_MISSING 회원 JWT·user_id 가 모두 없음
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 ORDER_SUBSCRIPTION_NOT_FOUND 없는 구독, 다른 몰의 구독
403 SUBSCRIPTION_DENIED 지정한 회원의 구독이 아님

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id 로 정할 수 있게 변경(이전에는 user_id 만, JWT 는 무시). 탈퇴한 회원의 user_id 는 404 USER_NOT_FOUND
  • 2026-09-28 배송지 변경 500(기존 배송지가 있는 구독) 수정, 배송지 외 변경은 500 대신 400, 배송지 필수 항목 검사
  • 2026-09-23 문서 최초 작성

함께 보기