쿠폰 템플릿은 쿠폰의 정의(이름·할인 방식·적용 대상·발급 조건)입니다. 회원이 받는 쿠폰 한 장 한 장은 템플릿에서 발급되며, 발급 시점의 템플릿 값을 복사해 갖습니다. 가맹점 서버·운영 도구용 API 입니다.
- 구매자가 쿠폰을 받는 API 는 쿠폰 (구매자)의
POST /v1/coupon/download입니다. - 쿠폰존은 다운로드 쿠폰을 모아 보여 주는 쇼핑몰 화면입니다. 이 문서의
zoneAPI 로 노출 순서·배지를 관리합니다.
인증 방식
이 문서의 API 는 가맹점 서버 전용이며 쿠폰과 같은 방식으로 인증합니다. secretKey 로 만든 Basic 인증(또는 그 키로 발급한 Bearer 토큰)이 필요하고, 키체인 키면 각 API 의 supervisor scope 를 받아 둬야 합니다.
- clientKey(
Bootpay-Client-Key헤더)만으로는 호출할 수 없습니다(400 TOKEN_AUTHORIZE_TYPE_INVALID). scope 가 없으면401 API_SCOPE_INVALID입니다. - 템플릿 ID 로 찾는 API(상세·수정·삭제·발급)는 인증한 프로젝트의 템플릿만 찾습니다. 다른 쇼핑몰의 템플릿 ID 는 없는 템플릿과 같은
404 COUPON_TEMPLATE_NOT_FOUND입니다. - 회원 JWT 는 쓰지 않습니다. 발급(
issue)의user_id, 쿠폰존 미리보기의as_user_id는 호출자가 아니라 대상 회원입니다 — 해석 규칙은 쿠폰의 대상 회원과 같습니다.
템플릿 객체
값이 없는 필드는 응답에서 빠집니다. 금액 필드는 숫자 문자열입니다.
{
"coupon_template_id": "66e0...",
"project_id": "64a0...",
"seller_id": "64a1...",
"name": "가을 맞이 3,000원 할인",
"code": "FALL3000",
"coupon_type": 1,
"discount_type": 1,
"discount_value": "3000.0",
"min_order_amount": "20000.0",
"target_type": 1,
"target_ids": [],
"issue_method": 2,
"total_quantity": 1000,
"issued_quantity": 120,
"limit_per_user": 1,
"available_from": "2026-09-20T00:00:00+09:00",
"available_until": "2026-10-31T23:59:59+09:00",
"valid_days": 30,
"active": true,
"usable_type": "days",
"zone_visible": true,
"zone_priority": 10,
"zone_tags": ["autumn"],
"zone_badge": "hot",
"subscription_apply_mode": "first_bill_only",
"subscription_apply_count": 1,
"subscription_apply_to_setup_fee": false
}json| 필드 | 타입 | 설명 |
|---|---|---|
| coupon_template_id | string | 템플릿 ID |
| name / code / description | string | 쿠폰명 / 쿠폰 코드(쇼핑몰 안에서 유일) / 설명 |
| coupon_type | integer | 1=주문, 2=상품, 3=배송비, 4=구독 |
| discount_type | integer | 1=정액, 2=정률, 3=무료배송(배송비 쿠폰 전용) |
| discount_value | string | 할인값(정액은 원, 정률은 %) |
| max_discount_amount | string | 정률 할인 상한 |
| min_order_amount | string | 최소 주문 금액 |
| target_type / target_ids | integer / string[] | 적용 대상 1=전체, 2=특정 상품, 3=특정 카테고리 / 대상 ID |
| target_summary | string | 대상 이름 요약(예: "원두 A 외 2개"). 대상이 없으면 빠짐 |
| issue_method | integer | 발급 방식 1=자동, 2=다운로드, 3=수동 |
| total_quantity | integer | 총 발급 수량. 없거나 0 이면 무제한 |
| issued_quantity | integer | 발급된 수량 |
| limit_per_user | integer | 1인당 발급 한도(0 이면 무제한). 사용·만료·복원 대기 쿠폰은 세지 않습니다 |
| available_from / available_until | string | 발급 기간(ISO 8601) |
| valid_days | integer | 받은 날부터 사용 가능한 일수 |
| usable_type | string | 사용 기간 방식 days(받은 날 + valid_days) 또는 absolute(usable_start_at~`usable_end_at`) |
| usable_start_at / usable_end_at | string | 절대 사용 기간 |
| active | boolean | 활성 여부. 비활성이면 발급되지 않습니다 |
| zone_visible / zone_priority / zone_tags / zone_badge | 쿠폰존 노출 여부 / 정렬 우선순위(큰 값 먼저) / 태그 / 배지(hot·new·event) |
|
| subscription_apply_mode / subscription_apply_count / subscription_apply_to_setup_fee | 구독 쿠폰 설정: 적용 회차 방식(first_bill_only·n_bills·all_bills) / 적용 회차 수 / 설치비 포함 여부 |
|
| deleted_at | string | 삭제 표시 시각 |
GET /v1/coupon_templates
쿠폰 템플릿 목록입니다. 최근 생성 순서입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_list - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | coupon_type | integer | 쿠폰 유형 필터 | ||
| query | issue_method | integer | 발급 방식 필터 | ||
| query | keyword | string | 쿠폰명 부분 일치(대소문자 무시) | ||
| query | active_only | string | 값이 있으면 활성 템플릿만. false 를 보내도 활성만 조회되니, 전체를 보려면 보내지 마세요 |
||
| query | page | integer | 1 | 1 이상 | |
| query | limit | integer | 20 | 1 이상. 상한 없음 |
공통 페이지네이션 보정을 하지 않습니다. page·limit 이 0 이하면 오류가 날 수 있습니다.
응답
200 OK
{ "coupon_templates": [ { "coupon_template_id": "66e0...", "name": "가을 맞이 3,000원 할인", "target_summary": null } ], "total_count": 1 }json| 필드 | 타입 | 설명 |
|---|---|---|
| coupon_templates[] | array | 템플릿 객체 |
| total_count | integer | 조건에 맞는 전체 개수 |
오류
인증 방식 절의 오류 외에 도메인 오류는 없습니다. 공통 형식은 오류를 봅니다.
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-04-20
keyword·issue_method필터 추가 - 2026-09-23 문서 최초 작성
POST /v1/coupon_templates
쿠폰 템플릿을 만듭니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_create - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | name | string | O | 쿠폰명 | |
| body | code | string | 쿠폰 코드. 쇼핑몰 안에서 유일해야 합니다(중복이면 서버 오류) | ||
| body | description | string | 설명 | ||
| body | coupon_type | integer | O | 1=주문, 2=상품, 3=배송비, 4=구독 | |
| body | discount_type | integer | O | 1=정액, 2=정률, 3=무료배송 | |
| body | discount_value | number | O | 할인값 | |
| body | max_discount_amount | number | 정률 할인 상한 | ||
| body | min_order_amount | number | 0 | 최소 주문 금액 | |
| body | target_type | integer | 1 | 적용 대상 | |
| body | target_ids | string[] | [] | 대상 상품·카테고리 ID | |
| body | issue_method | integer | 2 | 발급 방식 1=자동, 2=다운로드, 3=수동 | |
| body | total_quantity | integer | 총 발급 수량(없으면 무제한) | ||
| body | limit_per_user | integer | 1 | 1인당 발급 한도 | |
| body | available_from | string | 발급 시작 시각(ISO 8601) | ||
| body | available_until | string | 발급 종료 시각 | ||
| body | valid_days | integer | 받은 날부터 사용 가능한 일수 |
유형·방식 값의 범위는 검사하지 않습니다. 쿠폰존·구독 쿠폰 설정은 만든 뒤 PUT 으로 바꿉니다(zone_* 만 가능).
응답
200 OK — 만든 템플릿 객체.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 500 | SERVER_ERROR |
쿠폰 코드가 이 쇼핑몰에서 중복됨 |
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-09-28 판매자 정보가 채워져 생성이 동작(이전에는 항상
500) - 2026-09-23 문서 최초 작성
GET /v1/coupon_templates/:id
템플릿 하나를 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_read - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 템플릿 ID |
응답
200 OK — 템플릿 객체.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | COUPON_TEMPLATE_NOT_FOUND |
없는 템플릿, 다른 쇼핑몰의 템플릿이거나 ID 형식이 아님 |
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-09-23 문서 최초 작성
PUT /v1/coupon_templates/:id
템플릿을 고칩니다. 보낸 필드만 바뀝니다. PATCH 로 호출해도 같습니다. 이미 발급된 쿠폰에는 반영되지 않습니다(발급 시점 값 유지).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_update - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 템플릿 ID | |
| body | name | string | 쿠폰명 | ||
| body | description | string | 설명 | ||
| body | discount_value | number | 할인값 | ||
| body | max_discount_amount | number | 정률 할인 상한(null 로 해제) |
||
| body | min_order_amount | number | 최소 주문 금액 | ||
| body | target_type | integer | 적용 대상 | ||
| body | target_ids | string[] | 대상 ID | ||
| body | total_quantity | integer | 총 발급 수량(null 이면 무제한) |
||
| body | limit_per_user | integer | 1인당 발급 한도 | ||
| body | available_from / available_until | string | 발급 기간 | ||
| body | valid_days | integer | 사용 가능 일수 | ||
| body | active | boolean | 활성 여부 | ||
| body | zone_visible | boolean | 쿠폰존 노출 여부 | ||
| body | zone_priority | integer | 쿠폰존 정렬 우선순위(큰 값 먼저) | ||
| body | zone_tags | string[] | 쿠폰존 태그 | ||
| body | zone_badge | string | hot·new·event, 빈 값이면 배지 해제 |
code·coupon_type·discount_type·issue_method 는 바꿀 수 없습니다.
응답
200 OK — 고친 뒤의 템플릿 객체.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | COUPON_TEMPLATE_NOT_FOUND |
없는 템플릿이거나 다른 쇼핑몰의 템플릿 |
| 400 | INVALID_PARAMETER |
zone_badge 가 hot·new·event 가 아님 |
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-04-06 쿠폰존 설정(
zone_*) 추가 - 2026-09-23 문서 최초 작성
DELETE /v1/coupon_templates/:id
템플릿을 지웁니다. 이미 발급된 쿠폰은 지워지지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_delete - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 템플릿 ID |
응답
200 OK — 본문은 null 입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | COUPON_TEMPLATE_NOT_FOUND |
없는 템플릿이거나 다른 쇼핑몰의 템플릿 |
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-04-06 삭제 API 추가
- 2026-09-23 문서 최초 작성
POST /v1/coupon_templates/:id/issue
템플릿으로 지정한 회원에게 쿠폰 한 장을 발급합니다(수동 발급).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_issue - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 템플릿 ID | |
| body | user_id | string | O | 받을 대상 회원 — 회원 ID 또는 외부 회원 ID(ex_uid). 별칭 user_ex_uid 등, login_id 도 가능 |
발급 조건은 구매자 다운로드와 같습니다(활성·발급 기간·총 수량·1인당 한도).
응답
200 OK — 발급된 쿠폰. 형식은 쿠폰 GET /v1/coupons 의 coupons[] 항목과 같습니다(회원 정보 user·template_name 포함).
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | COUPON_TEMPLATE_NOT_FOUND |
없는 템플릿이거나 다른 쇼핑몰의 템플릿 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
user_id(또는 별칭·login_id)가 없음 |
| 404 | USER_NOT_FOUND |
이 몰의 회원이 아니거나 탈퇴한 회원(쿠폰은 발급되지 않음) |
| 403 | USER_NOT_MATCH |
user_id 와 login_id 가 서로 다른 회원 |
| 400 | COUPON_ISSUE_LIMIT_EXCEEDED |
비활성·발급 기간 밖·수량 소진·1인당 한도 도달 |
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-09-28 대상 회원을
ex_uid·별칭으로도 지정. 없는·다른 몰 회원은 발급하지 않고404 USER_NOT_FOUND, 누락은400 REQUIRED_PARAMETER_IS_MISSING(이전에는500또는 검증 없이 발급) - 2026-09-23 문서 최초 작성
GET /v1/coupon_templates/zone
쿠폰존 설정용 템플릿 목록입니다. zone_priority 큰 순, 같으면 최근 수정 순입니다. 쿠폰존 노출 여부와 관계없이 모든 템플릿을 대상으로 합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_zone - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | visible | string | true/false — 쿠폰존 노출 여부 필터. 다른 값은 무시 |
||
| query | badge | string | 배지 필터 | ||
| query | page | integer | 1 | 1 미만이면 1 | |
| query | limit | integer | 1 | 1~100. 보내지 않으면 1개만 옵니다. 항상 명시하세요 |
응답
200 OK
{
"items": [ { "coupon_template_id": "66e0...", "name": "가을 맞이 3,000원 할인", "zone_visible": true, "zone_priority": 10 } ],
"pagination": { "page": 1, "limit": 20, "total": 7 }
}json| 필드 | 타입 | 설명 |
|---|---|---|
| items[] | array | 템플릿 객체 |
| pagination | object | 적용한 page·limit 과 전체 개수 total |
오류
인증 방식 절의 오류 외에 도메인 오류는 없습니다.
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-04-06 추가
- 2026-09-23 문서 최초 작성
POST /v1/coupon_templates/zone/reorder
쿠폰존 정렬 우선순위(zone_priority)를 여러 템플릿에 한 번에 설정합니다. 목록에 이 쇼핑몰 템플릿이 아닌 ID 가 하나라도 있으면 아무것도 바꾸지 않고 거절합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_zone_reorder - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | orders | object[] | O | 설정 목록 | |
| body | orders[].id | string | O | 템플릿 ID. 같은 ID 를 두 번 넣지 마세요(거절됩니다) | |
| body | orders[].zone_priority | integer | 0 | 우선순위. 큰 값이 먼저 |
{ "orders": [ { "id": "66e0...", "zone_priority": 20 }, { "id": "66e1...", "zone_priority": 10 } ] }json응답
200 OK
{ "updated_count": 2 }json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | INVALID_PARAMETER |
orders 가 비었거나, id 가 없거나 ID 형식이 아님 |
| 403 | COUPON_TEMPLATE_NOT_FOUND |
이 쇼핑몰에 없는 템플릿이 섞였거나 같은 ID 가 중복됨 |
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-04-06 추가
- 2026-09-23 문서 최초 작성
GET /v1/coupon_templates/zone/preview
쇼핑몰 쿠폰존 화면이 받는 것과 같은 결과를 운영자가 미리 봅니다. as_user_id 를 주면 그 회원이 보는 화면(발급 여부·남은 수량)으로 계산합니다.
활성·다운로드 방식·쿠폰존 노출 템플릿만 대상입니다. 쿠폰 정책에서 쿠폰 사용이 꺼져 있거나, 회원 없이 조회하는데 show_coupon_to_guest 가 false 면 빈 결과입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_zone_preview - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | as_user_id | string | 이 대상 회원 기준으로 계산 — 회원 ID 또는 외부 회원 ID(ex_uid). 이 키 하나만 받습니다(별칭 없음) |
||
| query | type | integer | 쿠폰 유형 필터 | ||
| query | only_expiring_soon | string | true 면 발급 종료가 72시간 안인 것만 |
||
| query | only_available | string | true 면 발급 수량이 남은 것만 |
||
| query | tag | string | 쿠폰존 태그 필터 | ||
| query | sort | string | recommended | recommended(우선순위·마감 임박·할인값)·discount(할인값 큰 순)·expiring(발급 종료 빠른 순)·newest(발급 시작 최근 순) |
|
| query | page | integer | 1 | 1 미만이면 1 | |
| query | limit | integer | 1 | 1~100. 보내지 않으면 1개만 옵니다. 항상 명시하세요 |
응답
200 OK
{
"hero": { "total_count": 5, "downloadable_count": 4, "total_discount_hint": 12000, "unread_count": 2 },
"items": [ { "coupon_template_id": "66e0...", "name": "가을 맞이 3,000원 할인", "already_issued": false, "remaining_for_user": 1 } ],
"total": 5,
"page": 1,
"limit": 10
}json| 필드 | 타입 | 설명 |
|---|---|---|
| hero.total_count | integer | 쿠폰존 노출 템플릿 수(필터 적용 전) |
| hero.downloadable_count | integer | 그중 지금 발급 기간인 수 |
| hero.total_discount_hint | integer | 받을 수 있는 정액 쿠폰 할인값 합(정률 제외) |
| hero.unread_count | integer | as_user_id 회원이 아직 받지 않은 수. 회원 없으면 0 |
| items[] | array | 쿠폰 항목. 형식은 쿠폰 GET /v1/coupons/downloadable_for_product 의 coupons[] 와 같습니다 |
| total | integer | 필터에 맞는 전체 개수 |
| page / limit | integer | 적용한 값 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_NOT_FOUND |
as_user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원(형식 오류 포함) |
변경 이력
- 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 템플릿을 인증한 프로젝트 범위에서만 찾도록 변경
- 2026-09-28
as_user_id를ex_uid로도 지정. 없는 회원은 비회원 관점으로 넘어가지 않고404 USER_NOT_FOUND, 형식 오류도400대신404 - 2026-04-07 쿠폰존을 페이지 단위 목록으로 변경
- 2026-09-23 문서 최초 작성
