계약 조회

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

API 엔드포인트

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

요청 파라미터

파라미터	타입	필수	설명
`order_number`	String	선택	주문번호로 필터 (주문 ID가 아니에요)
`user_id`	String	선택	고객 ID 또는 이 몰의 외부 회원 ID로 필터. 이 몰에 없거나 탈퇴한 회원이면 `404 USER_NOT_FOUND`가 와요
`user_group_id`	String	선택	고객 그룹 ID로 필터
`status`	String	선택	구독 상태 필터 — 아래 표 참고
`request_type`	Integer \| String	선택	현재 이 값을 보내면 서버 오류(500)가 나요. 요청 유형별 조회는 신청 목록을 사용해요
`keyword`	String	선택	검색 키워드
`search_date_from`	String	선택	검색 시작일 (계약 생성일 기준) · 별칭 `s_at`. 비우면 오늘 00:00
`search_date_to`	String	선택	검색 종료일 (계약 생성일 기준) · 별칭 `e_at`. 비우면 오늘 23:59
`page`	Integer	선택	페이지 번호 (기본: 1)
`limit`	Integer	선택	페이지당 데이터 수 (기본: 20, 최대 100)

구독 상태 코드 (`status`)

키	값	설명
`contract_requested_completed`	`0`	구독 신청 완료, 승인 대기
`subscribing`	`1`	구독 중 (정상 결제 진행)
`auto_terminated`	`15`	자동 해지 (기간 만료 등)
`manual_terminated`	`20`	직접 해지 (사용자 요청)
`mid_term_transfer_approved`	`25`	중도 인수 승인
`mid_term_transfer_requested`	`26`	중도 인수 요청
`free_trial`	`-1`	무료 체험
`temporarily_paused`	`-2`	일시정지
`paused_due_to_issue`	`-3`	이슈로 인한 일시정지
`first_payment_error`	`-10`	첫 결제 오류
`admin_terminated`	`-11`	관리자 해지
`rejected`	`-12`	구독 거절

코드 예제

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: 'subscribing'
})
console.log(response)javascript

from bootpay_backend import BootpayCommerce

commerce = BootpayCommerce(
    client_key='your-commerce-client-key',
    secret_key='your-commerce-secret-key',
    mode='production'
)

response = commerce.order_subscription.list(page=1, limit=20, status='subscribing')
print(response)python

use Bootpay\ServerPhp\BootpayCommerceApi;

$commerce = new BootpayCommerceApi("your-commerce-client-key", "your-commerce-secret-key");
$response = $commerce->orderSubscription->list([
    'page' => 1,
    'limit' => 20,
    'status' => 'subscribing'
]);
print_r($response);php

import kr.co.bootpay.store.BootpayStore;
import kr.co.bootpay.store.model.request.TokenPayload;
import kr.co.bootpay.store.model.response.BootpayStoreResponse;
import kr.co.bootpay.store.model.request.orderSubscription.OrderSubscriptionListParams;

TokenPayload tp = new TokenPayload("your-commerce-client-key", "your-commerce-secret-key");
BootpayStore commerce = new BootpayStore(tp).withToken();

OrderSubscriptionListParams params = new OrderSubscriptionListParams();
params.page = 1;
params.limit = 20;
params.status = "subscribing";

BootpayStoreResponse response = commerce.orderSubscription.list(params);
System.out.println(response);java

require 'bootpay'

commerce = BootpayStore::RestClient.new(client_key: 'your-commerce-client-key', secret_key: 'your-commerce-secret-key')
response = commerce.order_subscriptions(
  page: 1,
  limit: 20,
  status: 'subscribing'
)
puts responseruby

commerce := bootpay.NewCommerceApi("your-commerce-client-key", "your-commerce-secret-key")
response, err := commerce.OrderSubscription.List(bootpay.OrderSubscriptionListParams{
    Page:   1,
    Limit:  20,
    Status: "subscribing",
})
fmt.Println(response)go

using Bootpay.Commerce;

var commerce = new BootpayCommerceApi("your-commerce-client-key", "your-commerce-secret-key");
var response = await commerce.OrderSubscription.List(new {
    page = 1,
    limit = 20,
    status = "subscribing"
});
Console.WriteLine(response);csharp

응답

성공 응답

{
  "count": 3,
  "list": [
    {
      "order_subscription_id": "687a1b2c3d4e5f6789012345",
      "order_number": "68707c59b0eacea5cd974efd",
      "user_id": "67e4b4425ec892162491d0ec",
      "status": "subscribing",
      "approval_status": "approval_approved_auto",
      "subscription_payment_cycle_type": "1month",
      "price": 29900,
      "payment_next_at": "2025-08-01T00:00:00+09:00",
      "service_start_at": "2025-07-01T00:00:00+09:00",
      "created_at": "2025-06-30T15:00:00+09:00"
    }
  ]
}json

응답 필드 설명

필드	타입	설명
`count`	Integer	총 구독 계약 수
`list`	Array	구독 계약 목록
└─ `order_subscription_id`	String	구독 계약 고유 ID
└─ `order_number`	String	연결된 주문번호
└─ `status`	String	구독 상태 — 아래 표 참고
└─ `approval_status`	String	승인 상태
└─ `subscription_payment_cycle_type`	String	결제 주기 (`1month`, `1year` 등)
└─ `price`	Integer	회차별 결제 금액
└─ `payment_next_at`	String	다음 결제 예정일
└─ `service_start_at`	String	구독 서비스 시작일

목록 외에 상태별 집계(sum_*)와 요청 유형별 집계(ing_*)가 최상위에 함께 와요.

에러 코드

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

코드	메시지	대처 방법
`INVALID_PARAMETER`	`status` 값을 해석할 수 없어요.	숫자 또는 상태 키(`subscribing` 등)로 보내요
`USER_NOT_FOUND`	`user_id`가 이 몰의 회원이 아니거나 탈퇴했어요.	해당 몰에 속한 유효한 회원 ID를 확인해요