구독 쿠폰

v1 API 상세 명세

진행 중인 구독 계약에 쿠폰을 적용·해제하고, 적용 후 회차 금액을 미리 계산합니다.

쿠폰은 발급된 쿠폰을 계약에 연결​​합니다. 금액을 직접 지정하는 방식은 회차 할인·추가금입니다. 연결 하나를 binding 이라고 부릅니다.

모든 쿠폰 API는 Basic 인증을 사용합니다. Bootpay-User-JWT 헤더 또는 user_id(본문·쿼리)를 선택해서 보내면 그 회원의 구독인지 확인합니다. 둘 다 없으면 가맹점 대리 호출로 처리합니다. 다른 회원의 구독이면 403 SUBSCRIPTION_DENIED, 다른 회원에게 발급된 쿠폰이면 404 COUPON_NOT_FOUND가 옵니다.

경로가 복수형입니다

/coupons 를 사용합니다. 단수형 /coupon 은 Phase 1 하위호환으로 남아 있지만 새로 붙이는 코드에는 쓰지 않습니다.

적용된 쿠폰 목록

GEThttps://api.bootapi.com/v1/order_subscriptions/:order_subscription_id/couponsBasic Auth
{ "ok": true, "items": [] }json

items 에는 활성 상태(active)인 연결만 담깁니다. 해제된 연결은 나오지 않습니다.

쿠폰 적용

POSThttps://api.bootapi.com/v1/order_subscriptions/:order_subscription_id/couponsBasic Auth
파라미터 타입 필수 설명
coupon_id String 필수 적용할 쿠폰 ID
타입별로 하나만 붙습니다

구독 금액 쿠폰(coupon)과 배송비 쿠폰(shipping_coupon)은 각각 한 장만 적용됩니다. 같은 타입을 또 붙이려면 먼저 해제합니다. 조정 타입 값은 구독 금액 조정 타입을 참고합니다.

적용되면 subscription_coupon.applied 웹훅이 나갑니다.

적용 미리보기

POSThttps://api.bootapi.com/v1/order_subscriptions/:order_subscription_id/coupons/previewBasic Auth

실제로 붙이지 않고 적용했을 때의 회차 금액​​만 계산해 줍니다.

검증에 실패해도 HTTP 200에 ok: false와 숫자 error_code가 올 수 있습니다. 적용 가능 여부는 ok로 확인합니다.

파라미터 타입 필수 설명
coupon_id String 필수 계산해 볼 쿠폰 ID
exclude_applied Boolean 선택 true 면 이미 적용된 쿠폰을 뺀 상태로 다시 계산합니다
`exclude_applied`

지금 붙은 쿠폰을 빼고 새 쿠폰으로 바꿨을 때의 금액을 계산합니다. 생략하면 기존 쿠폰 위에 더한 결과가 나옵니다.

쿠폰 해제

DELETEhttps://api.bootapi.com/v1/order_subscriptions/:order_subscription_id/coupons/:binding_idBasic Auth
파라미터 타입 필수 설명
:binding_id (경로) String 필수 해제할 연결 ID. 목록의 연결 ID 를 넣습니다
연결 ID 없이 해제하는 건 옛 경로에서만 됩니다

복수형 경로는 :binding_id 가 경로에 꼭 있어야 합니다. ID 없이 부르면 활성 연결 중 첫 번째를 해제하는 동작은 하위호환용 단수형 DELETE /v1/order_subscriptions/:order_subscription_id/coupon 에만 남아 있고, 이때는 서버가 무엇을 해제할지 고릅니다. 쿠폰이 둘 이상 붙어 있을 수 있는 계약은 목록에서 ID 를 먼저 확인합니다.

해제되면 subscription_coupon.removed 웹훅이 나갑니다.

구독이 끝나면 `expired` 가 옵니다

계약이 해지·종료되면 붙어 있던 쿠폰 연결도 닫히고 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 구독 쿠폰 바인딩을 찾을 수 없습니다. 이미 해제됐는지 목록으로 확인합니다

함께 보기