Mall StoryDevelopers
Mall Story
관리자 API쿠폰 관리소유자 토큰

쿠폰 생성

쿠폰을 만듭니다. 필드는 관리자 쿠폰 만들기 창의 차례입니다 — 종류 · 할인 · 적용 카테고리 · 발급 · 사용 기한.

업데이트됨 10.16 — 쿠폰에 적용 카테고리가 생겼습니다

생성

POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/coupons

권한 promotions:write

요청 본문

필드형식설명
name필수string쿠폰명(50자까지). 손님에게 보입니다
statusstring사용 · 중지. 비우면 active 코드값
coupon_typestring무엇을 깎는가. 비우면 PRODUCT 코드값
discount_typestring금액 · 퍼센트. 비우면 AMOUNT. 배송비 할인은 늘 AMOUNT 코드값
discount_value필수number금액 할인이면 원(1 이상, 최소 주문금액보다 작게), 퍼센트면 1~99
max_discountnumber퍼센트 할인의 최대 할인금액(원). 퍼센트 할인이면 필수, 아니면 0 으로 저장
min_order_amountnumber이 금액 이상일 때만 씀. 0 이면 조건 없음
category_modestring카테고리를 가리는가. 비우면 OFF 코드값
category_idsstring[]ON 일 때 쓸 수 있는 카테고리의 category_unique(1~20개). 고른 카테고리부터 그 하위 전체에 씀 — 하위를 따로 적지 않음. OFF 면 비워 저장. 응답에는 경로 이름(category_names)이 함께 옴
serial_modestring쿠폰번호를 쓰는 방식. 비우면 OFF 코드값
serialstringSAME 일 때 모두가 적는 번호 하나(글자 · 숫자 20자까지). 다른 방식이면 비워 저장
period_typestring사용 기한 방식. 비우면 DAYS 코드값
period_daysnumberDAYS 일 때 발급일부터 며칠(1~999)
start_at · end_atYYYY-MM-DDFIXED 일 때 사용 기간. 시작일 0시부터 종료일 끝(23:59:59)까지
issue_limitnumber모두 몇 장까지 발급. 0 이면 제한 없음. UNIQUE 는 만든 번호 수가 곧 상한이라 0
per_person_limitnumber한 사람이 몇 장까지. 0 이면 제한 없음. UNIQUE 는 0
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/coupons' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"가을맞이 3,000원 할인","coupon_type":"ORDER","discount_type":"AMOUNT","discount_value":3000,"min_order_amount":30000,"period_type":"DAYS","period_days":7,"per_person_limit":1}'
json201 Created
{
  "coupon_unique": "6acdf4194555cab633c38c9c",
  "code": "30e6ddb032cd139b",
  "name": "가을맞이 3,000원 할인",
  "status": "active",
  "coupon_type": "ORDER",
  "discount_type": "AMOUNT",
  "discount_value": 3000,
  "max_discount": 0,
  "min_order_amount": 30000,
  "serial_mode": "OFF",
  "serial": "",
  "serial_count": 0,
  "serial_used_count": 0,
  "period_type": "DAYS",
  "period_days": 7,
  "start_at": "",
  "end_at": "",
  "issue_limit": 0,
  "per_person_limit": 1,
  "issued_count": 0,
  "used_count": 0,
  "created": "2026-10-13T09:04:25.599Z",
  "register_url": "https://testmall.xyz/coupon/register/30e6ddb032cd139b"
}

3만 원 이상 주문에서 3,000원을 깎고, 받은 날부터 7일 쓰는 쿠폰입니다. 응답에는 category_mode · category_ids · category_names 도 옵니다(이 예시는 OFF · 빈 배열).

json요청 — 카카오 채널용 다른번호 발급 쿠폰(10%, 최대 5,000원, 11월 한 달)
{
  "name": "카카오 채널 친구 쿠폰",
  "coupon_type": "PRODUCT",
  "discount_type": "PERCENT",
  "discount_value": 10,
  "max_discount": 5000,
  "serial_mode": "UNIQUE",
  "period_type": "FIXED",
  "start_at": "2026-11-01",
  "end_at": "2026-11-30"
}
json요청 — 적용 카테고리를 둔 쿠폰(고른 카테고리와 그 하위 전체)
{
  "name": "의류 5,000원 할인",
  "coupon_type": "ORDER",
  "discount_type": "AMOUNT",
  "discount_value": 5000,
  "min_order_amount": 30000,
  "period_type": "DAYS",
  "period_days": 7,
  "per_person_limit": 1,
  "category_mode": "ON",
  "category_ids": [
    "6acdf41b4555cab633c38caa"
  ]
}
json400 — 목록에 없는 status
{
  "code": "InvalidParameterValue",
  "message": "status 는 active · stop 중 하나입니다.",
  "request_id": "req_9f5a902601ab49c5a80bcca5989dfffb"
}
json400 — 퍼센트 할인에 최대 할인금액이 없음
{
  "code": "InvalidParameterValue",
  "message": "최대 할인금액을 입력하세요.",
  "request_id": "req_c2534236253641b3946d3db3ed518e75"
}

오류

상태code언제
400InvalidParameterValue필수값 없음 · 목록에 없는 값 · 금액 · 기간 · 카테고리 규칙 위반(관리자 쿠폰 만들기 창과 같은 문장)
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 promotions:write 가 없음