진행 중인 구독 계약에 쿠폰을 적용·해제하고, 적용 후 회차 금액을 미리 계산합니다.
쿠폰은 발급된 쿠폰을 계약에 연결합니다. 금액을 직접 지정하는 방식은 회차 할인·추가금입니다. 연결 하나를 binding 이라고 부릅니다.
모든 쿠폰 API는 Basic 인증을 사용합니다. Bootpay-User-JWT 헤더 또는 user_id(본문·쿼리)를 선택해서 보내면 그 회원의 구독인지 확인합니다. 둘 다 없으면 가맹점 대리 호출로 처리합니다. 다른 회원의 구독이면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰이면 404 COUPON_NOT_FOUND가 옵니다.
/coupons 를 사용합니다. 단수형 /coupon 은 Phase 1 하위호환으로 남아 있지만 새로 붙이는 코드에는 쓰지 않습니다.
적용된 쿠폰 목록
{ "ok": true, "items": [] }jsonitems 에는 활성 상태(active)인 연결만 담깁니다. 해제된 연결은 나오지 않습니다.
쿠폰 적용
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
coupon_id |
String | 필수 | 적용할 쿠폰 ID |
구독 금액 쿠폰(coupon)과 배송비 쿠폰(shipping_coupon)은 각각 한 장만 적용됩니다. 같은 타입을 또 붙이려면 먼저 해제합니다. 조정 타입 값은 구독 금액 조정 타입을 참고합니다.
적용되면 subscription_coupon.applied 웹훅이 나갑니다.
적용 미리보기
실제로 붙이지 않고 적용했을 때의 회차 금액만 계산해 줍니다.
검증에 실패해도 HTTP 200에 ok: false와 숫자 error_code가 올 수 있습니다. 적용 가능 여부는 ok로 확인합니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
coupon_id |
String | 필수 | 계산해 볼 쿠폰 ID |
exclude_applied |
Boolean | 선택 | true 면 이미 적용된 쿠폰을 뺀 상태로 다시 계산합니다 |
지금 붙은 쿠폰을 빼고 새 쿠폰으로 바꿨을 때의 금액을 계산합니다. 생략하면 기존 쿠폰 위에 더한 결과가 나옵니다.
쿠폰 해제
https://api.bootapi.com/v1/order_subscriptions/:order_subscription_id/coupons/:binding_idBasic Auth| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
:binding_id (경로) |
String | 필수 | 해제할 연결 ID. 목록의 연결 ID 를 넣습니다 |
복수형 경로는 :binding_id 가 경로에 꼭 있어야 합니다. ID 없이 부르면 활성 연결 중 첫 번째를 해제하는 동작은 하위호환용 단수형 DELETE /v1/order_subscriptions/:order_subscription_id/coupon 에만 남아 있고, 이때는 서버가 무엇을 해제할지 고릅니다. 쿠폰이 둘 이상 붙어 있을 수 있는 계약은 목록에서 ID 를 먼저 확인합니다.
해제되면 subscription_coupon.removed 웹훅이 나갑니다.
계약이 해지·종료되면 붙어 있던 쿠폰 연결도 닫히고 subscription_coupon.expired 웹훅이 나갑니다. 쿠폰 잔여를 관리하면 이 이벤트도 함께 받습니다.
에러 코드
인증·권한 관련 에러는 커머스 API 인증 에러를 참고합니다.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
ORDER_ |
구독결제 건을 찾을 수 없습니다. | order_subscription_id 를 확인합니다 |
COUPON_ |
쿠폰을 찾을 수 없습니다 | coupon_id 를 확인합니다 |
COUPON_ |
이미 사용된 쿠폰입니다 | 사용 가능한 쿠폰인지 확인합니다 |
COUPON_ |
만료된 쿠폰입니다 | 유효기간을 확인합니다 |
COUPON_ |
구독에 적용할 수 없는 쿠폰 유형입니다 | 구독 금액·배송비 쿠폰인지 확인합니다 |
COUPON_ |
종량제 구독에는 쿠폰을 적용할 수 없습니다 | 종량제 계약에는 붙이지 않습니다 |
COUPON_ |
정기배송 구독에는 배송비 쿠폰을 적용할 수 없습니다 | 상품 금액 쿠폰을 씁니다 |
SUBSCRIPTION_ |
구독 쿠폰 바인딩을 찾을 수 없습니다. | 이미 해제됐는지 목록으로 확인합니다 |



