쿠폰 (구매자)

로그인한 구매자 본인​​의 쿠폰함을 다룹니다. 스토어프론트(쇼핑몰 화면)가 "내 쿠폰", "주문서에서 쓸 수 있는 쿠폰", "쿠폰 받기" 기능을 만들 때 씁니다.

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

함께 보기