쿠폰 템플릿

쿠폰 템플릿은 쿠폰의 정의​(이름·할인 방식·적용 대상·발급 조건)입니다. 회원이 받는 쿠폰 한 장 한 장은 템플릿에서 발급되며, 발급 시점의 템플릿 값을 복사해 갖습니다. 가맹점 서버·운영 도구용 API 입니다.

  • 구매자가 쿠폰을 받는 API 는 쿠폰 (구매자)의 POST /v1/coupon/download 입니다.
  • 쿠폰존은 다운로드 쿠폰을 모아 보여 주는 쇼핑몰 화면입니다. 이 문서의 zone API 로 노출 순서·배지를 관리합니다.

인증 방식

이 문서의 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 문서 최초 작성

함께 보기