쿠폰 목록 · 상세
지우지 않은 쿠폰을 최신순으로 읽고, 쿠폰 하나를 등록 주소와 함께 읽습니다.
목록
GET
https://api.mallstory.kr/v1/shop/{shop_unique}/coupons권한 promotions:read
지우지 않은 쿠폰을 만든 날 최신순으로 모두 줍니다(관리자 목록과 같은 차례).
| 쿼리 | 형식 | 설명 |
|---|---|---|
status | string | 사용 · 중지만 거름 코드값 |
bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/coupons?status=stop' \
-H 'Authorization: Bearer msat_8Hk2wQ7...'json200 OK
{
"items": [
{
"coupon_unique": "6acdf4194555cab633c38c9c",
"code": "30e6ddb032cd139b",
"name": "가을맞이 3,000원 할인",
"status": "stop",
"coupon_type": "ORDER",
"discount_type": "AMOUNT",
"discount_value": 5000,
"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"
}
]
}응답 필드
| 필드 | 형식 | 설명 |
|---|---|---|
coupon_unique | string | 쿠폰 키 |
code | string | 등록 주소에 쓰는 공개 코드. 만들 때 정해지고 바뀌지 않음 |
register_url | string | 손님이 쿠폰을 받는 주소 |
name | string | 쿠폰명(50자까지). 손님에게 보입니다 |
status | string | 사용 · 중지. 비우면 active 코드값 |
coupon_type | string | 무엇을 깎는가. 비우면 PRODUCT 코드값 |
discount_type | string | 금액 · 퍼센트. 비우면 AMOUNT. 배송비 할인은 늘 AMOUNT 코드값 |
discount_value | number | 금액 할인이면 원(1 이상, 최소 주문금액보다 작게), 퍼센트면 1~99 |
max_discount | number | 퍼센트 할인의 최대 할인금액(원). 퍼센트 할인이면 필수, 아니면 0 으로 저장 |
min_order_amount | number | 이 금액 이상일 때만 씀. 0 이면 조건 없음 |
category_mode | string | 카테고리를 가리는가. 비우면 OFF 코드값 |
category_ids | string[] | ON 일 때 쓸 수 있는 카테고리의 category_unique(1~20개). 고른 카테고리부터 그 하위 전체에 씀 — 하위를 따로 적지 않음. OFF 면 비워 저장. 응답에는 경로 이름(category_names)이 함께 옴 |
serial_mode | string | 쿠폰번호를 쓰는 방식. 비우면 OFF 코드값 |
serial | string | SAME 일 때 모두가 적는 번호 하나(글자 · 숫자 20자까지). 다른 방식이면 비워 저장 |
period_type | string | 사용 기한 방식. 비우면 DAYS 코드값 |
period_days | number | DAYS 일 때 발급일부터 며칠(1~999) |
start_at · end_at | YYYY-MM-DD | FIXED 일 때 사용 기간. 시작일 0시부터 종료일 끝(23:59:59)까지 |
issue_limit | number | 모두 몇 장까지 발급. 0 이면 제한 없음. UNIQUE 는 만든 번호 수가 곧 상한이라 0 |
per_person_limit | number | 한 사람이 몇 장까지. 0 이면 제한 없음. UNIQUE 는 0 |
category_names | string[] | category_ids 의 경로 이름("의류 > 여성의류"). 지워진 카테고리는 빠짐 |
serial_count · serial_used_count | number | UNIQUE 쿠폰의 만든 번호 수 · 그중 쓰인 수 |
issued_count · used_count | number | 지금까지 발급된 장 수 · 사용된 장 수 |
created | ISO | 만든 시각 |
오류
| 상태 | code | 언제 |
|---|---|---|
| 401 | MissingLoginSession | Authorization 헤더에 Bearer 토큰이 없음 |
| 401 | InvalidAccessToken | 토큰이 틀리거나 만료 · 폐기됨 |
| 403 | InsufficientScope | 토큰에 promotions:read 가 없음 |
상세
GET
https://api.mallstory.kr/v1/shop/{shop_unique}/coupons/{coupon_unique}권한 promotions:read
목록 한 줄과 같은 모양입니다.
bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/coupons/6acdf4194555cab633c38c9c' \
-H 'Authorization: Bearer msat_8Hk2wQ7...'json200 OK
{
"coupon_unique": "6acdf4194555cab633c38c9c",
"code": "30e6ddb032cd139b",
"name": "가을맞이 3,000원 할인",
"status": "stop",
"coupon_type": "ORDER",
"discount_type": "AMOUNT",
"discount_value": 5000,
"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"
}오류
| 상태 | code | 언제 |
|---|---|---|
| 404 | CouponNotExist | 없는 키이거나 지운 쿠폰 |
| 401 | MissingLoginSession | Authorization 헤더에 Bearer 토큰이 없음 |
| 401 | InvalidAccessToken | 토큰이 틀리거나 만료 · 폐기됨 |
| 403 | InsufficientScope | 토큰에 promotions:read 가 없음 |