진행 중인 구독 계약에 쿠폰을 붙이거나 떼요. 회차 금액이 얼마가 되는지 먼저 계산해 볼 수도 있어요.
회차 할인·추가금이 금액을 직접 적어 넣는 방식이라면, 쿠폰은 발급된 쿠폰을 계약에 연결하는 방식이에요. 연결 하나를 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_SUBSCRIPTION_NOT_FOUND |
구독 계약을 찾을 수 없어요 | order_subscription_id 를 확인해요 |
COUPON_NOT_FOUND |
쿠폰을 찾을 수 없어요 | coupon_id 를 확인해요 |
COUPON_ALREADY_USED |
이미 사용된 쿠폰이에요 | 사용 가능한 쿠폰인지 확인해요 |
COUPON_EXPIRED |
만료된 쿠폰이에요 | 유효기간을 확인해요 |
COUPON_TYPE_NOT_APPLICABLE_TO_SUBSCRIPTION |
구독에 적용할 수 없는 쿠폰 유형이에요 | 구독 금액·배송비 쿠폰인지 확인해요 |
COUPON_NOT_APPLICABLE_FOR_USAGE_BASED_SUBSCRIPTION |
종량제 구독에는 쿠폰을 적용할 수 없어요 | 종량제 계약에는 붙이지 않아요 |
COUPON_SHIPPING_NOT_APPLICABLE_FOR_RECURRING_DELIVERY |
정기배송 구독에는 배송비 쿠폰을 적용할 수 없어요 | 상품 금액 쿠폰을 써요 |
SUBSCRIPTION_COUPON_BINDING_NOT_FOUND |
적용된 쿠폰 연결이 없어요 | 이미 해제됐는지 목록으로 확인해요 |
함께 보기
- 회차 할인·추가금 등록 — 쿠폰 대신 금액을 직접 조정해요
- 회차 청구 내역 — 쿠폰이 반영된 회차 금액을 확인해요