# 변경 이력 (Mall Story Open API)

> 원문: https://developers.mallstory.co.kr/docs/changelog · 피드: https://developers.mallstory.co.kr/changelog.xml · 문서 목록: https://developers.mallstory.co.kr/llms.txt
> 맨 위가 최신. 종류: 추가 · 변경 · 수정 · 폐기 예정 · 호환 깨짐. **호환 깨짐**이면 연동 코드를 고쳐야 한다.

## 바꾸는 날 규칙

- **적용일** — 폐기 · 호환 깨짐은 **매달 1일**(휴일이면 다음 영업일 — 주말 · 한국 공휴일 · 대체공휴일 제외) **오전 10시(한국 시각)**에 바뀝니다.
- **예고** — 적용일 **3개월 전 1일까지** 이 쪽에 "폐기 예정" 으로 올리고 적용일을 적습니다. 예) 2027년 3월 2일(1일 휴일) 적용 → 2026년 12월 1일까지 예고.
- **예외** — 보안 · 개인정보 문제는 예고 없이 바로 바꾸고 까닭을 적습니다.
- **추가** — 새 필드 · 새 API · 받는 값을 늘리는 것은 아무 때나 엽니다. 연동 코드는 **모르는 응답 필드를 무시**하도록 만들어 주세요.
- **베타** — 정식 공개 전(지금)에는 예고 없이 바로 바꾸고 "호환 깨짐" 으로 남깁니다.

## 2026-10-26 · [호환 깨짐] 상품 일괄 정보수정 항목이 늘고, 할인 / 적립금이 둘로 나뉘었습니다

- 영역: 관리자 API
- `POST /products/bulk` 의 `field` 에 `image` · `video` · `option-select`(주문옵션) · `option-extra`(추가상품) · `option-custom`(주문 요청사항) · `bundle-shipping` · `detail`(상세설명) · `icon` · `color` · `size` · `clearance-code` 가 더해졌습니다. 이미지 · 상세설명 그림 · 옵션 이미지는 상품마다 파일을 복사해 붙입니다(상품 수만큼 저장 용량을 씀).
- **호환**: `product-discount` 가 없어지고 `discount`(할인 설정 — `discount`) · `reward`(적립금 설정 — `reward`) 로 나뉘었습니다. `product-discount` 를 보내면 400 입니다. 베타라 예고 없이 바꿨습니다.
- `option-select` 는 옵션이 **없는** 상품에만 옵션을 붙이고, 이미 옵션이 있는 상품은 `OptionProduct` 로 실패합니다. 옵션명 · 행을 모두 비워 보내면 옵션을 모두 지웁니다.
- `color` · `size` 도 옵션이 있는 상품은 `OptionProduct` 로 실패합니다. `OptionProduct` 의 `message` 문장이 바뀌었습니다 — 문장이 아니라 `code` 로 가르세요.
- 쇼핑몰이 배송여부를 숨겼으면 배송 방식 일괄 수정으로 마지막 방식을 끄는 상품은 `InvalidParameterValue` 로 실패합니다.
- 관련 문서: [상품 일괄 처리](https://developers.mallstory.co.kr/docs/products-bulk) · [코드값](https://developers.mallstory.co.kr/docs/codes)

## 2026-10-26 · [변경] 직접 입력 옵션에서 템플릿 색상 · 사이즈 자리를 1 · 2 · 3차 어디든 둘 수 있습니다

- 영역: 관리자 API
- `option_info.pick_types` 의 `TEMPLATE_COLOR` · `TEMPLATE_SIZE` 는 각각 **한 자리에만** 쓸 수 있습니다(둘 이상이면 400). 직접 입력(`generation: DIRECT`)에서 그 자리의 옵션값이 색상명 · 사이즈 값이 되고, 행의 `color_id` 는 그 자리의 색을 가리킵니다.
- 직접 입력이라도 `TEMPLATE_SIZE` 자리가 있으면 `option_info.size_template_id` 가 남습니다(전에는 사이즈 템플릿 생성 방식에서만).
- `option_info.manage_fields` 의 문서 차례를 관리자 화면과 같게 맞췄습니다(번호 · 옵션가 · 원가 · 재고수량 · 관리코드 · 이미지 · 노출여부). 받는 값은 그대로입니다.
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [상품 상세](https://developers.mallstory.co.kr/docs/products-detail) · [코드값](https://developers.mallstory.co.kr/docs/codes)

## 2026-10-26 · [변경] 상세설명 · 공통정보 이미지는 가로만 1000 으로 줄입니다

- 영역: 관리자 API
- `POST /files?usage=product.detail` · `product.template` 은 가로가 1000 을 넘을 때만 가로 1000 으로 줄이고 세로는 비율대로 둡니다. 전에는 긴 변을 1000 에 맞춰 세로로 긴 상세 이미지의 글씨가 뭉개졌습니다.
- 관련 문서: [이미지 업로드](https://developers.mallstory.co.kr/docs/files)

## 2026-10-20 · [변경] 회원 목록의 개인정보 가림은 쇼핑몰 보안 설정의 마스킹을 따릅니다

- 영역: 관리자 API
- ISMS 대상 스위치 대신, 쇼핑몰 관리자 설정 › 보안 설정의 **개인정보 마스킹**을 켠 쇼핑몰이면 회원 목록 · MCP `list_members` 의 이름 · 메일 · 휴대폰 · 생년월일이 가려집니다. 응답 모양은 그대로입니다.
- 관련 문서: [회원 관리](https://developers.mallstory.co.kr/docs/members) · [MCP 연결](https://developers.mallstory.co.kr/docs/mcp)

## 2026-10-19 · [추가] 상품 복사가 생겼습니다

- 영역: 관리자 API
- `POST /products/{product_unique}/copy` 가 상품 정보 · 이미지 · 옵션 · 상세설명 · 정보고시를 한 벌 더 만들고 복사본의 `{product, options}` 를 201 로 돌려줍니다. 복사본은 이름 앞에 `[복사] ` 가 붙고 **전시중지 · 판매중지 · 새 상품번호**로 생깁니다 — 고친 뒤 수정으로 켜세요.
- 이미지는 새 파일로 다시 올라가 쇼핑몰 저장 용량을 씁니다(넘으면 413 `StorageQuotaExceeded`). 부를 때마다 하나씩 생기니 재시도 전에 목록을 확인하세요.
- MCP 에 `copy_product` 도구가 더해졌습니다(47개 → 48개). 쇼핑몰 관리자 상품 목록 줄 메뉴의 복사와 같은 동작입니다.
- 관련 문서: [상품 복사](https://developers.mallstory.co.kr/docs/products-copy) · [상품 관리](https://developers.mallstory.co.kr/docs/products) · [MCP 연결](https://developers.mallstory.co.kr/docs/mcp)

## 2026-10-16 · [호환 깨짐] 쿠폰번호는 쿠폰 하나에 10,000개까지입니다

- 영역: 관리자 API
- `POST /coupons/{coupon_unique}/serials` 가 한 번에 받는 `count` 상한이 100,000 → **10,000** 으로 줄고, 이미 만든 수와 더해 쿠폰 하나에 **10,000개**를 넘으면 400 입니다. 응답 문장에 남은 자리를 적어 줍니다.
- 번호 하나가 문서 하나라 상한 없이 두면 공유 DB 에 부담이 됩니다. 그보다 많이 뿌릴 행사는 `serial_mode: SAME`(동일번호 발급)으로 만들고 `per_person_limit` 로 한 사람당 장 수를 막으세요. 베타라 예고 없이 바꿨습니다.
- 관련 문서: [쿠폰번호 발급](https://developers.mallstory.co.kr/docs/coupons-serials)

## 2026-10-16 · [변경] 쿠폰 이용 내역이 상품 목록처럼 쪽 번호 · 조건 · 정렬을 받습니다

- 영역: 관리자 API
- `GET /coupons/issues` · `/coupons/{coupon_unique}/issues` 에 `page` · `size`(최대 100) · `status` · `member_unique` · `serial` · `keyword` · `issued_from` · `issued_to` · `sort` · `order` 쿼리가 생겼습니다. 응답에 `page` · `size` · `total` · `has_more` 가 더해졌습니다.
- **호환**: 전에는 최근 500장을 한 번에 주었는데, 이제 쿼리 없이 부르면 **첫 쪽 20장**입니다. 전부가 필요하면 `has_more` 가 false 일 때까지 쪽을 넘기세요. 베타라 예고 없이 바꿨습니다.
- MCP `list_coupon_issues` 도 같은 조건을 받습니다.
- 관련 문서: [쿠폰 이용 내역](https://developers.mallstory.co.kr/docs/coupons-issues) · [코드값](https://developers.mallstory.co.kr/docs/codes) · [MCP 연결](https://developers.mallstory.co.kr/docs/mcp)

## 2026-10-16 · [추가] 쿠폰에 적용 카테고리가 생겼습니다

- 영역: 관리자 API
- 쿠폰 생성 · 수정에 `category_mode`(OFF · ON) 와 `category_ids` 를 받습니다. ON 이면 고른 카테고리**부터 그 하위 전체**의 상품에만 쿠폰을 쓸 수 있습니다 — 하위를 따로 적지 않습니다. 비우면 OFF(모든 상품)입니다.
- 목록 · 상세 응답에 `category_mode` · `category_ids` · `category_names`(경로 이름)가 더해졌습니다. 모르는 응답 필드를 무시하도록 만든 연동은 할 일이 없습니다.
- 문서의 쿠폰 쪽을 상품 관리처럼 묶었습니다 — 개요 아래 목록 · 생성 · 수정 · 삭제 · 이용 내역 · 쿠폰번호 쪽이 섭니다.
- 관련 문서: [쿠폰 관리](https://developers.mallstory.co.kr/docs/coupons) · [쿠폰 생성](https://developers.mallstory.co.kr/docs/coupons-create) · [쿠폰 수정](https://developers.mallstory.co.kr/docs/coupons-update) · [코드값](https://developers.mallstory.co.kr/docs/codes)

## 2026-10-14 · [변경] 호출 제한을 따로 쪽으로 분리했습니다

- 영역: API 공통
- API 호출하기 안에 있던 "호출 제한" 을 **호출 제한** 쪽으로 옮기고, 분당 한도 옆에 초당 환산을 적었습니다(소유자 300/분 = 5/초 · 회원 120/분 = 2/초 · 비회원 600/분 = 10/초).
- 한도 헤더 설명, 429 를 받았을 때의 재시도 규칙, 호출을 줄이는 방법을 더했습니다. 한도 값은 바뀌지 않았습니다.
- 관련 문서: [호출 제한](https://developers.mallstory.co.kr/docs/limits) · [API 호출하기](https://developers.mallstory.co.kr/docs/calling)

## 2026-10-14 · [추가] 상품 아이콘 API 와 상품의 `icon_id` 를 열었습니다

- 영역: 상품 관리
- 상품 이미지 우측 상단에 얹는 아이콘을 `/v1/shop/{shop_unique}/icons` 로 만들고 고치고 지웁니다(`products:read` · `products:write`). 상품에는 `icon_id` 로 하나를 겁니다.
- 아이콘 이미지는 `POST /files/images?usage=product.decoration&variant=icon` 으로 올립니다 — 이때만 **SVG** 를 받고 한 장입니다. JPG · PNG 는 가로 · 세로 160 안으로 줄입니다.
- 쇼핑몰 조회 API 의 상품 카드에 `icon`(`name` · `url`, 없으면 `null`)이 붙습니다.
- MCP 에 `list_icons` · `get_icon` · `create_icon` · `update_icon` · `delete_icon` 을 더했고, `upload_images` 가 `variant: "icon"` 을 받습니다.
- 관련 문서: [상품 아이콘](https://developers.mallstory.co.kr/docs/icons) · [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [상품 수정](https://developers.mallstory.co.kr/docs/products-update) · [상품 상세](https://developers.mallstory.co.kr/docs/products-detail) · [이미지 업로드](https://developers.mallstory.co.kr/docs/files) · [상품 목록](https://developers.mallstory.co.kr/docs/store-products) · [MCP 연결](https://developers.mallstory.co.kr/docs/mcp)

## 2026-10-14 · [변경] 옵션가 하한을 할인 적용 후 금액으로 봅니다

- 영역: 상품 관리
- 전에는 `판매가 + 옵션가` 가 1원 미만일 때만 `OptionBelowFloor` 였습니다. 이제 할인을 켠 상품은 `(판매가 − 할인 합계) + 옵션가` 로 봅니다 — 할인과 옵션 차감이 겹쳐 0원 이하가 되는 옵션도 막힙니다.
- 메시지는 할인 유무에 따라 두 문장입니다. 관리자 화면과 같은 문장입니다.
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [상품 수정](https://developers.mallstory.co.kr/docs/products-update)

## 2026-10-14 · [변경] 배지 이미지는 가로 160 을 넘으면 줄여 저장합니다

- 영역: 상품 관리
- `usage=product.decoration` 으로 올린 이미지는 가로 160 을 넘을 때만 가로 160 으로 줄입니다(세로는 비율대로). 전에는 상품 이미지와 같은 1000 기준이었습니다. 응답의 `width` · `height` 가 줄인 뒤 값입니다.
- 관련 문서: [이미지 업로드](https://developers.mallstory.co.kr/docs/files) · [상품 배지](https://developers.mallstory.co.kr/docs/badges)

## 2026-10-13 · [변경] 상품 수정도 보낸 칸과 이어진 필수 조건을 봅니다

- 영역: 상품 관리
- 전에는 필수 조건(전시기간 · 판매기간 · 배송수단 · 옵션 행)을 등록에서만 봐서, 수정으로 `display_status: "PERIOD"` 만 보내면 기간 없는 전시기간 상품이 됐습니다. 이제 보낸 칸과 이어진 조건을 수정 뒤 값으로 보고 등록과 같은 문장으로 400 을 줍니다.
- 보내지 않은 칸은 보지 않습니다 — 옛 상품에 빈칸이 있어도 이름 · 가격 같은 다른 칸 수정은 그대로 됩니다.
- 관련 문서: [상품 수정](https://developers.mallstory.co.kr/docs/products-update)

## 2026-10-13 · [수정] 없는 /v1 경로는 404 입니다

- 영역: API 공통
- 토큰을 넣고 없는 경로를 부르면 `501 NotImplemented`("준비 중") 가 왔습니다. 이제 `404 NotFound` 와 요청 ID 가 옵니다. 템플릿 하나의 주소에 POST 하면 키 자리가 키 모양이 아닐 때 404, 키면 405 입니다. `/v1/store` 를 소유자 토큰으로 부를 때의 403 문구도 무엇을 쓰면 되는지 말하게 고쳤습니다.
- 관련 문서: [API 호출하기](https://developers.mallstory.co.kr/docs/calling) · [상품 목록](https://developers.mallstory.co.kr/docs/store-products)

## 2026-10-13 · [추가] 회원 로그인에 회원 IP · User-Agent 를 넘길 수 있습니다

- 영역: 인증
- `POST /v1/member/login` 에 `X-Member-IP`(회원 기기 IP 하나) · `X-Member-User-Agent` 헤더를 넣으면 쇼핑몰의 회원 로그인 기록에 앱 서버가 아니라 **회원의 IP · 단말**이 남습니다. 실제로 부른 앱 서버 IP 와 앱은 따로 남습니다.
- 넘기지 않아도 로그인은 그대로 됩니다. `X-Member-IP` 가 IP 모양이 아니면(쉼표 목록 · 포트) `400 invalid_request`.
- 관련 문서: [회원 로그인](https://developers.mallstory.co.kr/docs/member-login)

## 2026-10-13 · [추가] 호출 한도를 걸었습니다 — 넘으면 429

- 영역: API 공통
- `/v1` · `/mcp` 를 1분 단위로 셉니다 — 소유자 토큰은 앱 · 쇼핑몰당 300회, 회원 토큰은 앱 · 회원당 120회, 비회원 조회(`X-Client-Id`)는 앱당 600회. REST 와 MCP 가 같은 한도를 나눠 씁니다.
- 응답에 `X-RateLimit-Limit` · `X-RateLimit-Remaining` · `X-RateLimit-Reset` 이 붙고, 넘으면 `429 TooManyRequests` + `Retry-After`(초). MCP 는 JSON-RPC 오류 `-32029` 입니다.
- 관련 문서: [API 호출하기](https://developers.mallstory.co.kr/docs/calling) · [MCP 연결](https://developers.mallstory.co.kr/docs/mcp)

## 2026-10-13 · [추가] Postman 컬렉션에 수정 · 삭제 요청을 채웠습니다

- 영역: 시작하기
- 템플릿 8종의 상세 · 수정 · 삭제, 배송 할증지역 쓰기(도로 찾기 · 더하기 · 수정 · 삭제 · 기본 지역 빼기/되돌리기), 카테고리 만들기 · 수정 · 옮기기 · 삭제, 회원 등급 만들기 · 수정 · 삭제, 이미지 업로드 7가지(쓰임별), 쿠폰(카카오톡 채널 쿠폰번호 포함) · 회원 적립금 · 상품 배지.
- 만들기 요청이 새 키를 변수에 담아, 이어지는 수정 · 삭제가 방금 만든 것을 가리킵니다. 컬렉션만 다시 가져오면 됩니다.
- **환경 파일에 변수가 늘었습니다** — `coupon_unique` · `badge_unique` · `level_unique` · `file_id` · `color_unique` · `surcharge_unique` · `area_unique`. 이미 가져온 환경에는 이 칸을 직접 더하세요(값은 비워 둠). 새로 받는 환경 파일에는 들어 있습니다.
- 관련 문서: [Postman 으로 시험하기](https://developers.mallstory.co.kr/docs/postman)

## 2026-10-13 · [추가] MCP 도구를 REST 관리자 API 에 맞췄습니다(11개 → 47개)

- 영역: AI 에이전트
- 새 도구 — `upload_images`(이미지 올리기 — 로컬 파일의 base64 또는 공개 주소 → file_id), 카테고리 만들기 · 수정 · 옮기기 · 삭제, `bulk_products`(상품 일괄 처리), 상품 배지, 템플릿 관리(`kind` 하나로 다섯 종류), 배송 할증지역, 회원 등급, 회원 적립금, 쿠폰(이용 내역 · 쿠폰번호 포함).
- REST 와 같은 동작 · 같은 검사 · 같은 기록입니다. 토큰에 없는 권한의 도구는 `tools/list` 에 나오지 않습니다 — 쿠폰 도구를 쓰려면 `promotions:read` · `promotions:write` 로 다시 연결합니다.
- Claude Code 처럼 로컬 파일을 읽는 에이전트는 파일을 그대로 올릴 수 있습니다(토큰을 꺼낼 필요 없음). 주문 · 클레임 도구는 주문 메뉴와 함께 엽니다.
- 관련 문서: [MCP 연결](https://developers.mallstory.co.kr/docs/mcp) · [이미지 업로드](https://developers.mallstory.co.kr/docs/files)

## 2026-10-13 · [추가] 쿠폰 · 회원 적립금 · 상품 배지 API 를 열었습니다

- 영역: 관리자 API
- **쿠폰** `/v1/shop/{shop_unique}/coupons` — 목록 · 상세 · 생성 · 수정(보낸 필드만) · 삭제, 이용 내역, 카카오톡 채널용 쿠폰번호 만들기 · 읽기. 새 권한 `promotions:read` · `promotions:write` 가 생겼습니다 — 쓰려면 앱 등록에서 권한을 더하고 동의를 다시 받습니다.
- **회원 적립금** `/members/{member_unique}/points` — 잔액 · 내역 읽기(customers:read), 지급 · 차감(customers:write). 잔액보다 많이 차감하면 403 `PointExceed`.
- **상품 배지** `/badges` — 목록 · 상세 · 생성 · 수정 · 삭제(products:read · write). 상품의 `badge_ids` 에 넣는 키를 여기서 얻습니다.
- 관련 문서: [쿠폰 관리](https://developers.mallstory.co.kr/docs/coupons) · [회원 적립금](https://developers.mallstory.co.kr/docs/points) · [상품 배지](https://developers.mallstory.co.kr/docs/badges) · [권한(스코프)](https://developers.mallstory.co.kr/docs/scopes)

## 2026-10-13 · [변경] 배지 이미지도 파일 키만 믿습니다

- 영역: 이미지 업로드
- 배지 이미지는 `file_id` 만 보고 저장소 · 경로 · 크기는 이 쇼핑몰의 파일 기록에서 채웁니다. 관리자 화면 저장도 같은 규칙입니다. 다른 쇼핑몰 · 지운 파일이면 400.
- 관련 문서: [상품 배지](https://developers.mallstory.co.kr/docs/badges) · [이미지 업로드](https://developers.mallstory.co.kr/docs/files)

## 2026-10-13 · [추가] 회원이 마이페이지에서 연결된 앱을 해지합니다

- 영역: 인증
- 쇼핑몰 마이페이지에 **연결된 앱** 이 생겼습니다. 회원 본인이 동의한 앱 · 제공 항목 · 동의일 · 마지막 사용일이 보이고, [해지] 하면 그 회원 · 그 앱의 동의가 지워지고 토큰이 모두 끊깁니다(`401 invalid_token`). 다시 쓰려면 동의를 새로 받습니다.
- 앱 등록에 **회원 해지**(마이페이지에서 바로 | 고객센터로 요청)가 생겼습니다. 기본은 바로입니다. 고객센터로 요청이면 [해지] 대신 쇼핑몰 고객센터 연락처가 보입니다. 회원 동의 화면의 보유 기간에도 해지하는 곳이 적힙니다.
- 관련 문서: [회원 동의](https://developers.mallstory.co.kr/docs/member-authorization) · [앱 등록하기](https://developers.mallstory.co.kr/docs/register-app)

## 2026-10-13 · [변경] 승인되지 않은 동적 등록 앱은 7일 뒤 지웁니다

- 영역: AI 에이전트
- MCP 커넥터가 `/api/oauth/register` 로 등록만 하고 7일 안에 한 번도 승인 · 토큰 발급까지 가지 않은 앱은 새벽 정리에서 지웁니다. 승인된 앱은 그대로입니다. 커넥터는 다시 연결할 때 새로 등록합니다.
- 관련 문서: [MCP 연결](https://developers.mallstory.co.kr/docs/mcp)

## 2026-10-13 · [변경] 이미지 칸은 어디서 저장하든 파일 키만 믿습니다

- 영역: 이미지 업로드
- 상품 이미지 · 옵션 이미지 · 상품정보제공고시 이미지 · 공통정보 템플릿 이미지 · 카테고리 배너 모두, 저장소 · 경로 · 크기는 이 쇼핑몰의 파일 기록에서 채우고 보낸 값은 버립니다. API 는 전부터 그랬고, 이제 관리자 화면 저장도 같은 규칙입니다.
- 지워진 이미지를 가리키면 400 이고, 문장이 어느 칸인지 말합니다 — "상품 이미지 1번째: 이 쇼핑몰에 올린 이미지가 아니거나 지워진 이미지입니다(…)".
- 관련 문서: [이미지 업로드](https://developers.mallstory.co.kr/docs/files) · [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [공통정보](https://developers.mallstory.co.kr/docs/templates-common) · [상품 카테고리](https://developers.mallstory.co.kr/docs/categories)

## 2026-10-13 · [수정] 카테고리 상단 배너 이미지가 하루 뒤 지워지던 것을 고쳤습니다

- 영역: 상품 관리
- 배너 파일을 카테고리에 붙이지 않아 파일 정리가 하루 뒤 지웠습니다. 이제 저장할 때 카테고리의 파일로 붙고, 배너를 바꾸거나 카테고리를 지울 때만 지워집니다. 이미 지워진 배너는 다시 올려야 합니다.
- 배너 이미지(`top.banner.pc_image` · `mobile_image`)는 **`file_id` 만** 받습니다(문자열 또는 `{"file_id": "…"}`). 보낸 경로 · 주소는 버리고 이 쇼핑몰의 파일 기록에서 채웁니다 — 다른 쇼핑몰 · 지워진 파일이면 400. 업로드 쓰임은 `?usage=category.banner`.
- 관련 문서: [상품 카테고리](https://developers.mallstory.co.kr/docs/categories) · [이미지 업로드](https://developers.mallstory.co.kr/docs/files)

## 2026-10-13 · [호환 깨짐] 판매 상태는 판매자가 고른 값이 최우선입니다

- 영역: 상품 관리
- `status_type` 은 `SALE`(판매중) · `SUSPENSION`(판매중지)만 받습니다 — 관리자 판매상태 탭과 같습니다. `WAIT` · `OUTOFSTOCK` · `CLOSE` 를 보내면 400. 판매기간은 `sale_start_at` · `sale_end_at` 로 넣습니다.
- 재고는 판매중 상품에만 품절(`OUTOFSTOCK`)을 덧씌우고, 재고가 다시 생기면 판매중으로 돌려놓습니다(전에는 재고만 고치면 품절로 남았습니다). 판매중지는 재고를 채워도 그대로입니다.
- 옵션 상품을 저장할 때 옛 판매대기 · 판매종료 값이 판매중으로 덮이던 것도 고쳤습니다.
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [상품 수정](https://developers.mallstory.co.kr/docs/products-update) · [코드값](https://developers.mallstory.co.kr/docs/codes)

## 2026-10-13 · [변경] 배송여부는 배송수단으로 정합니다

- 영역: 상품 관리
- `shippable` 을 보내지 않으면 `delivery` 로 정합니다 — 배송 방식이 하나라도 있으면 배송, 없으면 배송없음. 수정에서 `delivery` 만 보내도 다시 정합니다. 배송 방식 없이 등록하면 배송없음 상품이 됩니다.
- 상품 일괄 처리의 배송 방식 바꾸기가 배송없음 상품도 받습니다(방식을 켜면 배송 상품). 실패 코드 `NotShippable` · `NoDelivery` 는 없어졌습니다.
- 대량구매 할인을 켜면 저장할 때 묶음배송 `POSSIBLE` 을 늘 `PARTIAL` 로 내립니다(할인만 보낸 수정도).
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [상품 수정](https://developers.mallstory.co.kr/docs/products-update) · [상품 일괄 처리](https://developers.mallstory.co.kr/docs/products-bulk)

## 2026-10-13 · [호환 깨짐] 관리자 상품 응답에서 `detail_content` 를 뺐습니다

- 영역: 상품 관리
- 공통정보 템플릿(상단 · 하단)을 저장할 때 합치지 않고 손님 화면이 열 때 붙입니다 — 템플릿을 고치면 그 템플릿을 쓰는 상품에 바로 반영됩니다.
- 관리자 상품 상세 · 목록 · 등록 · 수정 응답에는 본문 `detail_content_body` 만 옵니다. 템플릿을 붙인 상세는 회원 API 상품 상세(`/v1/store/products/{product_no}`)의 `detail_content` 로 읽습니다.
- 관련 문서: [상품 상세](https://developers.mallstory.co.kr/docs/products-detail) · [상품 상세](https://developers.mallstory.co.kr/docs/store-product)

## 2026-10-13 · [변경] 상품 오류 문장 · 이름을 관리자 화면에 맞췄습니다

- 영역: 상품 관리
- 할인 하한: 켠 할인을 모두 더해 한 번 봅니다 — "{할인} 금액은 판매가를 초과할 수 없습니다." / "할인 합계가 판매가와 같거나 초과하였습니다."(`DiscountBelowFloor`).
- "특정기간 할인의 할인기간 (시작일시/종료일시)이 누락되었습니다." · "대량구매 할인의 적용기준 값(수량 · 판매가)이 누락되었습니다."
- 이름: 홍보문구 → **간략소개**(`promotion_text`), 배지(아이콘) → **배지**. 필드 이름 · 값은 그대로입니다.
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [상품 일괄 처리](https://developers.mallstory.co.kr/docs/products-bulk) · [코드값](https://developers.mallstory.co.kr/docs/codes)

## 2026-10-13 · [추가] 요청 ID `X-Request-Id` · 오류 본문의 `request_id`

- 영역: API 공통
- `/v1` · `/mcp` · `/api/oauth` 의 모든 응답 헤더에 `X-Request-Id`, `/v1` 오류 본문에 `request_id` 가 붙습니다. 문의할 때 이 값을 함께 보내 주세요.
- 요청 헤더로 직접 정한 `X-Request-Id`(영문 · 숫자 · `. _ : -` 8 ~ 128자)를 보내면 그 값을 씁니다.
- 관련 문서: [API 호출하기](https://developers.mallstory.co.kr/docs/calling)

## 2026-10-13 · [수정] 권한이 모자랄 때 403 대신 500 이 나던 것을 고쳤습니다

- 영역: API 공통
- `InsufficientScope` 응답의 `WWW-Authenticate` 에 한글 설명을 실어 응답을 만들지 못했습니다. 이제 403 과 `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"` 로 옵니다.
- 관련 문서: [API 호출하기](https://developers.mallstory.co.kr/docs/calling)

## 2026-10-13 · [추가] 상품 일괄 처리 `POST /products/bulk`

- 영역: 상품 관리
- 관리자 상품 목록의 일괄 정보수정 · 전시변경 · 판매변경 · 삭제와 같습니다. 한 번에 1,000개, 일부가 실패해도 200 과 `failed` 로 돌려줍니다.
- 정보수정 항목은 코드값 쪽의 **일괄 수정 항목** 표에 있습니다.
- 관련 문서: [상품 일괄 처리](https://developers.mallstory.co.kr/docs/products-bulk) · [상품 관리](https://developers.mallstory.co.kr/docs/products) · [코드값](https://developers.mallstory.co.kr/docs/codes)

## 2026-10-13 · [호환 깨짐] 상품 등록이 관리자 화면과 같은 필수 조건을 봅니다

- 영역: 상품 관리
- `shippable: true` 인데 배송수단이 없으면 400 입니다. `shippable` 을 보내지 않으면 배송수단으로 정해집니다(같은 날 바뀜 — 아래 "배송여부는 배송수단으로 정합니다").
- `display_status: "PERIOD"` 인데 전시기간이 없거나, 판매기간을 한쪽만 넣거나, `option_info.names` 를 넣고 옵션 행이 없으면 400(`OptionEmpty`).
- 주문 요청사항 · 추가상품의 이름 없는 항목, 값 없는 셀렉트 · 추가상품은 버리지 않고 400 으로 알립니다.
- 할인을 켜고 원 단위 금액이 0 이거나 대량구매 조건의 기준값이 0 이면 400.
- 모든 조건은 상품 등록 쪽의 **구현 규칙**에 있습니다.
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create)

## 2026-10-13 · [호환 깨짐] 상품 등록 · 수정에서 키가 이 쇼핑몰 것인지 확인합니다

- 영역: 상품 관리
- `category_id` · `display_category_ids` · `delivery[].template_id` · `badge_ids` · `color_ids` · `size_template_id` · `review_template_id` · `top_template_ids` · `bottom_template_ids` 가 이 쇼핑몰에 없으면 400 `ReferenceNotFound`.
- 배송 템플릿은 **방식도 맞아야** 합니다(택배배송 칸에 퀵배송 템플릿 불가).
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [상품 수정](https://developers.mallstory.co.kr/docs/products-update)

## 2026-10-13 · [추가] 목록 정렬 `sort` · `order` 를 받습니다

- 영역: 관리자 API
- 상품 목록 · 회원 목록 · 템플릿 목록. 키는 관리자 목록의 정렬과 같고 코드값 쪽의 **목록 정렬** 표에 있습니다. 모르는 키 · 방향은 400.
- 관련 문서: [상품 목록](https://developers.mallstory.co.kr/docs/products-list) · [회원 목록](https://developers.mallstory.co.kr/docs/members-list) · [공통정보](https://developers.mallstory.co.kr/docs/templates-common) · [택배배송](https://developers.mallstory.co.kr/docs/templates-parcel) · [색상](https://developers.mallstory.co.kr/docs/templates-colors) · [코드값](https://developers.mallstory.co.kr/docs/codes)

## 2026-10-13 · [변경] 목록의 기본 순서를 관리자 목록에 맞췄습니다

- 영역: 관리자 API
- 상품 목록: 수정일시 최신순 → **상품 번호 내림차순(최신 등록순)**. 수정일순이 필요하면 `sort=updated`.
- 템플릿 목록(공통정보 · 배송 넷): 이름순(배송은 기본 템플릿 먼저) → **등록일시 최신순**.
- 관련 문서: [상품 목록](https://developers.mallstory.co.kr/docs/products-list) · [공통정보](https://developers.mallstory.co.kr/docs/templates-common) · [택배배송](https://developers.mallstory.co.kr/docs/templates-parcel) · [직접배송](https://developers.mallstory.co.kr/docs/templates-direct) · [퀵배송](https://developers.mallstory.co.kr/docs/templates-quick) · [방문수령](https://developers.mallstory.co.kr/docs/templates-pickup)

## 2026-10-13 · [추가] 이미지 칸에 키 문자열만 보내도 됩니다

- 영역: 이미지 업로드
- `images: ["6acc…"]` · `options[].image: "6acc…"` · `product_info_provided_notice.image` · 공통정보 템플릿 `image`. 기존 `{"file_id": "…"}` 도 그대로 받습니다.
- 관련 문서: [상품 등록](https://developers.mallstory.co.kr/docs/products-create) · [공통정보](https://developers.mallstory.co.kr/docs/templates-common) · [이미지 업로드](https://developers.mallstory.co.kr/docs/files)

## 2026-10-13 · [수정] 한글 파일 이름을 올릴 때 나던 400 을 고쳤습니다

- 영역: 이미지 업로드
- 파일 이름이 한글이면 일부 클라이언트(Postman 등)가 `filename*=UTF-8''…` 를 함께 실어 "업로드 형식이 올바르지 않습니다" 가 났습니다. 이제 그대로 올라갑니다.
- 관련 문서: [이미지 업로드](https://developers.mallstory.co.kr/docs/files)

## 2026-10-13 · [추가] AI 에이전트용 마크다운 원문 · llms.txt

- 영역: AI 에이전트
- 쪽의 마크다운 원문 `/docs/{쪽}.md`(먼저 상품 등록 · 변경 이력)와 문서 목록 `/llms.txt`. 에이전트에게 건넬 주소 · 지시문은 **AI 에이전트로 개발하기** 쪽에 있습니다.
- 관련 문서: [AI 에이전트로 개발하기](https://developers.mallstory.co.kr/docs/ai-agents) · [상품 등록](https://developers.mallstory.co.kr/docs/products-create)

## 2026-10-13 · [추가] 변경 이력 쪽과 피드

- 영역: 참고
- 이 쪽입니다. 구독은 `/changelog.xml`(Atom).
- 관련 문서: [변경 이력](https://developers.mallstory.co.kr/docs/changelog)

## 2026-10-13 · [변경] Postman 컬렉션 · 환경 파일을 나눴습니다

- 영역: 시작하기
- 변수는 **환경 파일**로 따로 받습니다 — 컬렉션을 새로 가져와도 채운 값이 남습니다. 컬렉션 변수에 넣어 둔 값은 환경으로 옮겨 넣습니다.
- 관리자 API 폴더를 문서 메뉴대로 나누고, 상품 등록 6가지 · 템플릿 8종 생성 요청을 더했습니다.
- 관련 문서: [Postman 으로 시험하기](https://developers.mallstory.co.kr/docs/postman)

## 2026-10-13 · [변경] 동의 화면 제목에 앱 이름을 싣습니다

- 영역: 인증
- 소유자 · 회원 동의 화면의 제목이 "[앱 이름] 연결을 승인해 주세요" 입니다. 로그인한 계정 카드 · 돌아갈 주소는 싣지 않습니다.
- 관련 문서: [소유자 동의](https://developers.mallstory.co.kr/docs/authorization) · [회원 동의](https://developers.mallstory.co.kr/docs/member-authorization)

## 2026-10-12 · [추가] 첫 공개 범위

- 영역: 관리자 API
- 관리자 API: 쇼핑몰 정보 · 이미지 업로드 · 상품(목록 · 상세 · 등록 · 수정 · 삭제) · 상품 카테고리 · 템플릿 관리(배송 할증지역 포함) · 회원 · 회원 등급.
- 회원 API: 회원 본인 · 쇼핑몰 화면 조회(`/v1/store` — 상품 목록 · 상세 · 카테고리, 등급가 반영). 회원 로그인(`POST /v1/member/login`).
- MCP: 커넥터 주소 한 줄로 연결(동적 등록 + 로그인 때 쇼핑몰 아이디).