쿠폰

회원에게 발급된 쿠폰​​을 운영 관점에서 조회하고, 특정 회원 기준으로 사용 가능 쿠폰·적용 금액을 계산합니다. 가맹점 서버·운영 도구용입니다.

구매자 본인의 쿠폰함(스토어프론트)은 이 API 가 아니라 쿠폰 (구매자)(/v1/coupon)을 씁니다. 두 API 의 차이는 다음과 같습니다.

/v1/coupon (구매자) /v1/coupons (이 문서)
쓰는 곳 스토어프론트 — 로그인한 구매자 본인 가맹점 서버·운영 도구
대상 회원 회원 JWT 의 회원만 user_id 파라미터로 지정(대상 회원 — 아래 참고)
인증 Basic 인증 + 회원 JWT 필수 Basic 인증(secretKey) + supervisor scope. 브라우저에서 부르지 않습니다
기능 내 쿠폰함·사용 가능 쿠폰·쿠폰 받기 발급 쿠폰 검색·상세, 회원별 사용 가능 쿠폰, 상품별 받을 수 있는 쿠폰, 적용 미리보기

쿠폰 발급(수동 발급)과 템플릿 관리는 쿠폰 템플릿, 쇼핑몰 쿠폰 설정은 쿠폰 정책을 봅니다. 쿠폰 필드의 값 정의(coupon_type·discount_type·status 등)는 쿠폰 객체와 같습니다.

인증 방식

subscription-preview 를 뺀 이 문서의 API 는 가맹점 서버 전용​​입니다. secretKey 로 만든 Basic 인증(또는 그 키로 발급한 Bearer 토큰)이 필요하고, 키체인 키면 각 API 의 supervisor scope 를 받아 둬야 합니다.

  • 스토어프론트에 들어가는 clientKey(Bootpay-Client-Key 헤더)만으로는 호출할 수 없습니다.
  • 조회·계산은 인증한 프로젝트 안에서만 합니다. 다른 쇼핑몰의 쿠폰 ID 는 없는 쿠폰과 같은 404 입니다.
  • 회원 JWT 는 쓰지 않습니다.

대상 회원(user_id)

user_id 는 호출하는 회원이 아니라 조회·계산할 대상 회원​​입니다. 요청한 회원 세션이 바뀌지 않습니다.

  • 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 도 같은 뜻이고, 로그인 아이디는 login_id 로 보냅니다.
  • 이 몰의 회원이 아니거나 탈퇴한 회원이면 404 USER_NOT_FOUND 입니다. 목록 필터로 쓸 때도 전체 목록으로 넘어가지 않고 404 입니다.
  • user_id 와 login_id 를 함께 보냈는데 서로 다른 회원이면 403 USER_NOT_MATCH 입니다.
HTTP error_code 언제
400 TOKEN_AUTHORIZE_TYPE_INVALID Authorization 헤더가 없거나 Basic·Bearer 가 아님(clientKey 헤더만 보낸 경우 포함)
401 API_SCOPE_INVALID 키체인 키에 이 API 의 scope 가 없음
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원

인증 오류 전체는 인증을 봅니다.

응답의 null 값 필드는 빠집니다(downloadable_for_product 제외). 금액 필드(discount_value·max_discount_amount·min_order_amount·used_discount_amount)는 숫자 문자열(예: "3000.0")입니다.

GET /v1/coupons

이 쇼핑몰에서 발급된 쿠폰을 검색합니다. 최근 발급 순서입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:coupon_search
  • 회원 JWT(Bootpay-User-JWT): 필요 없음. user_id 는 선택 필터(대상 회원)

요청

위치 이름 타입 필수 기본값 설명
query user_id string 이 회원의 쿠폰만. 대상 회원 규칙(위 참고) — 이 몰 회원이 아니면 404 USER_NOT_FOUND
query coupon_template_id string 이 템플릿으로 발급된 쿠폰만
query status integer 상태 1=사용 가능, 2=사용 완료, 3=만료, 4=복원 대기
query page integer 1 1 이상으로 보내세요
query limit integer 20 1 이상으로 보내세요

공통 페이지네이션 보정을 하지 않습니다. page·limit 이 0 이하이거나 숫자가 아니면 오류가 날 수 있고, limit 상한이 없습니다. coupon_template_id 가 ID 형식이 아니면 500 SERVER_ERROR 입니다.

응답

200 OK

{
  "coupons": [
    {
      "coupon_id": "66f4...",
      "project_id": "64a0...",
      "seller_id": "64a1...",
      "user_id": "66a0...",
      "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": 2,
      "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",
      "used_at": "2026-09-21T12:00:00+09:00",
      "used_order_id": "66f5...",
      "used_discount_amount": "3000.0",
      "user": { "user_id": "66a0...", "name": "홍길동", "phone": "01012345678", "email": "user@example.com", "login_id": "hong" },
      "template_name": "가을 맞이 3,000원 할인"
    }
  ],
  "total_count": 1
}json
필드 타입 설명
coupons[].coupon_id string 쿠폰 ID
coupons[].project_id / seller_id string 프로젝트 / 판매자 ID
coupons[].user_id string 쿠폰을 가진 회원 ID
coupons[].used_order_id string 사용한 주문 ID
coupons[].used_discount_amount string 사용 시점 실제 할인 금액
coupons[].issued_by_admin_id string 관리자가 수동 발급한 경우 발급자 ID
coupons[].issue_reason string 수동 발급 사유
coupons[].reissued_from_binding_id string 구독 해지 복원으로 다시 발급된 경우 원본 연결 ID
coupons[].issue_method integer 발급 방식 1=자동, 2=다운로드, 3=수동
coupons[].user object 회원 정보 user_id·name·phone·email·login_id·comment (개인정보 — 취급에 주의)
coupons[].template_name string 템플릿의 현재 이름
(그 밖) 쿠폰 객체와 같음
total_count integer 조건에 맞는 전체 개수

오류

인증 방식 절의 오류(user_id 를 준 경우 404 USER_NOT_FOUND 포함) 외에 도메인 오류는 없습니다. 공통 형식은 오류를 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 조회를 인증한 프로젝트로 한정
  • 2026-09-23 문서 최초 작성

GET /v1/coupons/:id

발급된 쿠폰 한 장의 상세입니다. 응답은 GET /v1/coupons 의 coupons[] 항목과 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:coupon_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음. 회원과 무관

요청

위치 이름 타입 필수 기본값 설명
path id string O 쿠폰 ID(coupon_id)

응답

200 OK — GET /v1/coupons 의 coupons[] 항목 하나.

오류

HTTP error_code 언제
404 COUPON_NOT_FOUND 없는 쿠폰, 다른 쇼핑몰의 쿠폰이거나 ID 형식이 아님

공통 형식은 오류를 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 조회를 인증한 프로젝트로 한정
  • 2026-09-23 문서 최초 작성

GET /v1/coupons/available

지정한 회원이 지금 쓸 수 있는 쿠폰 목록입니다. 결과는 구매자용 GET /v1/coupon/available과 같습니다(상태 사용 가능, 사용 시작 시각 경과, 만료 전).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:coupon_available
  • 회원 JWT(Bootpay-User-JWT): 필요 없음. user_id 로 대상 회원 필수

요청

위치 이름 타입 필수 기본값 설명
query user_id string O 대상 회원 — 회원 ID 또는 외부 회원 ID(ex_uid). 별칭 user_ex_uid 등, login_id 도 가능

응답

200 OK — 쿠폰 객체 배열(객체로 감싸지 않음). 페이지네이션 없음.

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING user_id(또는 별칭·login_id)가 없음
404 USER_NOT_FOUND 이 몰의 회원이 아니거나 탈퇴한 회원

공통 형식은 오류를 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 조회를 인증한 프로젝트로 한정
  • 2026-09-28 대상 회원을 ex_uid·별칭으로도 지정. 없는·다른 몰 회원은 빈 목록 대신 404 USER_NOT_FOUND, 누락은 REQUIRED_PARAMETER_IS_MISSING
  • 2026-09-23 문서 최초 작성

GET /v1/coupons/downloadable_for_product

상품 상세에서 받을 수 있는 쿠폰(다운로드 방식·활성 템플릿) 목록입니다. 템플릿의 적용 대상이 전체 상품이거나, 이 상품이거나, 이 상품의 카테고리인 것만 최근 생성 순서로 돌려줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:coupon_downloadable_for_product
  • 회원 JWT(Bootpay-User-JWT): 필요 없음. user_id 로 대상 회원 선택

요청

위치 이름 타입 필수 기본값 설명
query product_id string O 상품 ID
query user_id string 대상 회원(선택). 주면 회원별 발급 여부·남은 수량을 채웁니다. 이 몰 회원이 아니면 404 USER_NOT_FOUND

user_id 가 없고 쿠폰 정책의 show_coupon_to_guest 가 false 면 빈 목록입니다. 상품이 없어도 빈 목록입니다(오류 아님).

응답

200 OK

{
  "coupons": [
    {
      "_id": "66e0...",
      "coupon_template_id": "66e0...",
      "name": "가을 맞이 3,000원 할인",
      "code": "FALL3000",
      "description": null,
      "coupon_type": 1,
      "discount_type": 1,
      "discount_value": "3000.0",
      "max_discount_amount": null,
      "min_order_amount": "20000.0",
      "target_type": 1,
      "target_ids": [],
      "total_quantity": 1000,
      "issued_quantity": 120,
      "limit_per_user": 1,
      "available_from": "2026-09-20 00:00:00 +0900",
      "available_until": "2026-10-31 23:59:59 +0900",
      "valid_days": 30,
      "active": true,
      "zone_badge": "hot",
      "zone_tags": [],
      "zone_priority": 0,
      "already_issued": true,
      "remaining_for_user": 0,
      "disabled": true,
      "disabled_reason": "limit_exceeded"
    }
  ],
  "total": 1
}json
필드 타입 설명
coupons[]._id / coupon_template_id string 쿠폰 템플릿 ID (같은 값). 받기는 POST /v1/coupon/download 에 이 값을 넘깁니다
coupons[].total_quantity integer|null 총 발급 수량. null 또는 0 이면 무제한
coupons[].issued_quantity integer 지금까지 발급된 수량
coupons[].limit_per_user integer 1인당 발급 한도
coupons[].available_from / available_until string|null 발급 기간. 형식이 YYYY-MM-DD HH:MM:SS +0900 입니다(ISO 8601 아님)
coupons[].valid_days integer|null 받은 날부터 사용 가능한 일수
coupons[].zone_badge / zone_tags / zone_priority 쿠폰존 노출 설정
coupons[].already_issued boolean user_id 를 줬을 때만. 이 회원이 이 템플릿 쿠폰을 한 번이라도 받았는지
coupons[].remaining_for_user integer|null user_id 를 줬을 때만. 1인당 한도에서 받은 수를 뺀 값(한도 없으면 null)
coupons[].disabled boolean 지금 받을 수 없을 때만 true 로 붙습니다
coupons[].disabled_reason string out_of_period(발급 기간 밖)·sold_out(수량 소진)·limit_exceeded(1인당 한도 도달)
total integer 개수

이 응답은 null 필드도 그대로 옵니다.

오류

HTTP error_code 언제
400 INVALID_PARAMETER product_id 가 없음
404 USER_NOT_FOUND user_id 를 줬는데 이 몰의 회원이 아니거나 탈퇴한 회원

공통 형식은 오류를 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 조회를 인증한 프로젝트로 한정
  • 2026-09-23 문서 최초 작성

POST /v1/coupons/preview

지정한 회원이 쿠폰을 쓰면 얼마가 할인되는지 미리 계산합니다. 쿠폰을 사용 처리하지 않습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:coupon_preview
  • 회원 JWT(Bootpay-User-JWT): 필요 없음. user_id 로 대상 회원 필수

요청

위치 이름 타입 필수 기본값 설명
body user_id string O 대상 회원 — 회원 ID 또는 외부 회원 ID(ex_uid). 별칭 user_ex_uid 등, login_id 도 가능
body coupon_ids string[] 적용할 쿠폰 ID 목록. 비었으면 할인 0
body order_items object[] [] 주문 상품 목록
body order_items[].product_id string 상품 ID. 상품 쿠폰·대상 지정 쿠폰 판정에 사용
body order_items[].category_id string 카테고리 ID. 카테고리 대상 쿠폰 판정에 사용
body order_items[].price number 0 이 줄의 금액(단가 × 수량으로 계산해 보냅니다). 숫자로 보내세요
  • 쿠폰 개수는 쿠폰 정책의 maximum_coupon_apply_count 이하여야 합니다.
  • 대상 회원의 쿠폰이 아니거나(다른 회원·다른 쇼핑몰 쿠폰, ID 형식 오류 포함), 사용 가능 상태가 아니거나 만료됐거나 할인액이 0 인 쿠폰은 오류 없이 결과에서 빠집니다.
  • 배송비를 받지 않으므로 배송비 쿠폰은 이 미리보기에서 항상 할인 0 입니다.
  • 할인은 쿠폰의 적용 대상·최소 주문 금액·정률 상한을 반영하고, 할인액이 대상 금액을 넘지 않습니다. 정률 할인은 원 미만을 버립니다.
{
  "user_id": "66a0...",
  "coupon_ids": ["66f4..."],
  "order_items": [ { "product_id": "65b2...", "category_id": "65a1...", "price": 24000 } ]
}json

응답

200 OK

{
  "coupon_discount_amount": 3000,
  "snapshots": [
    {
      "coupon_id": "66f4...",
      "coupon_template_id": "66e0...",
      "name": "가을 맞이 3,000원 할인",
      "code": "FALL3000",
      "coupon_type": 1,
      "discount_type": 1,
      "discount_value": "3000.0",
      "actual_discount_amount": 3000,
      "applied_item_ids": ["65b2..."]
    }
  ]
}json
필드 타입 설명
coupon_discount_amount number 할인 합계
snapshots[] array 실제로 적용된 쿠폰별 결과
snapshots[].actual_discount_amount number 이 쿠폰의 할인액
snapshots[].applied_item_ids string[] 할인이 적용된 상품 ID (구독·배송비 쿠폰은 빈 배열)

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING user_id(또는 별칭·login_id)가 없음
404 USER_NOT_FOUND 이 몰의 회원이 아니거나 탈퇴한 회원
400 COUPON_POLICY_NOT_FOUND 쇼핑몰 쿠폰 정책이 아직 없음 (coupon_ids 가 있을 때)
400 COUPON_NOT_AVAILABLE 쿠폰 정책에서 쿠폰 사용이 꺼져 있음
400 COUPON_MAX_APPLY_COUNT_EXCEEDED 쿠폰 개수가 주문당 최대 적용 수를 넘음

price 가 숫자가 아니면 500 SERVER_ERROR 입니다. 공통 형식은 오류를 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(스토어프론트 방식)에서 Basic 인증 + supervisor scope 로 변경, 조회를 인증한 프로젝트로 한정
  • 2026-09-28 대상 회원을 ex_uid·별칭으로도 지정, 대상 회원의 쿠폰만 계산(이전에는 다른 회원 쿠폰도 할인에 포함)
  • 2026-04-16 쿠폰 개수 초과를 조용히 버리지 않고 COUPON_MAX_APPLY_COUNT_EXCEEDED 로 거절
  • 2026-09-23 문서 최초 작성

POST /v1/coupons/:id/subscription-preview

구독 신청 전에, 구독 쿠폰 또는 배송비 쿠폰을 적용했을 때의 첫 결제 금액을 미리 계산합니다. 화면 표시용이며 실제 적용 시 서버가 다시 검증합니다.

  • 회원 요청​: 회원 본인이 받은 쿠폰으로 계산합니다. 쿠폰은 경로의 쿠폰 ID 또는 coupon_code 로 찾으며, 이 쇼핑몰에서 그 회원이 받은 쿠폰만 대상입니다. 실패하면 구체적인 사유(error_code)를 돌려줍니다.
  • 비회원 요청​: coupon_code 를 이 쇼핑몰의 활성 쿠폰 템플릿 코드​​로 찾아, 지금 받으면 발급될 쿠폰으로 계산합니다(저장하지 않음). 다른 회원이 받은 쿠폰은 보지 않습니다. 실패 사유는 구분하지 않고 같은 문구로 돌려줍니다. 응답의 coupon_id 는 저장된 쿠폰이 아니므로 쓰지 마세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:coupon_subscription_preview
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 가 유효하면 그 회원, JWT 가 없고 user_id(쇼핑몰 서버 지정, secretKey 인증 한정)가 있으면 그 회원입니다. JWT 가 무효인데 user_id 가 있으면 그 회원, 둘 다 없거나 JWT 가 무효이고 user_id 도 없으면 비회원 요청입니다 — 회원 JWT
    • user_id 는 쇼핑몰 서버가 자기 로그인 세션의 회원 ID 를 넣어 보냅니다(쿼리 또는 본문). 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 도 같은 뜻입니다.
    • 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다.
  • 비회원 요청은 같은 IP 에서 호출이 잦으면 제한됩니다. 일정 횟수를 넘으면 captcha_token 이 필요하고, 더 넘으면 차단됩니다. 쇼핑몰 서버를 거쳐 부르면 모든 비회원 호출이 서버 IP 하나로 묶여 제한에 먼저 걸릴 수 있습니다.

요청

위치 이름 타입 필수 기본값 설명
path id string O 쿠폰 ID(회원이 받은 쿠폰). 쿠폰 코드로 찾으려면 _
body coupon_code string 쿠폰 코드. 회원은 받은 쿠폰의 코드, 비회원은 쿠폰 템플릿 코드로 찾습니다
body draft object O 신청하려는 구독의 내용
body draft.subscription_type integer 구독 유형
body draft.origin_price number 회차 금액(할인 전)
body draft.amount_delivery_fee number 배송비
body draft.use_delivery boolean 배송 사용 여부
body draft.setup_price number 설치비
body draft.use_free_trial / free_trial_day boolean / integer 무료 체험 여부·일수
body draft.tax_free_price number 면세 금액
body draft.adjustments object[] 이미 적용된 조정 항목
body captcha_token string 호출 제한에 걸렸을 때 필요

응답

200 OK — 성공과 실패 모두 200 이며 ok 로 구분합니다.

성공

{
  "ok": true,
  "coupon_id": "66f4...",
  "coupon_name": "첫 달 5,000원 할인",
  "coupon_type": 4,
  "discount_type": 1,
  "discount_value": "5000.0",
  "discount_target": "subscription_amount",
  "applied_duration": 1,
  "apply_mode": "first_bill_only",
  "apply_count": 1,
  "discount_amount": 5000,
  "breakdown": {
    "origin_price": 30000,
    "times_benefit_sum": 0,
    "display_price": 30000,
    "coupon_discount": 5000,
    "setup_fee": 0,
    "delivery_fee": 3000,
    "total_first_bill": 28000
  },
  "per_bill_breakdown": [
    { "bill_no": 1, "is_unlimited": false, "base": 30000, "coupon_amount": 5000, "label": "1회차" }
  ]
}json

실패 (비회원 요청은 사유와 관계없이 같은 문구)

{ "ok": false, "error_code": 11501, "error_message": "사용할 수 없는 쿠폰입니다." }json
필드 타입 설명
ok boolean 계산 성공 여부
discount_target string subscription_amount(구독 금액) 또는 shipping(배송비)
apply_mode / apply_count string / integer 적용 회차 방식·횟수
discount_amount integer 할인 합계
breakdown object 첫 결제 금액 구성. total_first_bill 이 첫 결제 예상 금액
per_bill_breakdown[] array 회차별 할인(배송비 쿠폰은 빈 배열)
error_code integer 실패 시. 다른 API 와 달리 숫자 코드​​입니다(예: 11501 = 사용할 수 없는 쿠폰)
error_message string 실패 사유 문구

오류

HTTP error_code 언제
400 COUPON_GUEST_RATE_LIMIT_EXCEEDED 비회원 요청에서 같은 IP 의 호출이 너무 잦음(captcha_token 없이 제한을 넘었거나 차단 구간)
400 INVALID_PARAMETER 회원 요청인데 쿠폰 ID(_)도 coupon_code 도 없음
404 COUPON_NOT_FOUND 회원 요청에서 이 쇼핑몰의 그 회원 쿠폰이 아님(다른 회원·다른 쇼핑몰 쿠폰 포함)
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원

쿠폰을 쓸 수 없는 경우는 HTTP 오류가 아니라 200 의 ok: false 입니다. 공통 형식은 오류를 봅니다.

변경 이력

  • 2026-09-28 Basic 인증 필수, 회원을 JWT 또는 user_id 로 지정. 회원 쿠폰은 그 회원이 받은 쿠폰만, 비회원 coupon_code 는 쿠폰 템플릿 코드로만 찾도록 변경(이전에는 인증 헤더를 읽지 않아 항상 ok: false)
  • 2026-04-14 비회원 미리보기와 호출 제한 추가
  • 2026-09-23 문서 최초 작성

함께 보기