활성 구독 계약의 내용을 변경합니다. 상품 구성, 수량, 회차 수, 결제 금액, 수령인 정보, 서비스 기간 등을 수정할 수 있습니다. 바뀐 값만 보내면 나머지는 그대로 유지됩니다.
API 엔드포인트
금액을 바꾸는 두 가지 방법
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)javascriptfrom 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)pythonuse 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);phpimport 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);javarequire '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 responserubycommerce := 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)gousing 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_ |
구독결제 정보가 올바르지 않습니다. | 구독 계약 ID와 프로젝트를 확인합니다 |
PRODUCT_ |
상품 수량 개수가 잘못되었습니다. | quantity 를 1 이상으로 보냅니다 |
ORDER_ |
구독 서비스 기간이 유효하지 않습니다. | service_start_at·service_end_at 을 확인합니다 |
ORDER_ |
잘못된 계약기간입니다. | 시작일이 종료일보다 앞서게 보냅니다 |
ORDER_ |
유효하지 않은 가격입니다. | price를 0보다 큰 값으로 보냅니다 |
SUBSCRIPTION_ |
기본 결제 금액이 음수가 됩니다. | 회차 조정 금액을 함께 확인합니다 |
price가 적용되는 범위
바뀐 기준금액은 결제예정 회차에 즉시 다시 계산돼 반영되고, 그 이후 회차도 이 금액으로 만들어집니다. 이미 결제가 끝난 회차는 그대로입니다. 관리자 화면에서 금액을 바꿀 때와 같은 동작입니다.
최종 청구액은 기준금액 + 배송비 + 회차 조정이므로 회차 조정이 걸려 있으면 그만큼 더해지거나 빠집니다. 어떤 회차에서든 최종 금액이 음수가 되면 변경이 거절됩니다.


