상품 등록

필수는 name · sale_price 둘이고, 배송하는 상품이면 delivery(배송수단)를 하나 이상 넣습니다 — 비우면 배송없음 상품으로 등록됩니다. 관리자 상품 등록 화면이 저장 전에 막는 것을 API 도 똑같이 막고, 보내지 않은 필드는 그 화면의 기본값으로 저장됩니다. 조건부 필수 · 상한 · 서버가 바꿔 저장하는 값은 맨 아래 구현 규칙에 모았습니다.

탭은 상황별 본문입니다(응답 예시도 같은 탭으로 바뀝니다). 옵션 없음은 stock_quantity 를 바로 적고, 옵션 1~3개는 option_info.names 와 행의 option_name1 ~ option_name3 을 같은 차례로 채웁니다. 덧붙여 사는 것은 extra_options(추가상품), 손님이 적어 내는 것은 custom_options(주문 요청사항)이고 주문옵션과 함께 써도 됩니다.

curl -X POST 'https://api.mallstory.kr/v1/shop/{shop_unique}/products' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "무지 에코백",
  "sale_price": 15000,
  "list_price": 18000,
  "cost_price": 6000,
  "stock_quantity": 30,
  "status_type": "SALE",
  "tax_type": "TAX",
  "category_id": "6aab6a9ddd8941ed187ffe4b",
  "display_status": "DISPLAY",
  "stock_unlimited": false,
  "search_keywords": [
    "에코백"
  ],
  "management_code": "BG-ECO-001",
  "delivery": [
    {
      "method": "PARCEL",
      "template_id": "6a9fa2affc6e77ca0e475e4c"
    }
  ]
}'

{
  "product_unique": "6acd9ad3c2ca90eedea62185",
  "product_no": 66,
  "name": "무지 에코백",
  "sale_price": 15000,
  "list_price": 18000,
  "cost_price": 6000,
  "stock_quantity": 30,
  "status_type": "SALE",
  "display_status": "DISPLAY",
  "category_id": "6aab6a9ddd8941ed187ffe4b",
  "option_info": {
    "names": [],
    "pick_types": [],
    "manage_fields": [
      "price",
      "stockQuantity"
    ],
    "size_template_id": null
  },
  "delivery": [
    {
      "method": "PARCEL",
      "template_id": "6a9fa2affc6e77ca0e475e4c"
    }
  ],
  "created": "2026-10-13T02:43:31.155Z",
  "updated": "2026-10-13T02:43:31.155Z"
}

만든 상품 전체(상품 상세의 product 와 같은 모양, 원가 포함)를 돌려줍니다. 옵션이 있으면 stock_quantity 는 옵션 재고의 합입니다(옵션 1개 예시는 20 + 15 + 0 = 35). 옵션 행은 상세로 읽습니다.

관리자 상품 등록 화면의 섹션 차례입니다. 응답에만 있는 값(상품 키 · 번호 · 시각)은 보내지 않습니다.

상품 이미지

상품 카테고리

상품명

판매가

재고수량

할인 · 적립금

주문옵션

배송설정

상세설명

상품정보제공고시

공통정보 템플릿

전시 설정

판매 설정

기타 설정

관리자 상품 등록 화면과 서버가 저장 전에 보는 규칙 전부입니다. 이 규칙을 지키면 400 없이 한 번에 등록됩니다. 같은 내용을 마크다운 원문으로도 받을 수 있습니다.

호출 순서

1. 1
   이미지 올리기

   이미지가 있으면 먼저 올린다 — POST /v1/shop/{shop_unique}/files/images?usage=product.image(옵션 이미지 product.option · 상품정보제공고시 product.notice · 상세 본문 product.detail). 응답의 file_id 만 본문에 넣는다.
2. 2
   키 모으기

   넣을 키를 이 쇼핑몰에서 읽는다 — 카테고리 GET /v1/shop/{shop_unique}/categories, 배송 템플릿 GET /v1/shop/{shop_unique}/templates/delivery?method=PARCEL(DIRECT · QUICK · PICKUP), 공통정보 · 색상 · 사이즈 · 맞춤형 리뷰 GET /v1/shop/{shop_unique}/templates/{common|colors|sizes|reviews}. 다른 쇼핑몰 키 · 지어낸 키는 400.
3. 3
   등록

   등록한다 — POST /v1/shop/{shop_unique}/products. 응답은 저장된 상품 전체다.
4. 4
   확인

   저장 결과를 확인한다 — GET /v1/shop/{shop_unique}/products/{product_unique}. 서버가 바꿔 저장한 값(아래 "서버가 바꿔 저장하는 값")과 옵션 행은 상세에서 읽는다.

언제나 필수

조건부 필수 · 값끼리 맞물리는 규칙

서버가 바꿔 저장하는 값

오류 없이 저장되지만 보낸 값과 달라지는 것입니다. 등록 응답 · 상세로 확인합니다.

• 판매 상태는 판매자가 고른 값이 최우선이다. 재고는 SALE(판매중) 상품에만 품절을 덧씌운다 — 재고가 0 이면 OUTOFSTOCK, 다시 생기면 SALE 로 돌아간다. SUSPENSION(판매중지)은 재고를 채워도 그대로다. 무제한 재고는 품절이 되지 않는다.
• 옵션 행이 있으면 상품 stock_quantity 는 옵션 재고의 합이고, 판매 상태는 위 규칙대로 그 합으로 맞춘다.
• shippable 을 보내지 않으면 delivery 로 정한다 — 배송 방식이 하나라도 있으면 true, 없으면 false(배송없음). 수정에서 delivery 만 보내도 다시 정한다. 옛 표시 NONE 은 방식으로 세지 않는다.
• 대량구매 할인이 켜져 있고 bundle_shipping 이 POSSIBLE(없으면 POSSIBLE 로 봄)이면 PARTIAL 로 낮춰 저장된다 — 할인만 보낸 수정도 저장된 값과 합쳐 본다. 할인을 꺼도 POSSIBLE 로 되돌리지 않는다.
• view_permission · order_permission 이 GUEST 면 view_level · order_level 은 0 이 된다.
• product_info_provided_notice 는 고른 mode 의 값만 남는다(FORM 이면 image 를, IMAGE 면 fields 를 버림).
• search_keywords 는 빈 값 · 중복을 걷어 낸다.
• option_info.pick_types 가 names 보다 모자라면 SELECT 로 채운다. 옵션명은 3개까지만 남긴다.
• size_template_id 가 null 이면 sizes 는 비운다.
• detail_content_body 는 허용한 태그 · 속성만 남기고 씻는다. top_template_ids · bottom_template_ids 의 공통정보는 저장하지 않고 손님 화면이 열 때 본문 위 · 아래에 붙인다 — 템플릿을 고치면 그 템플릿을 쓰는 상품에 바로 반영된다. 관리자 상세 응답에는 본문(detail_content_body)만 온다.
• 개수 상한을 넘는 일부 목록은 오류 없이 잘라 저장한다 — badge_ids 5 · color_ids 200 · custom_options 5 · extra_options 20 · 항목당 선택값 20. 넘게 보내지 않는다.

상한 · 범위

보내지 않으면

수정(PATCH)이 다른 점

• 보낸 필드만 바뀐다. 등록의 필수 조건은 보낸 칸과 이어진 것만 수정 뒤 값으로 다시 본다 — display_status · display_start_at · display_end_at 을 보내면 전시기간, sale_start_at · sale_end_at 이면 판매기간, shippable · delivery 면 배송수단, options 없이 option_info 면 저장된 옵션 행. 보내지 않은 칸의 옛 빈칸으로는 막지 않는다.
• delivery 만 보내면 배송여부(shippable)를 남은 방식으로 다시 정한다(모두 지우거나 NONE 이면 배송없음). shippable: true 를 보냈는데 수정 뒤 배송 방식이 하나도 없으면 400.
• options · images 는 통째로 바꾼다. 일부만 고치려 해도 남길 것까지 모두 보낸다. 빠진 이미지 파일은 바로 지워진다.
• expected_updated 에 상세에서 읽은 updated 를 넣으면 그 사이 다른 곳에서 고쳤을 때 409 로 막힌다(덮어쓰기 방지).

오류 코드