본문으로 건너뛰기

쿠폰 카탈로그

쿠폰 카탈로그는 고객사가 현재 발급하거나 발송할 수 있는 쿠폰 상품의 목록입니다. 쿠폰을 발급하기 전에 카탈로그를 먼저 조회하여, 어떤 상품을 어떤 방식으로 이용할 수 있는지 확인합니다.

capabilities — 발급 방식​

카탈로그의 각 쿠폰에는 capabilities 필드가 있습니다. 이 필드는 해당 쿠폰을 어떤 방식으로 발급할 수 있는지를 나타냅니다.

capability설명사용 시나리오
SEND수신자의 휴대폰으로 MMS를 발송합니다.이벤트 당첨자에게 쿠폰을 직접 전달할 때
PINPIN 코드를 발급받아 고객사가 직접 전달합니다.자체 앱/웹에서 PIN을 노출하거나, 이메일로 전달할 때

하나의 쿠폰이 두 가지 방식을 모두 지원할 수도 있고, 하나만 지원할 수도 있습니다.

// SEND와 PIN 모두 가능
{ "capabilities": ["SEND", "PIN"] }

// MMS 발송만 가능
{ "capabilities": ["SEND"] }

// PIN 발급만 가능
{ "capabilities": ["PIN"] }
어떤 방식을 선택할까?
  • MMS 발송(SEND): 수신자의 전화번호만 알면 됩니다. 별도 UI 구현 없이 쿠폰을 전달할 수 있어 가장 간편합니다.
  • PIN 발급(PIN): 전달 방식을 고객사가 직접 제어합니다. 자체 앱 화면에 바코드를 노출하거나, 이메일/카카오톡 등 원하는 채널로 전달할 수 있습니다.

notice — 안내사항​

카탈로그의 notice 필드에는 해당 쿠폰의 유의사항이 담겨 있습니다. 사용 가능 매장, 이용 조건 등 최종 수신자에게 전달이 필요한 정보입니다.

{
  "name": "스타벅스 아메리카노 T",
  "notice": "유효기간 내 사용 가능하며, 일부 매장에서는 사용이 제한될 수 있습니다."
}

발급 방식에 따라 notice의 처리가 다릅니다.

방식notice 처리
MMS 발송 (SEND)MMS에 자동으로 포함됩니다. 고객사가 별도로 처리할 필요 없습니다.
PIN 발급 (PIN)고객사가 PIN을 노출하는 화면에 직접 표시해야 합니다.
PIN 발급 시 notice를 반드시 표시하세요

PIN 방식에서는 notice가 자동으로 전달되지 않습니다. 자체 앱/웹 화면에 PIN을 노출할 때 notice 내용을 함께 표시하여 수신자가 이용 조건을 확인할 수 있도록 해주세요.

쿠폰 유형​

카탈로그의 각 쿠폰은 type 필드로 유형이 구분됩니다.

유형설명예시
EXCHANGE특정 상품과 교환할 수 있는 쿠폰스타벅스 아메리카노 T
VOUCHER금액권으로, 해당 금액만큼 사용할 수 있는 쿠폰배달의민족 1만원권

messageConstraint — 메시지 제약조건​

MMS 발송(SEND)을 지원하는 쿠폰에는 messageConstraint 필드가 포함됩니다. 발송 시 작성하는 메시지의 제목과 본문에 길이 제한이 있으며, 쿠폰마다 제한 기준이 다릅니다.

{
  "messageConstraint": {
    "limitType": "BYTE",
    "encoding": "EUC-KR",
    "titleSupported": true,
    "titleLimit": 40,
    "contentLimit": 2000
  }
}
  • limitType: 길이를 글자 수(LENGTH)로 제한하는지, 바이트(BYTE)로 제한하는지를 나타냅니다.
  • encoding: BYTE 방식일 때 바이트 계산에 사용하는 인코딩입니다. EUC-KR에서는 한글 한 글자가 2바이트, UTF-8에서는 3바이트로 계산됩니다.
  • titleSupported: 메시지 제목 사용 가능 여부입니다. false이면 제목 없이 본문만 발송할 수 있습니다.
  • titleLimit / contentLimit: 제목과 본문의 최대 길이(또는 바이트)입니다.

SEND capability가 없는 쿠폰에는 messageConstraint가 null입니다.