[Open API] 포스 쿠폰이 적용된 주문의 조회 범위와 쿠폰 관련 API·웹훅 문의

[asyouplz]

어떤 제품을 사용하나요?

• 제품: Open API
• SDK 또는 API 버전: 현재 공개된 연동 가이드 기준 (연동 개발 전 확인 단계)
• 환경: 개발

무엇이 궁금한가요?

개인 카페 개점을 준비하며, 단일 매장의 주문·결제 데이터를 Open API로 조회하는 프로그램을 개발하고 있습니다.
토스 포스의 쿠폰 기능을 사용할 계획이고, 자체 매출 집계에서 쿠폰 할인을 구분하려고 합니다. 연동 가이드에서 확인하지 못한 아래 내용을 문의드립니다.

1. 쿠폰이 사용된 주문을 주문 조회 API로 조회하면 쿠폰 적용 내역(쿠폰 식별값, 할인 금액, 증정 품목)이 주문의 할인 내역에 포함됩니까? 쿠폰 할인과 일반 할인을 구분할 수 있습니까?
2. 외부 서버에서 쿠폰을 발급하거나 특정 고객에게 지급하는 API가 있습니까?
3. 문서의 '할인' API, '주문 - 혜택 사용 내역 추가(ALPHA)', '주문 - 적립 내역 추가(ALPHA)'는 토스 포스의 쿠폰·포인트 기능과 어떤 관계입니까? 단일 가맹점 앱에서도 사용할 수 있습니까?
4. 쿠폰 발급이나 사용 시점에 수신할 수 있는 웹훅 이벤트가 있습니까?

감사합니다.

[토스플레이스-개발자센터]

안녕하세요. 토스플레이스 개발자센터입니다.

문의주신 내용 확인하여 안내드립니다.

1. 쿠폰이 사용된 주문 조회

포함됩니다. 주문 조회의 할인 내역(Discount)에서 할인명, 할인 종류, 할인 코드, 할인 금액, 적용 우선순위를 확인하실 수 있습니다.

쿠폰 할인과 일반 할인은 할인 내역 안의 couponDetails 필드로 구분하실 수 있습니다. 이 필드에는 쿠폰 제공자, 쿠폰 번호, 쿠폰 잔액이 포함되며 일반 할인에는 포함되지 않습니다.

다만 couponDetails는 ALPHA 단계 필드로 사양이 변경될 수 있습니다. 증정 품목이 어떤 형태로 반영되는지는 문서에 명시되어 있지 않아 확답 드리기 어렵습니다. 1+1이나 상품 증정을 집계에서 구분해야 한다면, 실제 쿠폰을 운영하시기 전에 테스트 가맹점에서 해당 쿠폰을 적용한 주문을 조회해 응답 구조를 먼저 확인해 주시기 바랍니다.

https://docs.tossplace.com/reference/open-api/order/order-model.html

2. 외부 서버에서의 쿠폰 발급

제공하지 않습니다. 외부 서버에서 쿠폰을 발급하거나 특정 고객에게 지급하는 API는 현재 없으며, 제공 계획에 대해서도 예정된 내용이 없어 확답 드리기 어렵습니다.

3. 할인 API와 적립 API의 성격
   '주문 - 혜택 사용 추가(ALPHA)'와 '주문 - 적립 추가(ALPHA)'는 솔루션사가 자체 포인트·쿠폰 사용 내역이나 적립 내역을 주문에 기록하는 쓰기 API입니다. 토스 포스에서 적용된 쿠폰이 이 API로 전달되는 것이 아니라, 외부 시스템의 혜택 내역을 주문에 남기는 용도입니다.

https://docs.tossplace.com/reference/open-api/discount.html
https://docs.tossplace.com/reference/open-api/order/order-accrual-create.html

4. 쿠폰 관련 웹훅

쿠폰 발급이나 사용 시점에 발송되는 웹훅 이벤트는 제공하지 않습니다. 현재 제공하는 이벤트는 주문, 결제, 상품, 가맹점, 앱 설치 범위입니다.

쿠폰이 적용된 주문은 주문 또는 결제 이벤트로 수신하신 뒤 주문 조회의 할인 내역에서 쿠폰 적용 여부를 확인하는 방식으로 구성하실 수 있습니다.

https://docs.tossplace.com/reference/open-api/order/order-events.html

감사합니다.