쿠폰 정책

쇼핑몰 하나에 하나씩 있는 쿠폰 운영 설정입니다(쿠폰 사용 여부, 함께 쓸 수 있는 혜택, 주문당 최대 쿠폰 수, 취소 시 복원 방식 등). 가맹점 서버·운영 도구용 API 입니다. 정책이 아직 없으면 조회·수정 시 기본값으로 만듭니다(처음 만들 때 use_coupon 은 false).

이 정책은 다른 쿠폰 API 에 영향을 줍니다. 예를 들어 use_coupon 이 false 면 쿠폰의 적용 미리보기가 COUPON_NOT_AVAILABLE 로 거절되고 쿠폰존이 비어 보이며, show_coupon_to_guest 가 false 면 비회원에게 받을 수 있는 쿠폰 목록이 비어 보입니다.

인증 방식

가맹점 서버 전용​​이며 쿠폰과 같습니다. secretKey 로 만든 Basic 인증(또는 그 키로 발급한 Bearer 토큰)이 필요하고, 키체인 키면 supervisor scope 를 받아 둬야 합니다. clientKey(Bootpay-Client-Key 헤더)만으로는 호출할 수 없습니다(400 TOKEN_AUTHORIZE_TYPE_INVALID).

정책은 인증한 프로젝트의 것만 읽고 씁니다. 몰 단위 설정이라 회원과 무관​​합니다 — 회원 JWT·user_id 는 필요 없고, 보내도 결과가 바뀌지 않습니다.

현재 동작 주의​: PUT 은 변경 감사 기록 단계에서 서버 오류가 나 현재 500 SERVER_ERROR 로 끝납니다. GET 은 정상 동작합니다.

정책 객체

{
  "coupon_policy_id": "66d0...",
  "project_id": "64a0...",
  "seller_id": "64a1...",
  "use_coupon": true,
  "coupon_issue_scope_type": 1,
  "allow_coupon_with_point": true,
  "allow_coupon_with_member_discount": true,
  "allow_product_coupon_with_order_coupon": true,
  "maximum_coupon_apply_count": 1,
  "coupon_restore_policy": 1,
  "coupon_expire_notice_days": 3,
  "show_coupon_to_guest": true,
  "show_issued_coupon": true,
  "coupon_sort_type": 1,
  "use_additional_coupon": false,
  "disabled_system_keys": []
}json
필드 타입 기본값 설명
coupon_policy_id string 정책 ID
use_coupon boolean false 쿠폰 기능 사용
coupon_issue_scope_type integer 1 쿠폰 발급 범위 1=전체(회원·비회원), 2=가입 회원만
allow_coupon_with_point boolean true 쿠폰과 적립금 함께 사용
allow_coupon_with_member_discount boolean true 쿠폰과 회원 할인 함께 사용
allow_product_coupon_with_order_coupon boolean true 상품 쿠폰과 주문 쿠폰 함께 사용
maximum_coupon_apply_count integer 1 주문당 최대 쿠폰 수
coupon_restore_policy integer 1 주문 취소 시 쿠폰 1=즉시 복원, 2=수동 복원(상담 처리), 3=복원 안 함
coupon_expire_notice_days integer 3 만료 며칠 전에 알릴지
show_coupon_to_guest boolean true 비회원(방문자)에게 받을 수 있는 쿠폰 노출
show_issued_coupon boolean true 발급 쿠폰 목록 표시
coupon_sort_type integer 1 쿠폰 정렬 1=할인 금액순, 2=만료일순, 3=생성일순
use_additional_coupon boolean false 추가 쿠폰 사용
additional_coupon_template_id string 추가 쿠폰으로 쓸 템플릿 ID. 없으면 응답에서 빠짐
disabled_system_keys string[] [] 비활성화된 시스템 항목(조회 전용)

GET /v1/coupon_policies

쿠폰 정책을 조회합니다. 없으면 기본값으로 만들어 돌려줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:coupon_policy_detail
  • 회원 JWT(Bootpay-User-JWT)·user_id: 필요 없음(보내도 무시)

요청

파라미터 없음.

응답

200 OK — 정책 객체.

오류

인증 오류 외에 도메인 오류는 없습니다. 인증 오류는 쿠폰을 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경 — 판매자 정보가 채워져 조회가 동작(이전에는 항상 500)
  • 2026-09-23 문서 최초 작성

PUT /v1/coupon_policies

쿠폰 정책을 고칩니다. 보낸 필드만 바뀝니다. PATCH 로 호출해도 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:coupon_policy_update
  • 회원 JWT(Bootpay-User-JWT)·user_id: 필요 없음(보내도 무시)

요청

위치 이름 타입 필수 기본값 설명
body use_coupon boolean 쿠폰 기능 사용
body coupon_issue_scope_type integer 1 또는 2
body allow_coupon_with_point boolean
body allow_coupon_with_member_discount boolean
body allow_product_coupon_with_order_coupon boolean
body maximum_coupon_apply_count integer 주문당 최대 쿠폰 수
body coupon_restore_policy integer 1~3
body coupon_expire_notice_days integer
body show_coupon_to_guest boolean
body show_issued_coupon boolean
body coupon_sort_type integer 1~3
body use_additional_coupon boolean
body additional_coupon_template_id string 추가 쿠폰 템플릿 ID(이 쇼핑몰 템플릿만). 빈 값을 보내면 무시되어 기존 값을 지울 수 없습니다

각 필드의 뜻은 정책 객체를 봅니다. 값의 범위는 검사하지 않으니 표의 값만 보내세요. additional_coupon_template_id 는 이 쇼핑몰의 템플릿이어야 합니다.

응답

200 OK — 고친 뒤의 정책 객체.

오류

HTTP error_code 언제
404 COUPON_TEMPLATE_NOT_FOUND additional_coupon_template_id 가 없는 템플릿·다른 쇼핑몰 템플릿이거나 ID 형식이 아님
500 SERVER_ERROR 현재 항상(위 주의 참고)

인증 오류는 쿠폰을 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 다른 쇼핑몰 템플릿을 additional_coupon_template_id 로 지정하면 404
  • 2026-09-23 문서 최초 작성

함께 보기