구독

계약 조회

구독 계약 목록에서 상태·주기·다음 결제일을 함께 봐요.

구독 계약 목록을 조회해요. 주문과 연결된 구독 계약의 상태, 결제 주기, 다음 결제일 등을 확인할 수 있어요.

API 엔드포인트

GEThttps://api.bootapi.com/v1/order_subscriptionsBasic Auth

요청 파라미터

파라미터 타입 필수 설명
order_id String 선택 주문 ID로 필터
user_id String 선택 고객 ID로 필터
status Integer 선택 구독 상태 필터
page Integer 선택 페이지 번호 (기본: 1)
limit Integer 선택 페이지당 데이터 수 (기본: 20)

구독 상태 코드

상태 설명
0 대기 승인 대기 중
PROCESS_DUPLICATED 이미 처리된 요청이에요 정상 구독 진행
2 일시정지 구독 일시 중단
3 해지 중도 해지 완료
4 만료 구독 기간 종료

코드 예제

const { BootpayCommerce } = require('@bootpay/backend-js')

const commerce = new BootpayCommerce({
    client_key: 'your-commerce-client-key',
    secret_key: 'your-commerce-secret-key',
    mode: 'production'
})

const response = await commerce.orderSubscription.list({
    page: 1,
    limit: 20,
    status: 1
})
console.log(response)javascript

응답

성공 응답

{
  "count": 3,
  "list": [
    {
      "id": "687a1b2c3d4e5f6789012345",
      "order_id": "68707c59b0eacea5cd974efd",
      "user_id": "67e4b4425ec892162491d0ec",
      "status": 1,
      "subscription_setting_id": "sub_setting_001",
      "billing_cycle": "monthly",
      "price": 29900,
      "next_billing_at": "2025-08-01T00:00:00Z",
      "service_start_at": "2025-07-01T00:00:00Z",
      "approved_at": "2025-07-01T10:30:00Z",
      "created_at": "2025-06-30T15:00:00Z"
    }
  ]
}json

응답 필드 설명

필드 타입 설명
count Integer 총 구독 계약 수
list Array 구독 계약 목록
list[].id String 구독 계약 고유 ID
list[].order_id String 연결된 주문 ID
list[].status Integer 구독 상태 (위 상태 코드 참조)
list[].billing_cycle String 결제 주기 (monthly, yearly 등)
list[].price Integer 회차별 결제 금액
list[].next_billing_at String 다음 결제 예정일
list[].service_start_at String 구독 서비스 시작일

에러 코드

공통 에러

인증·권한 관련 에러는 에러 코드표를 참고해요.

코드 메시지 대처 방법
SUBSCRIPTION_NOT_ACTIVE 구독계약이 활성화되지 않은 상태예요. 관리자에 문의해요. 구독 상태를 확인해요
SUBSCRIPTION_DENIED 구독 계약 정보를 조회할 권한이 없어요. API 인증 권한을 확인해요
ORDER_SUBSCRIPTION_ONLY 구독상품의 경우 다른 일반 상품과 함께 구매할 수 없어요. 구독상품만 별도로 주문해요
ORDER_SUBSCRIPTION_INVALID 구독결제 정보가 올바르지 않아요. 구독 설정을 확인해요