구독

일시정지

구독을 잠시 세워 다음 청구와 서비스 제공 시점을 조정해요.

구독을 일시 중단하여 결제를 멈춰요.

고객이 일시정지 요청

고객이 직접 구독 일시정지를 요청해요. 구독 설정에 따라 관리자 승인이 필요할 수 있어요.

API 엔드포인트

POSThttps://api.bootapi.com/v1/order_subscriptions/requests/ing/pauseBasic Auth

요청 파라미터

파라미터 타입 필수 설명
order_subscription_id String 필수 구독 계약 고유 번호
paused_at String 선택 일시정지 시작일 (ISO 8601)
expected_resume_at String 선택 재개 예정일 (ISO 8601)
reason String 선택 일시정지 요청 사유

코드 예제

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.requestPause({
    order_subscription_id: '687a1b2c3d4e5f6789012345',
    paused_at: '2025-08-01T00:00:00Z',
    expected_resume_at: '2025-09-01T00:00:00Z',
    reason: '여행으로 인한 일시정지 요청'
})
console.log(response)javascript

응답

성공 응답

{
  "id": "687a1b2c3d4e5f6789012345",
  "status": 2,
  "request_type": 1,
  "paused_at": "2025-08-01T00:00:00Z",
  "expected_resume_at": "2025-09-01T00:00:00Z"
}json

응답 필드 설명

필드 타입 설명
id String 구독 계약 고유 ID
status Integer 변경된 구독 상태 (2: 일시정지)
request_type Integer 요청 타입 (1: 일시정지)
paused_at String 일시정지 시작일
expected_resume_at String 재개 예정일

에러 코드

공통 에러

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

코드 메시지 대처 방법
ORDER_SUBSCRIPTION_PAUSE_UNABLE 해당 구독 상품은 일시정지를 지원하지 않는 정책이에요 구독 정책을 확인해요
SUBSCRIPTION_PAUSE_NOT_ALLOWED 해당 구독 상품은 일시정지 기능을 제공하지 않아요 구독 설정에서 일시정지를 활성화해요
SUBSCRIPTION_PAUSE_COUNT_EXCEEDED 일시정지 횟수가 초과됐어요. 최대 일시정지 횟수를 확인해요
SUBSCRIPTION_PAUSE_DURATION_TOO_SHORT 일시정지 기간이 너무 짧아요. 최소 일시정지 기간을 확인해요

일시정지는 구독 상태가 구독 중(1)​​일 때만 요청 가능해요. 구독 설정에서 use_pause가 활성화되어 있어야 해요.

관리자가 일시정지 처리

관리자가 직접 구독 계약을 일시정지해요. 고객 요청 없이 관리자가 즉시 정지할 수 있어요.

이 API는 관리자(Supervisor) 권한이 필요해요.

고객 요청 vs 관리자 직접 정지

구분 고객 요청 관리자 직접 정지
API 고객 일시정지 요청 이 API
승인 과정 관리자 승인 필요 (설정에 따라) 즉시 정지
재개 예정일 고객이 설정 관리자가 설정

API 엔드포인트

POSThttps://api.bootapi.com/v1/order_subscriptions/:order_subscription_id/pauseBasic Auth

요청 파라미터

파라미터 타입 필수 설명
order_subscription_id String 필수 구독 계약 ID (URL 파라미터)
paused_at String 선택 정지 시작일 (ISO 8601, 미입력 시 즉시)
expected_resume_at String 선택 예상 재개일 (ISO 8601)
reason String 선택 정지 사유

코드 예제

curl -X POST "https://api.bootapi.com/v1/order_subscriptions/{order_subscription_id}/pause" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "결제 수단 문제로 일시정지",
    "expected_resume_at": "2025-08-01T00:00:00Z"
  }'bash

응답

{
  "id": "sub_abc123",
  "status": 2,
  "paused_at": "2025-07-11T15:00:00Z",
  "expected_resume_at": "2025-08-01T00:00:00Z",
  "reason": "결제 수단 문제로 일시정지"
}json

응답 필드 설명

파라미터 타입 설명
id String 구독 계약 ID
status Integer 변경된 상태 (2: 일시정지)
paused_at String 정지 시작 시각
expected_resume_at String 예상 재개 시각
reason String 정지 사유

에러 코드

공통 에러

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

코드 메시지 대처 방법
ORDER_SUBSCRIPTION_NOT_FOUND 구독결제 건을 찾을 수 없어요. order_subscription_id를 확인해요
ORDER_SUBSCRIPTION_PAUSE_APPROVE_ERROR 일시정지 승인을 할 수 없는 상태예요. 요청 상태를 확인해요
ORDER_SUBSCRIPTION_PAUSE_REJECT_ERROR 일시정지 거부를 할 수 없는 상태예요. 요청 상태를 확인해요
ORDER_SUBSCRIPTION_PAUSE_REASON_BLANK 일시정지 거절 사유가 비어 있어요. reason 파라미터를 입력해요