쿠폰 수정 API (v2)

쿠폰 수정 API는 이미 발급된 쿠폰의 정보를 변경하는 기능을 제공합니다.

쿠폰 번호(cpNo)를 기준으로 할인 방식, 유효기간, 사용 횟수, 그룹, 사용자 정보 등을 수정할 수 있습니다.
단, 이미 사용된 쿠폰은 일부 항목을 변경할 수 없습니다.

이 API는 퍼스널 요금제 이상에서만 사용할 수 있습니다.

API Version

PUT

/api/coupon/v2/update

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "nm": "$10 discount coupon",
    "disc": 10,
    "endYmd": "2025-12-31",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

cpnNo string required: 쿠폰 번호.
domain string: 쿠폰 도메인.
프리미엄 요금제 이상에서는, 커스텀 도메인을 지정할 수 있습니다.
webhookEnableYn string
Enum: YN: Webhook 사용 여부. 전역 Webhook이 활성화되어 있어야 합니다.
이 기능은 엔터프라이즈 요금제에서만 제공됩니다.
nm string: 쿠폰 이름.
discTypeIdx integer
Default:457
Enum: 457458: 할인 유형. (457:요율 할인 %, 458:금액 할인)
disc double
Default:0: 할인율(457)은 1~100% 범위, 할인금액(458)은 금액 입력
discCurrency string
Default:KRW
Enum: KRWCADCNYEURGBPIDRJPYMURRUBSGDUSD: 화폐 단위. 금액 할인(discTypeIdx:458) 사용시 필수.
strtYmd date: 쿠폰 유효 시작일. 예: 2024-10-01
endYmd date: 쿠폰 유효 만료일. 예: 2024-12-31
만료일은 다음 해 12월 31일까지만 설정할 수 있습니다.
useLimit integer
Default:1
Enum: 012345: 쿠폰 사용 가능 횟수. (0:무제한, 1~5: 횟수 제한)
2회 이상 지정시 userId 값은 반드시 지정해야 합니다.
grpIdx integer
Default:0: 쿠폰 그룹. 쿠폰을 그룹으로 관리할 때 사용. 그룹IDX는 대시보드의 쿠폰 그룹 관리에서 확인 가능.
그룹 설정과 쿠폰 설정이 중복될 경우 그룹 설정이 우선순위를 갖습니다.
tmplIdx integer
Default:0: 쿠폰 템플릿. 쿠폰 생성 시 참조할 템플릿. 템플릿IDX는 대시보드의 쿠폰 템플릿 관리에서 확인 가능.
onsiteYn string
Default:N
Enum: YN: 현장쿠폰 여부. 쿠폰 페이지에 “쿠폰 사용” 버튼 표시 여부.
오프라인 매장에서 직원이 쿠폰 사용 시 필요.
onsitePwd string: 현장쿠폰 비밀번호. 쿠폰 사용 시 필요한 비밀번호.
memo string: 내부 참고용 메모.
url string: URL 입력 시 쿠폰 페이지에 “쿠폰 사용하러 가기” 버튼이 표시됩니다.
버튼 또는 쿠폰 이미지 클릭 시 해당 URL로 리디렉션.
color string: 쿠폰 글자 색상. HEX 값 입력. 예: #4F4F4F
background string: 쿠폰 배경 색상. HEX 값 입력. 예: #FFFFFF
userId string: 쿠폰 발급 대상자를 관리하는 데 사용됩니다.
쿠폰 사용 가능 횟수가 2~5로 설정된 경우 반드시 입력해야 하며, 일반적으로 웹사이트 회원의 로그인 ID 또는 영문 이름을 입력합니다.
userNm string: 쿠폰 사용자 이름. 내부 관리용.
userPhnno string: 쿠폰 사용자 연락처. 내부 관리용.
userEml string: 쿠폰 사용자 이메일. 내부 관리용.
userEtc1 string: 추가 내부 관리용 필드.
userEtc2 string: 추가 내부 관리용 필드.
branchIdx integer: 발행 지점 IDX. 보내지 않으면 본사 발행이며, 0을 보내면 본사로 비웁니다.
비즈니스 요금제 이상에서만 사용할 수 있습니다.
storeIdx integer: 발행 매장 IDX. 지정하면 그 매장이 속한 지점이 발행 지점이 됩니다. 다른 지점을 함께 보내면 오류입니다.
useScope string: 사용 가능 범위. ALL(모든 매장) 또는 BRANCH(특정 지점)만 허용됩니다. 보내지 않으면 ALL입니다.
useBranchIdx integer: 사용 가능 지점 IDX. useScope = BRANCH일 때만 필요하며, ALL이면 항상 비어 있습니다.

{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer: 응답 코드: 0 = 성공, 그 외 값 = 오류
message string: 응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
result null

발행 지점·매장과 사용 가능 범위

여기서 지정하는 값은 발행 시점에 저장되는 정책입니다. "어디에서 발행됐는가"(발행 지점·발행 매장)와 "고객이 어디에서 쓸 수 있는가"(사용 가능 범위·사용 가능 지점)는 서로 다른 개념이므로 파라미터도 나뉘어 있습니다.

파라미터	의미	설명
`branchIdx`	발행 지점	보내지 않으면 본사 발행입니다. `0`을 보내면 본사로 비웁니다.
`storeIdx`	발행 매장	지정하면 그 매장이 속한 지점이 발행 지점이 됩니다. 다른 지점을 함께 보내면 거부됩니다.
`useScope`	사용 가능 범위	`ALL`(모든 매장) 또는 `BRANCH`(특정 지점). 보내지 않으면 `ALL`입니다.
`useBranchIdx`	사용 가능 지점	`useScope=BRANCH`일 때만 필요합니다. `ALL`이면 항상 비어 있습니다.

사용할 수 없는 파라미터 — processStoreIdx(처리 매장)는 검증·사용·적립·차감이 실제로 일어난 매장을 가리키는 값이라 이 API에서는 쓸 수 없습니다. 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

지점·매장 기능은 비즈니스 요금제 이상에서만 사용할 수 있습니다.

Idempotency-Key

네트워크 오류로 응답을 받지 못했을 때 안전하게 재시도하려면 Idempotency-Key 헤더에 요청마다 고유한 값을 담아 보냅니다. 본문의 requestId로도 보낼 수 있으며, 둘 다 보내고 값이 다르면 거부됩니다. 허용 형식은 영문·숫자와 . _ : - 를 조합한 8~64자입니다.

같은 key로 같은 요청을 다시 보내면 다시 처리하지 않고 최초 결과를 그대로 돌려줍니다. 중복으로 처리되지 않으며 웹훅도 다시 발송되지 않습니다.

같은 key는 같은 논리 작업의 재시도에만 사용하세요. 서로 다른 작업에는 반드시 새 key를 사용해야 합니다. 같은 key를 다른 요청 내용이나 다른 작업에 사용하면 409로 거부될 수 있습니다.

언제 이 API를 사용하나요?

이미 발급된 쿠폰의 조건을 변경해야 할 때 사용합니다.

이벤트 기간 연장, 할인율 조정, 특정 사용자 제한 추가 등 운영 중인 캠페인을 수정할 때 활용됩니다.

쿠폰을 새로 발급하는 것이 아니라 기존 쿠폰 번호를 유지한 채 내용만 업데이트하므로, 이미 배포된 쿠폰을 회수하지 않고도 조건을 변경할 수 있습니다.

유효기간 연장 방법

endYmd 파라미터에 새 종료일을 입력하면 유효기간을 연장할 수 있습니다.
이미 만료된 쿠폰도 종료일을 미래 날짜로 변경하면 다시 사용 가능한 상태로 복구됩니다. 날짜 형식은 YYYY-MM-DD를 사용합니다.

활용 예시

프로모션 기간 연장: 종료 예정인 캠페인의 endYmd를 수정해 유효기간을 연장
할인율 조정: 마케팅 전략 변경 시 disc 값을 수정해 할인 조건을 업데이트
사용 횟수 추가 부여: VIP 고객에게 useLimit을 높여 동일 쿠폰을 반복 사용할 수 있도록 혜택을 확대
오프라인 매장 쿠폰: grpIdx를 변경해 쿠폰을 다른 그룹으로 이동시키고, 새 그룹의 이미지와 웹훅 설정을 적용
그룹 재배정: 이메일 또는 사용자 ID 기반으로 맞춤형 할인 제공
랜딩 페이지 변경: 쿠폰 적용 URL을 다른 프로모션 페이지로 수정

사용 시 주의사항

cpNo(쿠폰 번호)가 유효하지 않으면 수정이 실패합니다.
이미 사용된 쿠폰은 일부 항목 변경이 제한될 수 있습니다.
할인 값 변경 시 기존 사용자 경험에 영향을 줄 수 있습니다.
만료된 쿠폰은 수정 후에도 즉시 사용되지 않을 수 있습니다.
현장 쿠폰 비밀번호는 직원이 퇴시할 때 반드시 변경하는 것을 권장합니다.