쿠폰 운영 (SDK)

판매자 서버에서 쿠폰을 운영할 때 쓰는 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)

함께 보기