판매자 서버에서 쿠폰을 운영할 때 쓰는 API 입니다. 관리자 화면의 쿠폰 기능(구독에 적용된 쿠폰, 템플릿별 적용 통계, 수동 발급, 발급 취소, 회원별 쿠폰 이력)을 서버 SDK 로 똑같이 호출할 수 있게 열어 둔 것입니다.
- 모두 판매자 서버 전용입니다. 대상 회원은 회원 JWT 가 아니라 경로·본문의
user_id로 지정합니다. 이 API 는Bootpay-User-JWT를 읽지 않으며,user_id는 호출한 회원이 아니라 쿠폰을 받거나 조회할 대상 회원입니다. - 필요한 scope 는 모두
supervisor역할입니다.Bootpay-Role헤더를 보내면 그 역할 이름으로 검사하므로, 이 API 들을 부를 때는 헤더를 빼거나supervisor로 보내세요 — 인증. - 쿠폰 금액 필드(
discount_value·max_discount_amount·min_order_amount·used_discount_amount)는 JSON 문자열(예:"1000")로 옵니다.
현재 상태 (2026-09-23):
GET /v1/sdk/order_subscriptions/:id/coupon-bindings와GET /v1/sdk/coupon_templates/:id/binding-stats는 경로의 ID 를 읽지 못해 항상500 SERVER_ERROR를 돌려줍니다. 수정되기 전까지는 쓰지 마세요.
GET /v1/sdk/order_subscriptions/:id/coupon-bindings
구독 한 건에 적용된 쿠폰 이력을 적용 시각 최신순으로 돌려줍니다. 위 현재 상태대로 지금은 항상 500 입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:order_subscription_coupon_list - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 구독 ID (order_subscription_id) |
응답
200 OK — 적용 이력 배열 (페이지네이션 없음)
[
{
"subscription_coupon_binding_id": "6651a0c2a1b2c3d4e5f60111",
"project_id": "6600a0c2a1b2c3d4e5f60000",
"user_id": "6650a0c2a1b2c3d4e5f60222",
"order_subscription_id": "6651a0c2a1b2c3d4e5f60333",
"coupon_id": "6651a0c2a1b2c3d4e5f60444",
"coupon_template_id": "6651a0c2a1b2c3d4e5f60555",
"applied_at": "2026-05-25T09:00:00+09:00",
"total_discount_amount": 3000,
"discount_per_bill": [3000],
"apply_mode": "first_bill_only",
"apply_count": null,
"discount_target": "subscription_amount",
"adjustment_ids": ["6651a0c2a1b2c3d4e5f60666"],
"coupon_name_snapshot": "첫 달 3천원 할인",
"coupon_type_snapshot": 3,
"discount_type_snapshot": 1,
"discount_value_snapshot": 3000,
"status": "active",
"terminated_at": null,
"created_at": "2026-05-25T09:00:00+09:00",
"updated_at": "2026-05-25T09:00:00+09:00"
}
]json| 필드 | 타입 | 설명 |
|---|---|---|
| subscription_coupon_binding_id | string | 적용 이력 ID |
| order_subscription_id | string | 구독 ID |
| coupon_id | string | 적용된 발급 쿠폰 ID |
| coupon_template_id | string | 쿠폰 템플릿 ID |
| applied_at | string | 적용 시각 |
| total_discount_amount | number | 할인 총액 |
| discount_per_bill | array | 회차별 할인 금액 |
| apply_mode | string | 적용 방식 (예: first_bill_only) |
| apply_count | integer | 적용 회차 수 (해당 방식일 때만) |
| discount_target | string | subscription_amount(구독 금액) 또는 shipping(배송비) |
| adjustment_ids | array | 이 적용으로 만들어진 구독 금액 조정 ID 목록 |
| coupon_name_snapshot · coupon_type_snapshot · discount_type_snapshot · discount_value_snapshot | 적용 시점의 쿠폰 이름·유형·할인 방식·할인값 | |
| status | string | active · subscription_paused · subscription_terminated · subscription_cancelled |
| terminated_at | string | 적용이 끝난 시각 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 500 | SERVER_ERROR |
현재 모든 요청 (위 현재 상태 참고) |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/sdk/coupon_templates/:id/binding-stats
쿠폰 템플릿 하나가 구독에 얼마나 적용됐는지 집계합니다. 위 현재 상태대로 지금은 항상 500 입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_template_detail - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 쿠폰 템플릿 ID |
응답
200 OK
{
"total_count": 42,
"active_count": 30,
"total_discount_amount": 126000,
"recent": []
}json| 필드 | 타입 | 설명 |
|---|---|---|
| total_count | integer | 이 몰에서 이 템플릿이 구독에 적용된 전체 건수 |
| active_count | integer | 그중 적용 중(active)인 건수 |
| total_discount_amount | integer | 할인 총액 합계 |
| recent | array | 최근 적용 이력 최대 10건. 항목 형식은 coupon-bindings 응답 항목과 같습니다 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 500 | SERVER_ERROR |
현재 모든 요청 (위 현재 상태 참고) |
변경 이력
- 2026-09-23 문서 최초 작성
POST /v1/sdk/coupons/manual-issue
쿠폰 템플릿으로 회원에게 쿠폰을 수동 발급합니다. 같은 회원에게 같은 템플릿을 30일 안에 이미 발급했다면 거절합니다(force 로 건너뜀).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_create - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | coupon_template_id | string | O | 발급할 쿠폰 템플릿 ID | |
| body | user_id | string | O | 받을 회원(대상 회원). 24자리 ObjectId 형식이면 회원 _id, 아니면 가맹점 회원 ID(ex_uid)로 찾습니다. user_ex_uid 로 보내도 됩니다. 이 몰 회원이 아니거나 탈퇴한 회원이면 404 |
|
| body | force | boolean | false | true 면 30일 중복 발급 검사를 건너뜁니다. 템플릿의 발급 한도 검사는 건너뛰지 않습니다 |
|
| body | issue_reason | string | 발급 사유 (CS 메모) | ||
| body | reissued_from_binding_id | string | 해지된 구독의 쿠폰을 다시 발급하는 경우 원래 적용 이력 ID |
응답
200 OK — 발급된 쿠폰
{
"coupon_id": "6651b0c2a1b2c3d4e5f60777",
"project_id": "6600a0c2a1b2c3d4e5f60000",
"seller_id": "6600a0c2a1b2c3d4e5f60001",
"user_id": "6650a0c2a1b2c3d4e5f60222",
"coupon_template_id": "6651a0c2a1b2c3d4e5f60555",
"name": "재구매 감사 쿠폰",
"code": "THANKS10",
"coupon_type": 1,
"discount_type": 2,
"discount_value": "10",
"max_discount_amount": "5000",
"min_order_amount": "0",
"target_type": 1,
"target_ids": [],
"status": 1,
"issued_at": "2026-05-25T09:00:00+09:00",
"valid_from": "2026-05-25T09:00:00+09:00",
"expires_at": "2026-06-24T23:59:59+09:00",
"used_at": null,
"used_order_id": null,
"used_discount_amount": null,
"issued_by_admin_id": null,
"issue_reason": "배송 지연 보상",
"reissued_from_binding_id": null,
"issue_method": 3
}json| 필드 | 타입 | 설명 |
|---|---|---|
| coupon_id | string | 발급된 쿠폰 ID |
| coupon_template_id | string | 템플릿 ID |
| name · code | string | 발급 시점에 복사한 쿠폰 이름·코드 |
| coupon_type · discount_type · target_type | integer | 템플릿에서 복사한 유형 값 |
| discount_value · max_discount_amount · min_order_amount | string | 할인값·최대 할인 금액·최소 주문 금액 (숫자 문자열) |
| target_ids | array | 적용 대상 ID 목록 |
| status | integer | 1 사용 가능 · 2 사용 완료 · 3 만료 · 4 취소 복원 대기 |
| issued_at · valid_from · expires_at | string | 발급·사용 시작·만료 시각 |
| used_at · used_order_id · used_discount_amount | 사용 정보 (사용 전에는 null) |
|
| issued_by_admin_id | string | 이 API 로 발급하면 항상 null (받는 회원을 발급자로 기록하지 않습니다) |
| issue_reason | string | 요청한 발급 사유 |
| reissued_from_binding_id | string | 요청한 원래 적용 이력 ID |
| issue_method | integer | 1 자동 · 2 다운로드 · 3 수동. 이 API 는 항상 3 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | COUPON_NOT_FOUND |
없는 coupon_template_id 또는 다른 몰의 템플릿 |
| 400 | REQUIRED_PARAMETER_IS_MISSING (131) |
user_id 없음 |
| 404 | USER_NOT_FOUND (2300) |
user_id 가 이 몰의 회원이 아님(없는 회원·다른 몰 회원·탈퇴 회원) — 쿠폰은 발급되지 않습니다 |
| 400 | COUPON_ALREADY_APPLIED_TO_SUBSCRIPTION |
30일 안에 같은 템플릿으로 이 회원에게 발급한 쿠폰이 있음 (force 없이). 메시지는 "이미 쿠폰이 적용된 구독입니다" 로 나가지만 뜻은 30일 중복 발급입니다 |
| 400 | COUPON_ISSUE_LIMIT_EXCEEDED |
템플릿의 발급 한도를 넘음 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28
user_id를 대상 회원으로 해석(_id·ex_uid, 이 몰·탈퇴 제외). 형식 오류500→404 USER_NOT_FOUND, 다른 몰 회원 발급 차단, 누락은400 REQUIRED_PARAMETER_IS_MISSING - 2026-09-28 인증된 프로젝트의 템플릿만 사용 — 다른 몰 템플릿 ID 는 404
COUPON_NOT_FOUND
DELETE /v1/sdk/coupons/:id
사용 전 쿠폰을 취소합니다. 쿠폰은 지워지지 않고 만료 상태(status: 3)가 됩니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_delete - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 발급 쿠폰 ID (coupon_id) |
응답
200 OK
{ "ok": true }json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | COUPON_NOT_FOUND |
없는 쿠폰 ID 또는 다른 몰의 쿠폰 |
| 400 | COUPON_ALREADY_USED |
사용 가능(status: 1) 상태가 아닌 쿠폰 — 사용 완료·만료·취소 복원 대기 |
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28 인증된 프로젝트의 쿠폰만 취소 — 다른 몰 쿠폰 ID 는 404
GET /v1/sdk/users/:user_id/coupons
한 회원이 이 몰에서 받은 쿠폰을 발급일 최신순으로 돌려줍니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:coupon_list - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | user_id | string | O | 대상 회원. 24자리 ObjectId 형식이면 회원 _id, 아니면 가맹점 회원 ID(ex_uid)로 찾습니다. 이 몰 회원이 아니거나 탈퇴한 회원이면 404 |
|
| query | status | integer | 쿠폰 상태로 거르기. 1 사용 가능 · 2 사용 완료 · 3 만료 · 4 취소 복원 대기 | ||
| query | page | integer | 1 | 페이지 번호 | |
| query | limit | integer | 20 | 페이지 크기 |
페이지네이션 공통 규칙의 최대값(100) 보정은 적용되지 않습니다.
응답
200 OK — 쿠폰 배열. 전체 개수(count)는 오지 않으므로, 받은 개수가 limit 보다 적으면 마지막 페이지로 판단하세요. 항목 형식은 수동 발급 응답과 같습니다.
[
{ "coupon_id": "6651b0c2a1b2c3d4e5f60777", "name": "재구매 감사 쿠폰", "status": 1 }
]json(예시는 일부 필드만 적었습니다.)
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | USER_NOT_FOUND (2300) |
user_id 가 이 몰의 회원이 아님(없는 회원·다른 몰 회원·탈퇴 회원) |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
- 2026-09-28
user_id를 대상 회원으로 해석(_id·ex_uid). 형식 오류500·다른 몰 회원 빈 목록 →404 USER_NOT_FOUND. 회원을 찾으면 페이지 처리 오류로 항상500이던 결함 수정(page·limit은 1 미만이면 1)
