상품 목록
손님이 쇼핑몰에서 보는 그대로 카테고리별 상품 목록과 가격을 읽습니다. 회원 토큰이면 등급가, 비회원은 X-Client-Id 로.
업데이트됨 10.14 — 상품 아이콘 API 와 상품의 icon_id 를 열었습니다무엇인가요
손님이 쇼핑몰에서 보는 것과 같은 값 · 같은 규칙으로 상품을 읽습니다. 외부에서 만든 쇼핑몰 화면(헤드리스 스토어프론트) · 회원용 앱이 씁니다. 읽기 전용입니다.
| 누가 보나 | 보내는 것 | 가격 · 노출 |
|---|---|---|
| 회원 토큰 로그인한 회원 | Authorization: Bearer 회원 토큰(me:read) | 그 회원 등급의 할인가 · 회원 전용 상품 · 회원 전용 카테고리가 열립니다 |
| 비회원 | X-Client-Id: ms_… (쇼핑몰이 등록한 앱) | 비회원 등급 가격. 회원 전용은 잠김 |
회원 토큰은 회원 로그인 또는 회원 동의로 받습니다. 둘 다 없으면 401 입니다.
캐시는 응답 헤더를 따르세요
비회원 응답은
Cache-Control: public, max-age=60, stale-while-revalidate=300 입니다 — 모든 비회원에게 같으니 서버 · CDN 에 담아도 됩니다(Next.js 면 ISR · 60초). 회원 응답은 private, no-store 입니다 — 등급마다 가격이 달라 담지 말고 그때그때 부르세요. API 가 이미 캐시에서 읽고 등급가만 얹어 빠릅니다. 오류 응답에는 캐시 헤더가 없습니다.카테고리 상품 목록
GET
https://api.mallstory.kr/v1/store/categories/{slug}/products인증 회원 토큰(me:read) 또는 X-Client-Id
| 쿼리 | 형식 | 설명 |
|---|---|---|
page | number | 쪽 번호(1부터, 기본 1) |
size | number | 쪽당 건수(기본 20, 최대 100) |
sort | string | 차례. 없으면 카테고리에 정한 차례(list_sort) 코드값 |
bash요청
curl 'https://api.mallstory.kr/v1/store/categories/all/products?size=1' \
-H 'X-Client-Id: ms_xxxxxxxxxxxx'json200 OK (비회원)
{
"items": [
{
"product_no": 4,
"name": "펩시",
"promotion_text": "ㅋㅋ",
"image_url": "https://cdn.story.store/storages/2026/09/04/9eb598eb-c575-4bbf-b28d-36a0f6e110f8.jpg",
"badges": [],
"status_type": "OUTOFSTOCK",
"sold_out": true,
"list_price": null,
"sale_price": 5000,
"base_price": 5000,
"final_price": 5000,
"strike_price": null,
"level_discount": 0,
"discount_rate": 0,
"sales_count": 0,
"review_count": 0,
"review_score": 0,
"created_at": "2026-09-04T06:27:41.500Z",
"category_ids": [],
"view_permission": "GUEST",
"view_level": 0,
"locked": false
}
],
"page": 1,
"size": 1,
"total": 40,
"has_more": true,
"sort": "DISPLAY",
"sort_options": [
{
"value": "DISPLAY",
"label": "기본 전시순"
},
{
"value": "CREATED",
"label": "최신 등록순"
},
{
"value": "PRICE_LOW",
"label": "낮은 가격순"
},
{
"value": "PRICE_HIGH",
"label": "높은 가격순"
},
{
"value": "DISCOUNT",
"label": "할인율순"
},
{
"value": "SALES",
"label": "판매량순"
},
{
"value": "REVIEW",
"label": "리뷰 많은순"
},
{
"value": "RATING",
"label": "평점 높은순"
}
],
"list_type": "CARD"
}응답 필드
| 필드 | 형식 | 설명 |
|---|---|---|
items | array | 상품 카드(아래 카드 필드) |
page | number | 지금 쪽 번호 |
size | number | 쪽당 건수 |
total | number | 전체 건수 |
has_more | boolean | 다음 쪽이 있는가 |
sort | string | 적용한 차례 코드값 |
sort_options | array | 정렬 선택지 — value · label |
list_type | string | 카테고리의 목록 모양 코드값 |
카드 필드
| 필드 | 형식 | 설명 |
|---|---|---|
product_no | number | 상품 번호. 상세는 /v1/store/products/{product_no} |
name | string | 상품명 |
promotion_text | string | 간략소개(상품명 위 작은 글자). 없으면 빈 글자 |
image_url | string | null | 대표 이미지 1장. 이미지를 넣지 않은 상품은 null. 나머지 이미지는 상세의 images |
badges | array | 상품명 앞 배지. 한 개에 name · design · shape · text_color · background_color · border_color · image_url |
icon | object | null | 상품 이미지 우측 상단에 얹는 아이콘. name(그림의 대체 글자) · url. 없으면 null |
status_type | string | 판매 상태. 쇼핑몰 화면에는 판매중 · 품절인 상품만 나옵니다 코드값 |
sold_out | boolean | 품절인가(상품 품절 · 재고 0) |
list_price | number | null | 정가. 없으면 null |
sale_price | number | 할인 전 판매가 |
base_price | number | 상품 할인(즉시 · 기간)까지 적용한 값. 등급 할인 전 |
final_price | number | 열람자가 내는 값(등급 할인까지). 화면에 크게 쓰는 값 |
strike_price | number | null | 취소선으로 쓰는 값. 깎인 게 없으면 null |
level_discount | number | 등급으로 더 깎인 금액. 0 이면 등급 혜택이 없음 |
discount_rate | number | 할인율(%). 할인율순 정렬에 쓰는 값 |
sales_count | number | 판매량. 판매량순 정렬에 쓰는 값 |
review_count | number | 리뷰 수. 리뷰 많은순 정렬에 쓰는 값 |
review_score | number | 평점(0~5). 평점 높은순 정렬에 쓰는 값 |
created_at | ISO | 등록 시각. 최신 등록순 정렬에 쓰는 값 |
category_ids | string[] | 걸린 카테고리 키(대표 · 추가 진열) |
view_permission | string | 누가 볼 수 있나 코드값 |
view_level | number | MEMBER 일 때 볼 수 있는 최소 등급 레벨 |
locked | boolean | 이 열람자가 볼 수 없는 상품. 자리만 두고 눌리지 않게 그립니다(상세는 403) |
오류
| 상태 | code | 언제 |
|---|---|---|
| 400 | InvalidParameterValue | sort 가 표에 없는 값 |
| 403 | Forbidden | 회원 전용 카테고리를 볼 수 없는 열람자 |
| 404 | CategoryNotExist | 없는 slug · 숨긴 카테고리 |
| 401 | MissingClient | X-Client-Id 도 회원 토큰도 없음 |
| 401 | InvalidClient | 등록되지 않은 앱 |