쇼핑몰 하나에 하나씩 있는 쿠폰 운영 설정입니다(쿠폰 사용 여부, 함께 쓸 수 있는 혜택, 주문당 최대 쿠폰 수, 취소 시 복원 방식 등). 가맹점 서버·운영 도구용 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 문서 최초 작성
