> 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/back-office/marketing-bo/undefined-3.md).

# 쿠폰관리

쿠폰 관리 서비스를 통해 다양한 쿠폰 종류를 등록, 수정하고, 등록된 쿠폰들의 목록을 조회하여 상세한 정보 및 상태를 확인할 수 있습니다. 이 서비스는 쿠폰의 무분별한 사용 및 발급을 방지하고, 쿠폰 관련 비용을 효율적으로 관리하는 데에 중점을 둡니다.

***

## 주요 기능

* **쿠폰 등록 및 수정**
  * 쿠폰의 기본정보, 쿠폰혜택, 적용대상, 제외대상 등 세부적인 설정을 통해 쿠폰을 등록하고 수정할 수 있습니다.
  * 발급 방식을 설정하여 해당 조건에 부합하는 회원에게 자동으로 쿠폰을 발급할 수 있습니다.
  * 정액 또는 정률 할인 유형의 쿠폰을 설정하고, 쿠폰 최소/최대 금액을 지정하여 쿠폰 사용에 제한을 둘 수 있습니다.
* **쿠폰 상태 관리**
  * 등록된 쿠폰의 상태를 확인하고 중단된 쿠폰의 경우 발급 및 사용이 불가능하도록 관리합니다.
* **쿠폰 비용 조회**
  * 한 번의 조회로 발급된 쿠폰의 현황과 쿠폰 사용으로 인한 비용을 효율적으로 조회할 수 있습니다.
  * 쿠폰을 발급받은 회원의 수, 쿠폰 사용 비율 및 건수 등을 통해 전반적인 쿠폰 관련 비용을 모니터링할 수 있습니다.

## 프로세스 정의

<figure><img src="/files/B6uTlGiPxGVFYZ3ydCyO" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

### 등록 쿠폰 조회

등록된 쿠폰의 목록과 개수를 조회합니다.
{% endstep %}

{% step %}

### 쿠폰 상태 변경

등록된 쿠폰의 상태를 변경합니다. 상태 구분으로는 정상 쿠폰과 중단 쿠폰이 존재합니다.
{% endstep %}

{% step %}

### 쿠폰 설정 및 발급

쿠폰의 기본정보, 쿠폰혜택, 적용대상 등 쿠폰 발급 조건을 입력하고 쿠폰을 발급합니다.
{% endstep %}

{% step %}

### 발급 현황 조회

쿠폰의 발급현황, 사용현황, 발생 비용 현황 등 쿠폰이 사용된 비용 정보 목록 및 개수를 조회합니다.
{% endstep %}

{% step %}

### 쿠폰 상세조회

등록 당시 입력한 쿠폰의 상세 정보를 조회합니다.
{% endstep %}

{% step %}

### 쿠폰 발급 현황

등록된 쿠폰을 발급받은 회원의 목록과 회원 수를 조회합니다.
{% endstep %}

{% step %}

### 데이터 다운로드

엑셀파일 내 등록된 회원 정보를 업로드하여, 파일 내 기록된 내용을 조회하여 전달합니다.
{% endstep %}

{% step %}

### 쿠폰 회수 절차

발급 된 회원 목록 중 특정 회원에게 오발급 및 비정상적으로 발급된 쿠폰을 회수합니다.
{% endstep %}

{% step %}

### 쿠폰 기간 수정

회원이 보유하고 있는 쿠폰의 유효기간을 변경합니다.
{% endstep %}

{% step %}

### 쿠폰 수동발급

시스템 오류로 인해 발급되지 않은 쿠폰을 회원에게 수동으로 발급합니다.
{% endstep %}

{% step %}

### 쿠폰 다국어 조회

쿠폰 관리의 다국어 등록 정보를 조회합니다.
{% endstep %}

{% step %}

### 쿠폰 다국어 등록

쿠폰 관리의 다국어 정보를 등록합니다.
{% endstep %}
{% endstepper %}

## API 기능 목록

<table><thead><tr><th width="137.888916015625">API</th><th width="334.22216796875">설명</th><th width="94.666748046875">Server</th><th width="93.5555419921875">메소드</th><th>비고</th></tr></thead><tbody><tr><td>쿠폰관리 목록 조회</td><td>입력된 조건을 통해 등록된 쿠폰의 목록을 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponList">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰관리 목록 개수 조회</td><td>입력된 조건을 통해 등록된 쿠폰의 개수를 조회합니다. 조회된 수에 따라 페이징 처리가 됩니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponListCount">🔗API 확인하기 ></a></td></tr><tr><td>공통코드 조회</td><td>쿠폰 목록 조회 시 조회 조건 중 쿠폰유형의 공통 코드를 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=system&#x26;depth=%EA%B3%B5%ED%86%B5%EC%BD%94%EB%93%9C%20%EC%A1%B0%ED%9A%8C&#x26;path=getStStdCd">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 등록/수정</td><td>관리자가 입력한 쿠폰 정보를 등록 혹은 수정합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=registerCoupon">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 상태 변경</td><td>쿠폰의 상태코드를 변경합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=saveCouponState">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 상세 정보 조회</td><td>등록된 쿠폰의 상세 정보를 조회 합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponData">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 발급회원 조회</td><td>등록한 쿠폰을 발급받은 회원 및 회원의 목록을 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponIssuedMemberList">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 발급회원 수 조회</td><td>등록한 쿠폰을 발급받은 회원의 목록 개수를 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponIssuedMemberListCount">🔗API 확인하기 ></a></td></tr><tr><td>회원 쿠폰 일괄발급 조회</td><td>엑셀 파일을 업로드하여, 엑셀 파일 내 등록된 회원 정보를 조회하여 전달합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=couponIssuedMbrLoadByExcel">🔗API 확인하기 ></a></td></tr><tr><td>회원 쿠폰 발급</td><td>지정한 회원에게 특정 쿠폰을 발급합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=registCouponIssuedMember">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 기간 변경</td><td>회원이 발급받은 쿠폰 목록 중 특정하여 쿠폰의 유효기간을 변경합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=modifyCouponValiDtm">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 회수</td><td>회원이 발급받은 쿠폰 목록 중 특정하여 쿠폰의 사용여부를 사용완료 처리 합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=withdrawCoupon">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 비용 관리 조회</td><td>입력된 조건을 통해 등록된 쿠폰의 비용 목록을 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponCostList">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 비용 관리 결과수 조회</td><td>입력된 조건을 통해 등록된 쿠폰의 비용 목록 개수를 조회합니다. 조회된 수에 따라 페이징 처리가 됩니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponCostManageListCount">🔗API 확인하기 ></a></td></tr><tr><td>공통코드 조회</td><td>쿠폰 목록 조회 시 조회 조건 중 쿠폰유형의 공통 코드를 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=system&#x26;depth=%EA%B3%B5%ED%86%B5%EC%BD%94%EB%93%9C%20%EC%A1%B0%ED%9A%8C&#x26;path=getStStdCd">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 상세 정보 조회</td><td>등록된 쿠폰의 상세 정보를 조회 합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponData">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 발급회원 조회</td><td>등록한 쿠폰을 발급받은 회원 및 회원의 목록을 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getCouponIssuedMemberList">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 발급회원 수 조회</td><td>등록한 쿠폰을 발급받은 회원의 목록 개수를 조회합니다.</td><td>BO</td><td>GET</td><td><a href="http://api.x2bee.com/content?msa=common&#x26;depth=%EC%95%8C%EB%A6%BC%EB%A9%94%EC%8B%9C%EC%A7%80&#x26;path=sendMessage">🔗API 확인하기 ></a></td></tr><tr><td>회원 쿠폰 일괄발급 조회</td><td>엑셀 파일을 업로드하여, 엑셀 파일 내 등록된 회원 정보를 조회하여 전달합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=couponIssuedMbrLoadByExcel">🔗API 확인하기 ></a></td></tr><tr><td>회원 쿠폰 발급</td><td>지정한 회원에게 특정 쿠폰을 발급합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=registCouponIssuedMember">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 기간 변경</td><td>회원이 발급받은 쿠폰 목록 중 특정하여 쿠폰의 유효기간을 변경합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=modifyCouponValiDtm">🔗API 확인하기 ></a></td></tr><tr><td>쿠폰 회수</td><td>회원이 발급받은 쿠폰 목록 중 특정하여 쿠폰의 사용여부를 사용완료 처리 합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=withdrawCoupon">🔗API 확인하기 ></a></td></tr><tr><td>프로모션 다국어 정보 조회</td><td>할인/마일리지 혜택의 다국어 정보를 조회합니다.</td><td>BO</td><td>GET</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=getMultilingualInfo">🔗API 확인하기 ></a></td></tr><tr><td>프로모션 다국어 등록</td><td>할인/마일리지 혜택의 다국어 정보를 등록합니다.</td><td>BO</td><td>POST</td><td><a href="https://apibo.x2bee.com/content?bo=marketing&#x26;depth=%ED%94%84%EB%A1%9C%EB%AA%A8%EC%85%98%20%EA%B4%80%EB%A6%AC&#x26;path=saveMultilingualInfo">🔗API 확인하기 ></a></td></tr></tbody></table>

## 용어 정의

<table><thead><tr><th width="154">명칭</th><th>설명</th><th data-hidden>비고</th></tr></thead><tbody><tr><td>할인유형(정액)</td><td>상품을 구매할 때 일정 금액이나 금액 범위를 할인해주는 유형의 쿠폰입니다. 이 유형의 쿠폰은 주로 일정 금액을 할인해주거나, 최소 구매 금액을 충족하면 등록 당시 지정한 금액 만큼을 할인해주는 혜택을 제공합니다.</td><td></td></tr><tr><td>할인유형(정률)</td><td>상품 구매 시 해당 상품의 가격에 일정 비율 만큼을 할인해주는 쿠폰입니다. 이 유형의 쿠폰은 상품의 가격에 따라 할인되는 금액이 변동됩니다. 정률 쿠폰은 상품의 가격에 따라 할인되는 금액이 상대적으로 변동하기 때문에 상품의 가격이 높을수록 할인되는 금액도 그에 따라 더 커질 수 있습니다.</td><td></td></tr><tr><td>회원당 발급 횟수</td><td>한 회원이 해당 쿠폰을 발급받을 수 있는 최대 개수를 지정합니다.</td><td></td></tr><tr><td>총 발급 횟수</td><td>해당 쿠폰의 발급 총 개수를 지정합니다. 설정한 수 만큼 선착순 쿠폰 발급 서비스가 가능합니다.</td><td></td></tr><tr><td>발급주체</td><td>고정판촉쿠폰 : 판촉을 위해 고정하여 제공하는 쿠폰입니다. 이벤트 쿠폰 : 특정 이벤트를 위해 생성된 쿠폰입니다. 제휴사 : 특정 제휴사 상품을 위해 생성된 쿠폰입니다. 고객보상쿠폰 : 고객 클레임의 보상을 위해 생성된 쿠폰입니다.</td><td></td></tr></tbody></table>

## 기타 참고사항

* **대상자 지정 발급**: 특정 회원을 대상으로 쿠폰을 자동 발급하는 시스템입니다.
* **조건부 자동 발급**: 일 배치를 통해 설정한 특정 조건에 충족되는 회원에게 쿠폰을 자동으로 발급하는 시스템입니다.
* **고객 다운로드 발급**: 쇼핑몰 페이지 내에서 고객이 직접 발급받는 시스템입니다.
* **분담률**: 쿠폰의 발생 비용을 당사와 협력사와 조율하여 부담하는 시스템 입니다.
* **쿠폰 및 할인 정책**

<table data-full-width="true"><thead><tr><th width="94.6666259765625">구분</th><th width="112.4444580078125">1차 할인</th><th width="307.9998779296875">2차 할인</th><th width="81.333251953125"></th><th width="90.22216796875"></th><th width="394.6666259765625">3차 할인</th><th></th></tr></thead><tbody><tr><td>종류</td><td>판매가할인(단품할인)</td><td>상품할인쿠폰</td><td>임직원할인</td><td>상품즉시할인</td><td>중복할인쿠폰</td><td>장바구니쿠폰</td></tr><tr><td>할인유형</td><td>정액</td><td>정액/정률</td><td>정률</td><td>정률</td><td>정액/정률</td><td>정액/정률</td></tr><tr><td>성격</td><td>상품 등록시 설정</td><td><ul><li>동일 차수 내에서는 다른 할인 유형 선택 불가(동시사용불가) <br>(예 : 2차 상품 쿠폰 + 임직원 할인 사용 불가) </li><li>최대혜택가 계산시 금액이 큰 경우 우선적용 </li><li>금액 동일 시 상품즉시할인->상품할인쿠폰->임직원할인 순으로 적용</li></ul></td><td></td><td></td><td><ul><li>동일 차수 내에서는 다른 할인유형 선택 불가(동시사용불가) </li><li>3차 할인 단독 사용 가능. </li><li>최대혜택가 계산시 금액 큰 경우 우선 적용 </li><li>금액 동일 시 쿠폰유효기간 마감일 순으로 적용</li></ul></td><td></td></tr><tr><td>계산기준금액</td><td>판매가</td><td>1차 할인 적용가</td><td></td><td></td><td>2차 할인 적용가</td><td></td></tr><tr><td>최소 구매 기준</td><td>N/A</td><td>수량 : 1 개 고정 금액 : 상품 1개의 판매가</td><td>N/A</td><td>N/A</td><td>수량 : 1 개 고정 금액 : 상품 1개의 판매가</td><td>수량 : 적용 가능 상품의 합 금액 : 적용 가능 상품의 할인 후 금액의 합(이전차수)</td></tr><tr><td>적용 기준</td><td>상품 판매가 조정</td><td>상품의 모든 수량에 개별 할인 적용</td><td></td><td></td><td></td><td>적용 가능 상품들의 모든 수량에 할인 적용</td></tr><tr><td>마진 체크</td><td>상품 등록시</td><td>“공급가 >= 판매가 - 할인금액” 인 경우에만 쿠폰/할인 노출 및 사용 가능</td><td></td><td></td><td></td><td></td></tr><tr><td>3차할인 적용 가능여부</td><td>N/A</td><td>O</td><td>X</td><td>O</td><td>N/A</td><td>N/A</td></tr><tr><td>공통 적용 사항</td><td>N/A</td><td><ul><li>할인은 1원 단위로 사용이 가능하고, 1원 단위 미만은 반올림 처리를 한다</li><li>주문의 모든 상품이 배송중 되기 전에 클레임 진행 시에만 프로모션 재계산을 진행한다. </li><li>0원 결제 방지를 위해 판매가보다 큰 할인 금액의 쿠폰/할인은 사용이 불가능하다.</li></ul></td><td></td><td></td><td></td><td></td></tr></tbody></table>