계약 내용 변경

v1 API 상세 명세

활성 구독 계약의 내용을 변경합니다. 상품 구성, 수량, 회차 수, 결제 금액​, 수령인 정보, 서비스 기간 등을 수정할 수 있습니다. 바뀐 값만 보내면 나머지는 그대로 유지됩니다.

API 엔드포인트

PUThttps://api.bootapi.com/v1/order_subscriptions/:idBasic Auth (supervisor)
금액을 바꾸는 두 가지 방법

price는 회차마다 청구되는 기준금액입니다. 계약 자체의 금액이 바뀌므로 이미 잡혀 있는 결제예정 회차의 청구액까지 즉시 다시 계산되고 이후 회차도 이 금액으로 만들어집니다.

일부 회차만 가감할 때는 회차 금액 조정의 조정 항목을 사용합니다. 기준금액은 그대로 두고 한 회차·회차 범위·특정 회차부터 끝까지 중 하나를 골라 가감합니다.

요청 파라미터

파라미터 타입 필수 설명
id String 필수 구독 계약 ID (URL 경로)
product_id String 선택 변경할 상품 ID
product_option_id String 선택 변경할 상품 옵션 ID
order_name String 선택 주문명
price Integer 선택 회차별 결제 금액(기준금액). 0보다 커야 합니다. 결제예정 회차부터 반영됩니다
quantity Integer 선택 수량
total_subscription_duration Integer 선택 총 구독 회차 수
address_id String 선택 배송지 ID
username String 선택 수령인 이름
phone String 선택 수령인 연락처
email String 선택 수령인 이메일
use_free_trial Boolean 선택 무료 체험 사용 여부
free_trial_day Integer 선택 무료 체험 일수
service_start_at String 선택 서비스 시작일
service_end_at String 선택 서비스 종료일
memo 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.update('687a1b2c3d4e5f6789012345', {
    quantity: 2,
    total_subscription_duration: 12,
    price: 45000
})
console.log(response)javascript

응답

성공 응답

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

{
  "order_subscription_id": "687a1b2c3d4e5f6789012345",
  "status": "subscribing",
  "price": 45000,
  "quantity": 2,
  "total_subscription_duration": 12
}json
상태·유형 값은 문자열입니다

응답의 status 같은 코드값은 정수가 아니라 문자열(enum)로 내려옵니다. 전체 목록은 커머스 Enum에서 확인합니다.

구독 상태 (status)

내용 변경은 상태를 바꾸지 않습니다. 구독 중이면 응답도 subscribing 그대로입니다. 전체 값은 구독 상태에 있습니다.

키 값 설명
subscribing 1 구독 중 (정상 결제 진행)

에러 코드

공통 에러

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

코드 메시지 대처 방법
ORDER_SUBSCRIPTION_INVALID 구독결제 정보가 올바르지 않습니다. 구독 계약 ID와 프로젝트를 확인합니다
PRODUCT_QTY_INVALID 상품 수량 개수가 잘못되었습니다. quantity 를 1 이상으로 보냅니다
ORDER_SUBSCRIPTION_SERVICE_DATE_INVALID 구독 서비스 기간이 유효하지 않습니다. service_start_at·service_end_at 을 확인합니다
ORDER_SUBSCRIPTION_SERVICE_DATE_WRONG 잘못된 계약기간입니다. 시작일이 종료일보다 앞서게 보냅니다
ORDER_SUBSCRIPTION_PRICE_INVALID 유효하지 않은 가격입니다. price를 0보다 큰 값으로 보냅니다
SUBSCRIPTION_ADJUSTMENT_NEGATIVE_PRICE 기본 결제 금액이 음수가 됩니다. 회차 조정 금액을 함께 확인합니다
price가 적용되는 범위

바뀐 기준금액은 결제예정 회차에 즉시 다시 계산돼 반영되고, 그 이후 회차도 이 금액으로 만들어집니다. 이미 결제가 끝난 회차는 그대로입니다. 관리자 화면에서 금액을 바꿀 때와 같은 동작입니다.

최종 청구액은 기준금액 + 배송비 + 회차 조정이므로 회차 조정이 걸려 있으면 그만큼 더해지거나 빠집니다. 어떤 회차에서든 최종 금액이 음수가 되면 변경이 거절됩니다.

함께 보기