회원 API회원 토큰

쇼핑몰 카테고리

손님이 쇼핑몰에서 보는 그대로 진열 중인 카테고리를 읽습니다. 회원 전용 카테고리는 잠김으로 표시됩니다.

무엇인가요

손님이 쇼핑몰에서 보는 카테고리를 읽습니다. 숨긴 카테고리는 나오지 않습니다. 읽기 전용입니다 — 카테고리를 만들고 고치는 것은 관리자 API 의 상품 카테고리입니다.

누가 보나	보내는 것	가격 · 노출
회원 토큰 로그인한 회원	`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 가 이미 캐시에서 읽고 등급가만 얹어 빠릅니다. 오류 응답에는 캐시 헤더가 없습니다.

카테고리 목록

GEThttps://api.mallstory.kr/v1/store/categories

인증 회원 토큰(me:read) 또는 X-Client-Id

bash요청

curl 'https://api.mallstory.kr/v1/store/categories' \
  -H 'X-Client-Id: ms_xxxxxxxxxxxx'

json200 OK (줄임)

{
  "items": [
    {
      "category_unique": "6aab71c3dd8941ed187ffe56",
      "name": "전체 카테고리",
      "slug": "all",
      "parent_id": null,
      "depth": 0,
      "sort_order": 0,
      "is_all": true,
      "list_type": "CARD",
      "list_sort": "DISPLAY",
      "locked": false
    },
    {
      "category_unique": "6aab6a9ddd8941ed187ffe4b",
      "name": "의류",
      "slug": "f2vikewf",
      "parent_id": null,
      "depth": 0,
      "sort_order": 2,
      "is_all": false,
      "list_type": "GALLERY",
      "list_sort": "PRICE_HIGH",
      "locked": false
    },
    {
      "category_unique": "6aab6ae6dd8941ed187ffe4d",
      "name": "푸드",
      "slug": "v7ikr1go",
      "parent_id": null,
      "depth": 0,
      "sort_order": 3,
      "is_all": false,
      "list_type": "CARD",
      "list_sort": "DISPLAY",
      "locked": false
    }
  ]
}

응답 필드

필드	형식	설명
`category_unique`	string	카테고리 키. 상품의 category_ids 에 들어 있는 값
`name`	string	카테고리 이름
`slug`	string	상품 목록을 부를 때 쓰는 값 → 상품 목록. 전체 카테고리는 `all`
`parent_id`	string \| null	상위 카테고리 키. 대분류는 null
`depth`	number	단계(0 대분류 ~ 3 세분류)
`sort_order`	number	형제 카테고리 사이의 차례
`is_all`	boolean	전체 카테고리인가
`list_type`	string	상품 목록 모양 코드값
`list_sort`	string	상품 목록의 기본 차례 코드값
`locked`	boolean	이 열람자가 볼 수 없는 카테고리(회원 전용 · 등급 미달). 상품 목록을 부르면 403

json401 — 인증 없이 부름

{
  "code": "MissingClient",
  "message": "X-Client-Id 헤더(쇼핑몰이 등록한 앱의 Client ID) 또는 회원 토큰(Authorization: Bearer)이 필요합니다."
}

오류

상태	code	언제
401	`MissingClient`	X-Client-Id 도 회원 토큰도 없음
401	`InvalidClient`	등록되지 않은 앱

카테고리 상세

GEThttps://api.mallstory.kr/v1/store/categories/{slug}

인증 회원 토큰(me:read) 또는 X-Client-Id

쇼핑몰 카테고리 화면의 머리입니다 — 상단 문구 · 배너 · 동영상, 판매자가 고른 추천 상품, 목록 모양 · 정렬 선택지, 바로 아래 하위 카테고리. 상품 목록은 상품 목록으로 따로 읽습니다.

bash요청

curl 'https://api.mallstory.kr/v1/store/categories/f2vikewf' \
  -H 'X-Client-Id: ms_xxxxxxxxxxxx'

json200 OK

{
  "category_unique": "6aab6a9ddd8941ed187ffe4b",
  "name": "의류",
  "slug": "f2vikewf",
  "parent_id": null,
  "depth": 0,
  "is_all": false,
  "list_type": "GALLERY",
  "list_sort": "PRICE_HIGH",
  "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": "평점 높은순"
    }
  ],
  "top": {
    "text": {
      "enabled": false,
      "title": "",
      "description": "",
      "text_color": "#000000",
      "background_color": "",
      "size": "MEDIUM",
      "position": "CENTER_MIDDLE"
    },
    "banner": {
      "enabled": true,
      "mobile_url": null,
      "pc_url": "https://cdn.story.store/storages/2026/09/21/97974105-9a2a-4ac8-a38b-10100f0eec6d.jpg",
      "background_color": "",
      "combine": "SPLIT",
      "link_kind": "URL",
      "link_value": "",
      "link_target": "SELF"
    },
    "video": {
      "enabled": false,
      "url": "",
      "ratio": "AUTO",
      "autoplay": false
    }
  },
  "recommend": {
    "enabled": true,
    "title": "",
    "items": [
      {
        "product_no": 46,
        "name": "바나나",
        "promotion_text": "",
        "image_url": "https://cdn.story.store/storages/2026/09/21/90689207-069a-4444-b50c-4f041327becd.jpg",
        "badges": [],
        "status_type": "SALE",
        "sold_out": false,
        "list_price": 100000,
        "sale_price": 10000,
        "base_price": 1000,
        "final_price": 1000,
        "strike_price": 100000,
        "level_discount": 0,
        "discount_rate": 99,
        "sales_count": 0,
        "review_count": 0,
        "review_score": 0,
        "created_at": "2026-09-21T01:58:50.822Z",
        "category_ids": [
          "6aab6ae6dd8941ed187ffe4d",
          "6aab6ae3dd8941ed187ffe4c",
          "6aab6b3ddd8941ed187ffe51",
          "6aab6aeadd8941ed187ffe4e"
        ],
        "view_permission": "GUEST",
        "view_level": 0,
        "locked": false
      },
      {
        "product_no": 39,
        "name": "롱폼 동영상 + 이미지",
        "promotion_text": "",
        "image_url": "https://cdn.story.store/storages/2026/09/18/02180621-5d1c-4a04-8508-8925a86880af.jpg",
        "badges": [],
        "status_type": "OUTOFSTOCK",
        "sold_out": true,
        "list_price": null,
        "sale_price": 10000,
        "base_price": 10000,
        "final_price": 10000,
        "strike_price": null,
        "level_discount": 0,
        "discount_rate": 0,
        "sales_count": 0,
        "review_count": 0,
        "review_score": 0,
        "created_at": "2026-09-18T02:10:48.103Z",
        "category_ids": [
          "6aab6aeadd8941ed187ffe4e"
        ],
        "view_permission": "GUEST",
        "view_level": 0,
        "locked": false
      },
      {
        "product_no": 13,
        "name": "고액 상품",
        "promotion_text": "",
        "image_url": "https://cdn.story.store/storages/2026/09/09/952143a2-0a15-4366-996d-82ea222d442f.jpg",
        "badges": [],
        "status_type": "OUTOFSTOCK",
        "sold_out": true,
        "list_price": null,
        "sale_price": 100000,
        "base_price": 100000,
        "final_price": 100000,
        "strike_price": null,
        "level_discount": 0,
        "discount_rate": 0,
        "sales_count": 0,
        "review_count": 0,
        "review_score": 0,
        "created_at": "2026-09-09T08:42:16.674Z",
        "category_ids": [],
        "view_permission": "GUEST",
        "view_level": 0,
        "locked": false
      },
      {
        "product_no": 11,
        "name": "3차 옵션 테스트",
        "promotion_text": "",
        "image_url": "https://cdn.story.store/storages/2026/09/08/a675eac7-3414-414e-bdc1-be15bdd3d7e5.jpg",
        "badges": [],
        "status_type": "SALE",
        "sold_out": false,
        "list_price": null,
        "sale_price": 10000,
        "base_price": 10000,
        "final_price": 10000,
        "strike_price": null,
        "level_discount": 0,
        "discount_rate": 0,
        "sales_count": 0,
        "review_count": 0,
        "review_score": 0,
        "created_at": "2026-09-08T06:44:44.531Z",
        "category_ids": [],
        "view_permission": "GUEST",
        "view_level": 0,
        "locked": false
      },
      {
        "product_no": 10,
        "name": "바나나맛 우유",
        "promotion_text": "",
        "image_url": "https://cdn.story.store/storages/2026/09/08/94d89e68-b7a2-4461-9ea9-b8500c7512a3.png",
        "badges": [
          {
            "name": "당일배송",
            "design": "SIMPLE",
            "shape": "TYPE3",
            "text_color": "#FFFFFF",
            "background_color": "#00C247",
            "border_color": "#D0FF00",
            "image_url": null
          }
        ],
        "status_type": "SALE",
        "sold_out": false,
        "list_price": null,
        "sale_price": 1000,
        "base_price": 900,
        "final_price": 900,
        "strike_price": 1000,
        "level_discount": 0,
        "discount_rate": 10,
        "sales_count": 0,
        "review_count": 0,
        "review_score": 0,
        "created_at": "2026-09-08T06:03:55.543Z",
        "category_ids": [],
        "view_permission": "GUEST",
        "view_level": 0,
        "locked": false
      },
      {
        "product_no": 7,
        "name": "펩시 제로",
        "promotion_text": "",
        "image_url": "https://cdn.story.store/storages/2026/09/08/95d878ce-a671-4791-a8bc-843644dfc4c0.jpg",
        "badges": [],
        "status_type": "SALE",
        "sold_out": false,
        "list_price": null,
        "sale_price": 2000,
        "base_price": 2000,
        "final_price": 2000,
        "strike_price": null,
        "level_discount": 0,
        "discount_rate": 0,
        "sales_count": 0,
        "review_count": 0,
        "review_score": 0,
        "created_at": "2026-09-08T05:29:57.898Z",
        "category_ids": [],
        "view_permission": "GUEST",
        "view_level": 0,
        "locked": false
      }
    ]
  },
  "children": [
    {
      "category_unique": "6aab6b2ddd8941ed187ffe4f",
      "name": "여성의류",
      "slug": "7rzcdbr8",
      "locked": false
    },
    {
      "category_unique": "6aab6b32dd8941ed187ffe50",
      "name": "남성의류",
      "slug": "csznj2io",
      "locked": false
    },
    {
      "category_unique": "6aaba65f772eafd22bc322f0",
      "name": "남여공용",
      "slug": "odealf5u",
      "locked": false
    }
  ]
}

응답 필드

필드	형식	설명
`category_unique`	string	카테고리 키
`name`	string	카테고리 이름
`slug`	string	상품 목록을 부를 때 쓰는 값
`parent_id`	string \| null	상위 카테고리 키
`depth`	number	단계
`is_all`	boolean	전체 카테고리인가
`list_type`	string	상품 목록 모양 코드값
`list_sort`	string	상품 목록의 기본 차례 코드값
`sort_options`	array	정렬 선택지 — `value` · `label`
`top.text`	object	상단 문구 — `enabled` · `title` · `description` · `text_color` · `background_color` · `size` · `position`
`top.banner`	object	상단 배너 — `enabled` · `pc_url` · `mobile_url`(없으면 null) · `background_color` · `combine` · `link_kind` · `link_value` · `link_target`
`top.video`	object	상단 동영상 — `enabled` · `url` · `ratio` · `autoplay`
`recommend.enabled`	boolean	추천 상품을 보이는가
`recommend.title`	string	추천 상품 제목
`recommend.items`	array	추천 상품(판매자가 고른 차례, 상품 목록의 카드와 같은 모양, 열람자 기준 가격)
`children[].category_unique`	string	바로 아래 하위 카테고리 키
`children[].name`	string	하위 카테고리 이름
`children[].slug`	string	하위 카테고리 slug
`children[].locked`	boolean	이 열람자가 볼 수 없는가

오류

상태	code	언제
403	`Forbidden`	회원 전용 카테고리를 볼 수 없는 열람자
404	`CategoryNotExist`	없는 slug · 숨긴 카테고리
401	`MissingClient`	X-Client-Id 도 회원 토큰도 없음
401	`InvalidClient`	등록되지 않은 앱

무엇인가요#

카테고리 목록#

응답 필드

오류

카테고리 상세#

응답 필드

오류

무엇인가요

카테고리 목록

카테고리 상세