로그인한 구매자 본인의 쿠폰함을 다룹니다. 스토어프론트(쇼핑몰 화면)가 "내 쿠폰", "주문서에서 쓸 수 있는 쿠폰", "쿠폰 받기" 기능을 만들 때 씁니다.
- Basic 인증과 회원 지정이 필수입니다. 회원은 회원 JWT(
Bootpay-User-JWT) 또는user_id중 하나로 정합니다.user_id는 쇼핑몰 서버가 자기 로그인 세션의 회원 ID 를 넣어 보냅니다(쿼리 또는 본문). 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다.user_ex_uid·user_external_uid·user_uid도 같은 뜻입니다.user_id는 secretKey 인증(Basic·Bearer)일 때만 받습니다. 브라우저가 보낸 값을 그대로 넘기지 마세요 — 인증 — 호출 구조.- 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403
USER_NOT_MATCH입니다.
- 가맹점 서버용 쿠폰 API(
/v1/coupons,/v1/coupon_templates,/v1/coupon_policies)는 인증 방식을 정비 중이라 공개 문서에서 제외했습니다.
정리하면 이렇습니다.
| 누가 | 무엇을 | 쓰는 API |
|---|---|---|
| 스토어프론트(구매자 본인) | 내 쿠폰함·사용 가능 쿠폰·쿠폰 받기 | /v1/coupon (이 문서) |
| 가맹점 서버·운영 도구 | 회원을 지정한 조회, 적용 미리보기, 발급 쿠폰 검색 | /v1/coupons (정비 중, 비공개) |
쿠폰 객체
세 API 가 같은 형태의 쿠폰 객체를 돌려줍니다. 값이 없는 필드는 응답에서 빠집니다.
{
"coupon_id": "66f4...",
"coupon_template_id": "66e0...",
"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": [],
"status": 1,
"issued_at": "2026-09-20T10:00:00+09:00",
"valid_from": "2026-09-20T10:00:00+09:00",
"expires_at": "2026-10-20T10:00:00+09:00"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| coupon_id | string | 쿠폰 ID (회원이 받은 쿠폰 한 장) |
| coupon_template_id | string | 이 쿠폰을 만든 쿠폰 템플릿 ID |
| name | string | 쿠폰명 |
| code | string | 쿠폰 코드 |
| coupon_type | integer | 1=주문 쿠폰, 2=상품 쿠폰, 3=배송비 쿠폰, 4=구독 쿠폰 |
| discount_type | integer | 1=정액(원), 2=정률(%), 3=무료배송(배송비 쿠폰 전용) |
| discount_value | string | 할인값. 숫자 문자열(예: "3000.0", "10.0") |
| max_discount_amount | string | 정률 할인 상한 금액(숫자 문자열) |
| min_order_amount | string | 최소 주문 금액(숫자 문자열) |
| target_type | integer | 적용 대상 1=전체 상품, 2=특정 상품, 3=특정 카테고리 |
| target_ids | string[] | target_type 이 2·3 일 때 대상 상품·카테고리 ID |
| status | integer | 1=사용 가능, 2=사용 완료, 3=만료, 4=주문 취소로 복원 대기 |
| issued_at | string | 발급 시각(ISO 8601) |
| valid_from | string | 사용 시작 시각 |
| expires_at | string | 만료 시각 |
| used_at | string | 사용 시각(사용한 쿠폰만) |
| subscription_apply_mode | string | 구독 쿠폰(coupon_type 4)만. first_bill_only(첫 결제만), n_bills(N회차까지), all_bills(모든 회차) |
| subscription_apply_count | integer | 구독 쿠폰만. n_bills 일 때 적용 회차 수 |
GET /v1/coupon
내 쿠폰함 목록입니다. 최근에 받은 순서입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:coupon_list - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | status | integer | 상태 필터 1~4. 없으면 전체 | ||
| query | page | integer | 1 | 1 미만이면 1 | |
| query | limit | integer | 1 | 페이지 크기. 보내지 않으면 1개만 옵니다. 항상 명시하세요(예: 20) |
공통 페이지네이션 규칙을 따르지 않습니다. limit 상한이 없으니 100 이하로 보내세요.
응답
200 OK
{
"coupons": [ { "coupon_id": "66f4...", "name": "가을 맞이 3,000원 할인", "status": 1 } ],
"total_count": 3,
"available_count": 1,
"used_count": 1,
"expired_count": 1,
"has_more": false
}json| 필드 | 타입 | 설명 |
|---|---|---|
| coupons[] | array | 쿠폰 객체 목록 |
| total_count | integer | status 조건에 맞는 전체 개수 |
| available_count / used_count / expired_count | integer | 상태별 개수(status 필터와 무관, 탭 배지용) |
| has_more | boolean | 다음 페이지가 있는지 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT·user_id 가 모두 없거나 JWT 세션이 끝남 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
| 401 | USER_JWT_INVALID |
JWT 서명이 틀렸거나 만료됨 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경 - 2026-09-23 문서 최초 작성
GET /v1/coupon/available
지금 사용할 수 있는 내 쿠폰 목록입니다. 상태가 사용 가능(1)이고, 사용 시작 시각이 지났고, 만료되지 않은 쿠폰만 최근에 받은 순서로 돌려줍니다. 특정 주문에 적용 가능한지(최소 주문 금액·대상 상품)는 따지지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:coupon_available - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
파라미터 없음. 페이지네이션 없이 전부 돌려줍니다.
응답
200 OK — 쿠폰 객체 배열입니다(객체로 감싸지 않음).
[
{ "coupon_id": "66f4...", "name": "가을 맞이 3,000원 할인", "coupon_type": 1, "discount_type": 1, "discount_value": "3000.0", "status": 1 }
]json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT·user_id 가 모두 없거나 JWT 세션이 끝남 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경 - 2026-09-23 문서 최초 작성
POST /v1/coupon/download
쿠폰 템플릿으로 쿠폰을 한 장 받습니다(쿠폰존·상품 상세의 "쿠폰 받기").
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:coupon_download - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | coupon_template_id | string | O | 받을 쿠폰 템플릿 ID. 이 쇼핑몰의 템플릿이어야 합니다 |
발급 조건: 템플릿이 활성 상태이고, 발급 기간 안이고, 총 발급 수량이 남았고, 1인당 발급 한도 안이어야 합니다. 1인당 한도는 아직 쓰지 않은 쿠폰만 셉니다. 사용·만료·복원 대기 쿠폰은 세지 않으므로, 쓰고 나면 다시 받을 수 있습니다.
사용 기간은 템플릿 설정을 따릅니다(받은 날부터 N일, 또는 정해진 기간).
응답
200 OK — 받은 쿠폰 객체.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | COUPON_TEMPLATE_NOT_FOUND |
없는 템플릿이거나 다른 쇼핑몰의 템플릿 |
| 400 | COUPON_ISSUE_LIMIT_EXCEEDED |
발급 조건을 만족하지 않음(비활성·발급 기간 밖·수량 소진·1인당 한도 도달) |
| 401 | USER_SESSION_INVALID |
JWT·user_id 가 모두 없거나 JWT 세션이 끝남 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경 - 2026-09-14 다른 쇼핑몰의 템플릿은 404
- 2026-09-23 문서 최초 작성
