계약 내용 변경

바뀐 값만 보내면 나머지는 유지돼요. price 를 바꾸면 예정 회차 청구액까지 다시 계산돼요.

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

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

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.update(
    '687a1b2c3d4e5f6789012345',
    quantity=2,
    total_subscription_duration=12,
    price=45000
)
print(response)python

use Bootpay\ServerPhp\BootpayCommerceApi;

$commerce = new BootpayCommerceApi("your-commerce-client-key", "your-commerce-secret-key");
$response = $commerce->orderSubscription->update('687a1b2c3d4e5f6789012345', [
    'quantity' => 2,
    'total_subscription_duration' => 12,
    'price' => 45000
]);
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.OrderSubscriptionUpdateParams;

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

OrderSubscriptionUpdateParams params = new OrderSubscriptionUpdateParams();
params.orderSubscriptionId = "687a1b2c3d4e5f6789012345";
params.quantity = 2.0;
params.totalSubscriptionDuration = 12.0;
params.price = 45000.0;

BootpayStoreResponse response = commerce.orderSubscription.update(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_subscription_update(
  order_subscription_id: '687a1b2c3d4e5f6789012345',
  quantity: 2,
  total_subscription_duration: 12,
  price: 45000
)
puts responseruby

commerce := bootpay.NewCommerceApi("your-commerce-client-key", "your-commerce-secret-key")
response, err := commerce.OrderSubscription.Update("687a1b2c3d4e5f6789012345", bootpay.OrderSubscriptionUpdateParams{
    Quantity:                  2,
    TotalSubscriptionDuration: 12,
    Price:                     45000,
})
fmt.Println(response)go

using Bootpay.Commerce;

var commerce = new BootpayCommerceApi("your-commerce-client-key", "your-commerce-secret-key");
var response = await commerce.OrderSubscription.Update("687a1b2c3d4e5f6789012345", new {
    quantity = 2,
    total_subscription_duration = 12,
    price = 45000
});
Console.WriteLine(response);csharp

응답

성공 응답

변경이 반영된 구독 계약 상세 전체를 돌려줘요. 아래는 일부만 추린 예시예요.

{
  "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`	기본 결제 금액이 음수가 돼요.	회차 조정 금액을 함께 확인해요

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

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