관리자 API상품 관리소유자 토큰

상품 상세

상품 하나를 옵션과 함께 읽습니다. 원가는 여기에만 있습니다.

업데이트됨 10.26 — 직접 입력 옵션에서 템플릿 색상 · 사이즈 자리를 1 · 2 · 3차 어디든 둘 수 있습니다

요청

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/products/{product_unique}

bash요청

curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/products/6accaa68c2ca90eedea62100' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

응답

응답은 {product, options} 입니다. 아래는 옵션 세 개(색상 × 사이즈)짜리 상품입니다 — 재고 stock_quantity 가 옵션 재고의 합(10 + 5 + 0)입니다.

json200 OK

{
  "product": {
    "product_no": 50,
    "status_type": "SALE",
    "sale_type": "NEW",
    "display_order": 0,
    "view_permission": "GUEST",
    "view_level": 0,
    "benefit_limit": {
      "coupon": false,
      "level_discount": false,
      "point": false
    },
    "order_limit": {
      "enabled": false,
      "basis": "EACH",
      "min": 0,
      "max": 0,
      "max_check": "ORDER"
    },
    "adult_only": false,
    "restock_alert_excluded": false,
    "order_permission": "GUEST",
    "order_level": 0,
    "brand": "",
    "supplier": "",
    "management_code": "SH-LN-001",
    "search_keywords": [
      "셔츠",
      "린넨"
    ],
    "seo": {
      "mode": "AUTO",
      "page_title": "",
      "meta_description": "",
      "target_keywords": ""
    },
    "name": "린넨 셔츠",
    "promotion_text": "봄 신상 10% 할인",
    "sale_price": 39000,
    "list_price": 49000,
    "cost_price": 18000,
    "tax_type": "TAX",
    "stock_quantity": 15,
    "stock_unlimited": false,
    "custom_options": [],
    "extra_options": [],
    "video_url": "",
    "shippable": true,
    "bundle_shipping": "POSSIBLE",
    "collect_clearance_code": false,
    "discount": {
      "immediate": {
        "enabled": false,
        "value": 0,
        "unit": "WON"
      },
      "period": {
        "enabled": false,
        "value": 0,
        "unit": "WON",
        "start_at": null,
        "end_at": null
      },
      "bulk": {
        "enabled": false,
        "rules": []
      }
    },
    "reward": {
      "enabled": false,
      "value": 0,
      "unit": "WON",
      "basis": "SALE_PRICE"
    },
    "source": {
      "type": "SELF",
      "external_code": null,
      "imported_at": null
    },
    "created": "2026-10-12T09:37:44.797Z",
    "updated": "2026-10-12T09:37:44.797Z",
    "deleted": null,
    "color_ids": [],
    "size_template_id": null,
    "sizes": [],
    "review_template_id": null,
    "option_info": {
      "names": [
        "색상",
        "사이즈"
      ],
      "pick_types": [
        "SELECT",
        "SELECT"
      ],
      "manage_fields": [
        "price",
        "stockQuantity",
        "usable"
      ],
      "generation": "DIRECT",
      "size_template_id": null
    },
    "display_status": "DISPLAY",
    "display_start_at": null,
    "display_end_at": null,
    "badge_ids": [],
    "sale_start_at": null,
    "sale_end_at": null,
    "detail_content_body": "<p>통기성이 좋은 린넨 100% 셔츠입니다.</p>",
    "images": [],
    "product_info_provided_notice": null,
    "product_unique": "6accaa68c2ca90eedea62100",
    "category_id": "6aab6a9ddd8941ed187ffe4b",
    "display_category_ids": [],
    "top_template_ids": [],
    "bottom_template_ids": [],
    "delivery": []
  },
  "options": [
    {
      "option_type": "COMBINATION",
      "option_name1": "화이트",
      "option_name2": "M",
      "option_name3": "",
      "price": 0,
      "stock_quantity": 10,
      "cost_price": null,
      "usable": true,
      "seller_manager_code": "",
      "sort_order": 0,
      "created": "2026-10-12T09:37:44.811Z",
      "updated": "2026-10-12T09:37:44.811Z",
      "deleted": null,
      "color_id": null,
      "color_hex": "",
      "image": null,
      "option_unique": "6accaa68c2ca90eedea62101",
      "product_unique": "6accaa68c2ca90eedea62100"
    },
    {
      "option_type": "COMBINATION",
      "option_name1": "화이트",
      "option_name2": "L",
      "option_name3": "",
      "price": 1000,
      "stock_quantity": 5,
      "cost_price": null,
      "usable": true,
      "seller_manager_code": "",
      "sort_order": 1,
      "created": "2026-10-12T09:37:44.811Z",
      "updated": "2026-10-12T09:37:44.811Z",
      "deleted": null,
      "color_id": null,
      "color_hex": "",
      "image": null,
      "option_unique": "6accaa68c2ca90eedea62102",
      "product_unique": "6accaa68c2ca90eedea62100"
    },
    {
      "option_type": "COMBINATION",
      "option_name1": "네이비",
      "option_name2": "M",
      "option_name3": "",
      "price": 0,
      "stock_quantity": 0,
      "cost_price": null,
      "usable": true,
      "seller_manager_code": "",
      "sort_order": 2,
      "created": "2026-10-12T09:37:44.811Z",
      "updated": "2026-10-12T09:37:44.811Z",
      "deleted": null,
      "color_id": null,
      "color_hex": "",
      "image": null,
      "option_unique": "6accaa68c2ca90eedea62103",
      "product_unique": "6accaa68c2ca90eedea62100"
    }
  ]
}

product 필드

관리자 상품 등록 화면의 섹션 차례입니다.

상품 이미지

필드	형식	설명
`images`	string[] \| object[]	상품 이미지(첫 장이 대표, 차례 그대로). 키만 보냅니다 — 이미지 업로드(`?usage=product.image`)로 받은 `file_id` 를 `["6acc…", "6acc…"]` 처럼 문자열 배열로 넣고, `[{"file_id": "…"}]` 도 같습니다. 보내면 이미지 전체를 이것으로 바꾸고, 빠진 이미지 파일은 지웁니다
`images[].file_id`	string	이미지 업로드로 받은 키. 보낼 때는 이것만 — 저장소 · 경로 · 크기는 서버가 채웁니다
`images[].url`	string	이미지 주소(응답에만)
`images[].width`	number \| null	가로(px). 서버가 파일에서 채웁니다(응답에만)
`images[].height`	number \| null	세로(px). 서버가 파일에서 채웁니다(응답에만)
`images[].sort_order`	number	차례(0 이 대표). 보낸 배열의 차례로 매깁니다(응답에만)

상품 카테고리

필드	형식	설명
`category_id`	string \| null	대표 카테고리 키(상품 카테고리의 category_unique). 전체 카테고리는 걸 수 없습니다
`display_category_ids`	string[]	대표 외에 함께 진열할 카테고리 키

상품명

필드	형식	설명
`name`	string	상품명
`promotion_text`	string	간략소개(상품명 위 작은 글자)
`search_keywords`	string[]	검색어
`brand`	string	브랜드
`management_code`	string	판매자 관리 코드(손님에게 보이지 않음)
`supplier`	string	공급사(손님에게 보이지 않음)

판매가

필드	형식	설명
`sale_price`	number	판매가(원). 최소 금액보다 작으면 거절됩니다
`list_price`	number \| null	정가(원). 손님 화면에 취소선으로
`cost_price`	number \| null	원가(원). 손님에게 보이지 않고 목록 응답에도 없음
`tax_type`	string	상품의 과세 구분 코드값
`sale_type`	string	새 상품인지 중고인지 코드값

재고수량

필드	형식	설명
`stock_quantity`	number	재고. 옵션이 있으면 옵션 재고의 합으로 저장됩니다. 판매중 상품은 재고가 0 이면 품절, 다시 생기면 판매중으로 돌아옵니다(판매중지는 그대로)
`stock_unlimited`	boolean	재고 무제한
`restock_alert_excluded`	boolean	재입고 알림 대상에서 제외하는가(true 면 품절 때 재입고 알림 신청을 받지 않음)

할인 · 적립금

필드	형식	설명
`discount.immediate.enabled`	boolean	즉시 할인을 쓰는가
`discount.immediate.value`	number	즉시 할인 값(unit 에 따라 원 또는 %)
`discount.immediate.unit`	string	할인 단위. 율이면 0.01 ~ 99.99 코드값
`discount.period.enabled`	boolean	기간 할인을 쓰는가
`discount.period.value`	number	기간 할인 값
`discount.period.unit`	string	할인 단위. 율이면 0.01 ~ 99.99 코드값
`discount.period.start_at`	ISO \| null	기간 할인 시작
`discount.period.end_at`	ISO \| null	기간 할인 끝
`discount.bulk.enabled`	boolean	대량구매 할인을 쓰는가
`discount.bulk.rules[].basis`	string	조건(threshold)을 무엇으로 재는가 코드값
`discount.bulk.rules[].apply_to`	string	할인액을 주문 합계에서 한 번 빼는가, 개마다 빼는가 코드값
`discount.bulk.rules[].conditions[].threshold`	number	이 값(수량 · 금액) 이상이면
`discount.bulk.rules[].conditions[].value`	number	할인 값
`discount.bulk.rules[].conditions[].unit`	string	할인 단위. 율이면 0.01 ~ 99.99 코드값
`benefit_limit.coupon`	boolean	true 면 쿠폰을 쓸 수 없음
`benefit_limit.level_discount`	boolean	true 면 회원 등급 할인을 하지 않음
`benefit_limit.point`	boolean	true 면 적립금을 쓸 수 없음
`reward.enabled`	boolean	상품 적립금을 주는가
`reward.value`	number	적립 값
`reward.unit`	string	적립 단위 코드값
`reward.basis`	string	율로 적립할 때 어느 금액에 율을 곱하는가 코드값

주문옵션

필드	형식	설명
`option_info.names`	string[]	옵션명(예: ["색상", "사이즈"]). 최대 3개. 비우면 옵션 없는 상품
`option_info.pick_types`	string[]	옵션명마다 손님이 값을 고르는 모양. `names` 와 같은 자리끼리 짝이고, 모자라면 셀렉트 박스로 채웁니다. `TEMPLATE_COLOR` · `TEMPLATE_SIZE` 는 각각 한 자리에만 쓸 수 있습니다(둘 이상이면 400) — 직접 입력 옵션에서도 1 · 2 · 3차 어디든 둘 수 있고, 그 자리가 색상 · 사이즈 자리가 됩니다 코드값
`option_info.manage_fields`	string[]	옵션별로 따로 관리할 항목 — 관리자 옵션 목록에 그 열이 섭니다 코드값
`options`	array	옵션 행. 보내면 옵션 전체를 이것으로 바꿉니다
`options[].option_type`	string	옵션 행의 종류. 선택형 옵션 행은 `COMBINATION` 입니다 — 주문 요청사항은 이 배열이 아니라 `custom_options` 로 보냅니다 코드값
`options[].option_name1`	string	1단계 옵션값(option_info.names[0] 의 값, 예: 화이트)
`options[].option_name2`	string	2단계 옵션값(예: M)
`options[].option_name3`	string	3단계 옵션값
`options[].price`	number	옵션 가산액(원, 음수 가능)
`options[].stock_quantity`	number	옵션 재고
`options[].cost_price`	number \| null	옵션 원가
`options[].usable`	boolean	판매하는 옵션인가(false 면 손님 화면에 없음)
`options[].seller_manager_code`	string	판매자 관리 코드
`options[].image`	string \| object \| null	옵션 이미지 — 키 문자열 `"…"` 또는 `{"file_id": "…"}`(`?usage=product.option` 으로 올린 것). null 이면 빼기
`custom_options[].name`	string	입력 칸 이름(예: 각인 문구). 비우면 400
`custom_options[].input_type`	string	손님이 값을 내는 방식. 셀렉트 박스면 `values` 가, 텍스트폼 · 첨부파일이면 `guide` 가 쓰입니다 코드값
`custom_options[].required`	boolean	손님이 꼭 채워야 하는가
`custom_options[].values`	string[]	SELECT 일 때 고를 값
`custom_options[].guide`	string	칸 안내 문구
`custom_options[].fixed_guide`	boolean	TEXT 에서만. 켜면 `guide` 가 자리표시자가 아니라 칸에 미리 채워 둔 글이 됩니다(예: “- 기업/단체명:”)
`custom_scope`	string	주문 요청사항을 주문에 한 번 받는가, 고른 옵션마다 따로 받는가(각인 문구처럼 물건마다 다를 때). 항목마다가 아니라 상품 전체의 설정입니다 코드값
`extra_options[].name`	string	추가 상품 묶음 이름(예: 쇼핑백)
`extra_options[].required`	boolean	꼭 골라야 하는가
`extra_options[].use_stock`	boolean	재고를 쓰는가
`extra_options[].values[].value`	string	고를 값(예: 소형)
`extra_options[].values[].price`	number	그 값의 추가 상품가(원). 0 이상 — 음수는 받지 않습니다
`extra_options[].values[].stock_quantity`	number	그 값의 재고(use_stock 일 때)
`color_ids`	string[]	쓰는 색상 키(색상)
`size_template_id`	string \| null	쓰는 사이즈 템플릿(사이즈)
`sizes`	string[]	고른 사이즈

배송설정

필드	형식	설명
`delivery`	array	배송 방식 목록. 같은 방식은 한 번만 넣습니다. 배송 상품이면 하나 이상 — 비우면 배송없음 상품입니다(배송여부는 수단으로 정합니다)
`delivery[].method`	string	배송 방식. 같은 방식은 한 번만, 미배송(`NONE`)은 다른 방식과 함께 쓸 수 없습니다 코드값
`delivery[].template_id`	string	그 방식의 배송 템플릿 키(택배배송 등). NONE 을 뺀 방식은 필수 — 없으면 "택배배송의 템플릿이 지정되지 않았습니다"
`shippable`	boolean	배송하는 상품인가. 보내지 않으면 `delivery` 로 정합니다 — 수단이 있으면 true, 없으면 false. `true` 로 보내고 수단이 없으면 400
`bundle_shipping`	string	다른 상품과 한 상자로 묶어 보낼 수 있는가. 대량구매 할인을 켜면 가능으로 둘 수 없어 부분가능으로 낮춰 저장합니다 코드값
`collect_clearance_code`	boolean	주문 때 통관고유부호를 받는가

상세설명

필드	형식	설명
`detail_content_body`	string	상세 설명 HTML. 이미지는 이미지 업로드(`?usage=product.detail`)의 `url` 을 `<img src>` 에 넣습니다 — 이 쇼핑몰 파일이면 상품에 붙고, 빼면 지워집니다
`video_url`	string	동영상 주소

상품정보제공고시

필드	형식	설명
`product_info_provided_notice`	object \| null	상품정보제공고시. null 이면 등록하지 않음
`product_info_provided_notice.mode`	string	고시를 서식 항목(`fields`)으로 적는가, 이미지(`image`) 한 장으로 넣는가. 고르지 않은 쪽 값은 버립니다 코드값
`product_info_provided_notice.product_info_provided_notice_type`	string	서식 코드(의류 · 식품 …). FORM 일 때. IMAGE 면 빈 글자
`product_info_provided_notice.fields`	object	항목 이름 → 값(예: `{"소재": "린넨 100%", "제조국": "대한민국"}`). FORM 일 때
`product_info_provided_notice.image`	string \| object \| null	이미지 한 장 — 키 문자열 `"…"` 또는 `{"file_id": "…"}`, IMAGE 일 때(`?usage=product.notice`)

공통정보 템플릿

필드	형식	설명
`top_template_ids`	string[]	상세 위에 붙일 공통정보 키
`bottom_template_ids`	string[]	상세 아래에 붙일 공통정보 키

전시 설정

필드	형식	설명
`display_status`	string	쇼핑몰 화면에 보이는가. 기간 전시면 `display_start_at` · `display_end_at` 가 필수입니다 코드값
`display_start_at`	ISO \| null	기간 전시 시작(PERIOD)
`display_end_at`	ISO \| null	기간 전시 끝(PERIOD)
`display_order`	number	기본 전시순(작을수록 앞)
`badge_ids`	string[]	상품명 앞 배지 키(상품 배지의 badge_unique). 5개까지 — 쇼핑몰 관리자 화면은 2개까지 보여 주고, 관리자에서 다시 저장하면 앞의 2개만 남습니다
`icon_id`	string \| null	상품 이미지 우측 상단 아이콘 키(상품 아이콘의 icon_unique). 하나. `null` 이면 없음
`view_permission`	string	누가 상품을 볼 수 있나. 회원으로 좁히면 `view_level` 로 등급까지 거를 수 있습니다 코드값
`view_level`	number	MEMBER 일 때 최소 등급 레벨

판매 설정

필드	형식	설명
`status_type`	string	판매 상태 — 보낼 때는 `SALE` · `SUSPENSION` 만(관리자 판매상태 탭과 같음). 판매자가 고른 값이 최우선이라 재고는 판매중 상품에만 품절을 덧씌웁니다 코드값
`sale_start_at`	ISO \| null	판매 시작
`sale_end_at`	ISO \| null	판매 끝
`order_permission`	string	누가 주문할 수 있나. 회원으로 좁히면 `order_level` 로 등급까지 거를 수 있습니다 코드값
`order_level`	number	MEMBER 일 때 최소 등급 레벨
`order_limit.enabled`	boolean	주문 수량을 제한하는가
`order_limit.basis`	string	수량 제한을 옵션마다 따로 세는가, 옵션을 합쳐 세는가 코드값
`order_limit.min`	number	최소 주문 수량(0 이면 없음)
`order_limit.max`	number	최대 주문 수량(0 이면 없음)
`order_limit.max_check`	string	최대 수량을 어느 기간 동안 세는가 — 한 주문 안에서만인지, 지난 며칠의 주문까지 합쳐서인지 코드값
`adult_only`	boolean	성인 인증 상품

기타 설정

필드	형식	설명
`review_template_id`	string \| null	맞춤형 리뷰 키. null 이면 기본 리뷰
`seo.mode`	string	검색엔진 문구를 쇼핑몰 기본값으로 둘지, 아래 `page_title` · `meta_description` 를 쓸지 코드값
`seo.page_title`	string	검색 결과 · 브라우저 탭 제목(MANUAL)
`seo.meta_description`	string	검색 결과 설명(MANUAL)
`seo.target_keywords`	string	검색 키워드(쉼표로 구분, MANUAL)

응답에만 있는 값

필드	형식	설명
`product_unique`	string	상품 키. 상세 · 수정 · 삭제 경로에 넣습니다
`product_no`	number	상품 번호(쇼핑몰 주소 /product/{product_no})
`option_info.generation`	string	옵션을 직접 적었는가, 색상 · 사이즈 템플릿에서 골라 만들었는가. 템플릿으로 만들었으면 그 템플릿의 적용상품으로 셉니다 코드값
`option_info.size_template_id`	string \| null	옵션의 사이즈 템플릿(서버가 채움). 생성 방식이 사이즈 템플릿이거나, 직접 입력에서 TEMPLATE_SIZE 자리를 둔 상품에만 남습니다
`source.type`	string	등록 경로 — API · 관리자로 만든 상품은 `SELF`
`source.external_code`	string \| null	외부에서 가져온 상품이면 그쪽 코드
`source.imported_at`	ISO \| null	외부에서 가져온 시각
`created`	ISO	등록 시각
`updated`	ISO	마지막 수정 시각. 수정할 때 `expected_updated` 에 넣습니다
`deleted`	ISO \| null	지운 시각(지운 상품은 나오지 않으므로 늘 null)

options 필드

필드	형식	설명
`option_unique`	string	옵션 행 키
`option_type`	string	옵션 행 방식(`COMBINATION` 선택형 …) 코드값
`option_name1`	string	1단계 옵션값(예: 화이트)
`option_name2`	string	2단계 옵션값(예: M). 없으면 빈 글자
`option_name3`	string	3단계 옵션값
`price`	number	옵션 가산액(원, 음수 가능)
`stock_quantity`	number	옵션 재고
`cost_price`	number \| null	옵션 원가
`usable`	boolean	판매하는 옵션인가(false 면 손님 화면에 없음)
`seller_manager_code`	string	판매자 관리 코드
`sort_order`	number	차례
`color_id`	string \| null	색상 템플릿의 색을 쓴 행이면 그 색상 키. 색상 자리(생성 방식이 템플릿이면 1단계, 직접 입력이면 pick_types 가 TEMPLATE_COLOR 인 단계)의 옵션값이 그 색 이름으로 저장되고, 색상 템플릿에서 이름을 고치면 따라 바뀝니다
`color_hex`	string	그 색 값(#RRGGBB)
`image`	object \| null	옵션 이미지
`product_unique`	string	이 옵션의 상품 키

오류

상태	code	언제
404	`ProductNotExist`	없는 키이거나 지운 상품
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 products:read · products:write 가 없음

요청#

응답#

product 필드#