구매자 마이페이지의 주문 내역·구독 관리를 서버에서 호출하는 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(쇼핑몰 서버 지정). 둘 다 없으면 401USER_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(쇼핑몰 서버 지정). 둘 다 없으면 401USER_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(쇼핑몰 서버 지정). 둘 다 없으면 401USER_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, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400REQUIRED_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, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400REQUIRED_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, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400REQUIRED_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, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400REQUIRED_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, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400REQUIRED_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, 쇼핑몰 서버의 로그인 세션에서 꺼낸 값). 둘 다 없으면 400REQUIRED_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 문서 최초 작성
