일시정지

v1 API 상세 명세

구독을 일시 중단하여 결제를 멈춥니다.

고객이 일시정지 요청

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

API 엔드포인트

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

요청 파라미터

파라미터 타입 필수 설명
order_subscription_id String 필수 구독 계약 고유 번호
user_id String 선택 로그인한 회원 ID 또는 이 몰의 외부 회원 ID. 보내면 구독 소유자와 대조합니다. Bootpay-User-JWT 헤더로 보내도 됩니다
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.requestIng.pause({
    order_subscription_id: '687a1b2c3d4e5f6789012345',
    paused_at: '2025-08-01T00:00:00Z',
    expected_resume_at: '2025-09-01T00:00:00Z',
    reason: '여행으로 인한 일시정지 요청'
})
console.log(response)javascript

응답

성공 응답

요청이 반영된 구독 계약 상세 전체를 돌려줍니다. 아래는 일부만 정리한 예시입니다.

{
  "order_subscription_id": "687a1b2c3d4e5f6789012345",
  "status": "temporarily_paused",
  "paused_at": "2025-08-01T00:00:00+09:00",
  "pause_expected_resume_at": "2025-09-01T00:00:00+09:00",
  "request_histories": [
    { "request_type": "request_pause", "request_status": "request_approved_auto" }
  ]
}json

응답 필드 설명

필드 타입 설명
order_subscription_id String 구독 계약 고유 ID
status String 구독 상태. 자동 승인이면 temporarily_paused(일시정지), 관리자 승인이 필요하면 승인 전까지 그대로입니다
paused_at String 일시정지 시작일
pause_expected_resume_at String 재개 예정일
request_histories Array 이 구독의 요청 이력. 일시정지 요청은 request_type 이 request_pause (내부값 11). 요청 유형 전체

에러 코드

공통 에러

인증·권한 관련 에러는 에러 코드표를 참고합니다.

코드 메시지 대처 방법
ORDER_SUBSCRIPTION_PAUSE_UNABLE 해당 구독 상품은 일시정지를 지원하지 않는 정책입니다 구독 정책을 확인합니다
SUBSCRIPTION_PAUSE_NOT_ALLOWED 해당 구독 상품은 일시정지 기능을 제공하지 않습니다 구독 설정에서 일시정지를 활성화합니다
SUBSCRIPTION_PAUSE_COUNT_EXCEEDED 일시정지 횟수가 초과됐습니다. 최대 일시정지 횟수를 확인합니다
SUBSCRIPTION_RESUME_REASON_REQUIRED 사유를 입력해야 합니다. reason 을 보냅니다 (코드명과 달리 일시정지 사유 누락입니다)
SUBSCRIPTION_PAUSE_RESUME_DATE_REQUIRED 일시정지 재개 날짜를 입력해야 합니다. expected_resume_at 을 보냅니다
SUBSCRIPTION_PAUSE_DURATION_TOO_LONG 일시정지 기간이 너무 길어 최대 일시정지 기간을 초과했습니다. 템플릿의 최대 일시정지 기간을 확인합니다
SUBSCRIPTION_PAUSE_TOTAL_DAYS_EXCEEDED 총 일시정지 일수가 최대 허용 일수를 초과했습니다. 누적 일시정지 일수를 확인합니다
SUBSCRIPTION_PAUSE_STATUS_INVALID 유효하지 않은 일시정지 상태입니다. 구독 중 상태인지 확인합니다
ORDER_SUBSCRIPTION_PAUSE_REQUEST_DUPLICATE 이미 대기 중인 일시정지 요청이 있습니다. 기존 요청 처리를 기다립니다

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

알려진 문제 — 고객 일시정지에는 subscription.paused 웹훅이 오지 않습니다

지금은 관리자 일시정지만 subscription.paused 웹훅을 보냅니다. 고객 요청으로 멈춘 경우(자동 승인이든, 신청 관리에서 승인한 경우든)는 웹훅이 없으니, 이 API의 응답 status 나 계약 상세의 status 로 일시정지 여부를 확인합니다.

관리자가 일시정지 처리

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

이 API는 관리자(Supervisor) 권한이 필요합니다.

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

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

API 엔드포인트

PUThttps://api.bootapi.com/v1/order_subscriptions/:order_subscription_id/pauseBasic Auth (supervisor 권한 필요)

요청 파라미터

파라미터 타입 필수 설명
order_subscription_id String 필수 구독 계약 ID (URL 파라미터)
paused_at String 필수 정지 시작일 (ISO 8601). 즉시 멈추려면 지금 시각을 넣습니다
expected_resume_at String 필수 예상 재개일 (ISO 8601). 지금부터 1년 이내여야 합니다
reason String 선택 정지 사유

코드 예제

curl -X PUT "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": "결제 수단 문제로 일시정지",
    "paused_at": "2025-07-11T15:00:00+09:00",
    "expected_resume_at": "2025-08-01T00:00:00+09:00"
  }'bash

응답

{
  "order_subscription_id": "687a1b2c3d4e5f6789012345",
  "status": "temporarily_paused",
  "paused_at": "2025-07-11T15:00:00+09:00",
  "pause_expected_resume_at": "2025-08-01T00:00:00+09:00"
}json

응답 필드 설명

파라미터 타입 설명
order_subscription_id String 구독 계약 ID
status String 변경된 상태 (temporarily_paused: 일시정지)
paused_at String 정지 시작 시각
pause_expected_resume_at String 예상 재개 시각

정지 사유는 응답에 담기지 않습니다. 계약 상세의 pause_reason 으로 확인합니다.

에러 코드

공통 에러

인증·권한 관련 에러는 에러 코드표를 참고합니다.

코드 메시지 대처 방법
ORDER_SUBSCRIPTION_NOT_FOUND 구독결제 건을 찾을 수 없습니다. order_subscription_id를 확인합니다
ORDER_SUBSCRIPTION_ALREADY_PAUSE 이미 일시정지가 진행된 구독입니다 구독 상태를 확인합니다
ORDER_SUBSCRIPTION_EXPECTED_RESUME_AT_INVALID 구독 재개 시간이 현재보다 과거이거나 1년 이후는 설정할 수 없습니다. expected_resume_at 을 지금부터 1년 이내로 보냅니다
TIME_INVALID 시간 포맷이 잘못되었습니다. ISO 8601 표준시 포맷으로 보냅니다. paused_at·expected_resume_at 형식을 확인합니다

함께 보기