> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/api-guide/store-front/promotion/undefined-1.md).

# 쿠폰발급

쇼핑몰에서는 할인 및 다양한 혜택을 받을 수 있는 코드나 쿠폰을 제공합니다. 정률 쿠폰과 정액 쿠폰 두 가지 속성을 갖고 있으며, 결제 시 해당 쿠폰을 사용하면 할인 혜택을 받을 수 있습니다. 또한, 무료배송이나 무료반품을 제공하는 특별한 쿠폰도 존재합니다.

***

## 주요 기능

* **쿠폰 발급 시스템**
  * 회원은 스토어 프론트(Store Front)에서 직접 쿠폰을 발급받을 수 있습니다.
  * 시스템에서는 백 오피스(Back Office)에서 쿠폰을 발급하는 시스템이 운영됩니다.
* **자동 발급 시스템**
  * 자동발급유형코드를 통해 조건에 맞는 쿠폰을 자동으로 발급하는 조건부 쿠폰 발급 시스템이 존재합니다.
* **쿠폰 조회**
  * 상품상세에서는 다운로드 가능 쿠폰 조회 API를 통해 상품별 다운로드 가능한 쿠폰 목록을 조회할 수 있습니다.
  * 회원별 쿠폰 조회 API를 통해 회원이 보유하고 있는 쿠폰 목록을 조회할 수 있습니다.

## 프로세스 정의

<figure><img src="/files/23sYHGSUQDNnbRDr8SOv" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

### 상품상세 다운로드 쿠폰조회

상품상세 페이지에서 해당 상품에 적용 가능한 쿠폰을 조회합니다.
{% endstep %}

{% step %}

### 회원 별 쿠폰조회

회원이 보유하고 있는 쿠폰 목록을 조회하여 쿠폰의 유효기간, 쿠폰의 종류 등을 확인합니다.
{% endstep %}

{% step %}

### 쿠폰 다운로드(BO)

시스템에서 쿠폰을 발급할 때 사용하는 API로, 신규회원가입, 생일축하쿠폰 등 쿠폰을 발급할 때 사용합니다.
{% endstep %}

{% step %}

### 쿠폰 다운로드(FO)

회원이 직접 쿠폰 다운로드 요청 및 일련의 행위를 통해 쿠폰을 발급받는 서비스 입니다.
{% endstep %}

{% step %}

### 자동발급 유형별 쿠폰 조회

자동발급 유형 조건에 맞는 유효한 쿠폰이 존재하는지 조회합니다.
{% endstep %}
{% endstepper %}

## API 기능 목록

<table><thead><tr><th width="129">API</th><th width="386.2222900390625">설명</th><th width="96.888916015625">Server</th><th width="92.4444580078125">메소드</th><th>비고</th></tr></thead><tbody><tr><td>쿠폰 다운로드(FO)</td><td>상품페이지 및 이벤트페이지 등을 통하여 로그인한 회원을 대상으로 회원이 직접 쿠폰을 발급받을 수 있는 서비스 입니다.</td><td>Order</td><td>POST</td><td><a href="http://api.x2bee.com/content?msa=order&#x26;depth=%EC%BF%A0%ED%8F%B0%20%EB%B0%9C%EA%B8%89&#x26;path=cpnDownFo">🔗API 확인하기></a></td></tr><tr><td>쿠폰 다운로드(BO)</td><td>배치나 신규회원 가입 등의 타 모듈 서비스 중 쿠폰 발급이 필요한 경우 모듈에서 쿠폰 발급을 요청하는 서비스 입니다.</td><td>Order</td><td>POST</td><td><p><a href="https://api.x2bee.com/content?msa=order&#x26;depth=%EC%BF%A0%ED%8F%B0%20%EB%B0%9C%EA%B8%89&#x26;path=cpnDownBo">🔗API 확인하기></a></p><p>회원 정보 목록 조회: /api/member/v1/member/getMemberInfoList</p></td></tr><tr><td>회원별 쿠폰 조회</td><td>회원이 보유하고 있는 쿠폰 정보를 조회합니다.</td><td>Order</td><td>GET</td><td><a href="https://api.x2bee.com/content?msa=order&#x26;depth=%EC%BF%A0%ED%8F%B0%20%EB%B0%9C%EA%B8%89&#x26;path=getCpnIssuList">🔗API 확인하기></a></td></tr><tr><td>상품상세 다운로드가능 쿠폰 조회</td><td>상품상세 페이지에서 해당 상품에 다운로드 가능한 쿠폰의 목록을 조회합니다.</td><td>Order</td><td>POST</td><td><a href="https://api.x2bee.com/content?msa=order&#x26;depth=%EC%BF%A0%ED%8F%B0%20%EB%B0%9C%EA%B8%89&#x26;path=getCpnListForGoodsDetail">🔗API 확인하기></a></td></tr><tr><td>자동발급유형별 쿠폰 조회</td><td>특정 기준 조건에 부합한 회원에게 자동으로 쿠폰 발급을 위해 해당 자동발급유형코드 중 발급 유효한 쿠폰 목록을 존재합니다.</td><td>Order</td><td>GET</td><td><a href="https://api.x2bee.com/content?msa=order&#x26;depth=%EC%BF%A0%ED%8F%B0%20%EB%B0%9C%EA%B8%89&#x26;path=getCouponListByAutoIssuTypCd">🔗API 확인하기></a></td></tr></tbody></table>

## 용어 정의

<table><thead><tr><th width="155.111083984375">명칭</th><th>설명</th><th data-hidden></th></tr></thead><tbody><tr><td>조건부자동발급 쿠폰</td><td>특정한 기준 조건(자동발급유형)에 부합한 회원의 경우, 회원이 직접 요청하지 않아도 시스템에서 자동으로 해당 회원에게 자동으로 쿠폰을 발급하는 시스템입니다.</td><td></td></tr><tr><td>자동발급유형코드(MK008)</td><td>자동으로 발급되는 쿠폰유형을 정의한 코드입니다.<br>신규회원 가입 쿠폰(2101), 쇼핑백 전용 쿠폰(2201) <br>장기미구매고객 쿠폰(2301), 생일 축하 쿠폰(2401)<br>등급 축하 쿠폰(2501), 앱 첫 로그인 환영 쿠폰(2601)<br>PUSH 수신동의 쿠폰(2701)</td><td></td></tr></tbody></table>

## 기타 참고사항

* 쿠폰 사용 처리
  * 주문 및 클레임 시 해당 쿠폰 발급 번호 사용 처리합니다.
* 쿠폰 만료 도래 안내
  * 사용자가 보유한 쿠폰 중 유효기간이 3일 또는 당일일인 경우 만료 도래 안내(알림함, 이메일 발송)
* 쿠폰 사용 취소 처리
  * 주문 시(주문 처리 중 실패 시): 발급된 쿠폰의 속성 중 사용여부를 ‘N’으로 수정하였으나, 작성일 기준 동일 트랜잭션 내에서 작업 가능하므로 해당 기능을 사용하지 않습니다.
  * 클레임 및 기타 호출 시
    * 기존 발급 이력을 기반으로 새로운 쿠폰 생성 합니다.
    * 발급한 이력이 있는 경우에는 쿠폰 발급을 진행하지 않습니다.
    * 쿠폰 발급 횟수 제한은 체크하지 않으며, 재발급 시 기존 쿠폰 사용 가능 기간이 넘지 않았을 경우 기존 기간으로 발급을 진행하고, 기존 쿠폰 사용 가능 기간이 넘었을 경우 오늘부터 쿠폰 복원유효일수(ST001) 값을 조회하여 사용 가능한 쿠폰으로 발급합니다.