상품 옵션 구성

상품 옵션을 어떻게 구성하는지 설명합니다. 옵션명마다 조합과 추가 선택 중 하나를 고르고, 구매자가 글자를 적는 직접 입력 항목을 따로 둘 수 있습니다. 재고 변경과 판매 상태는 상품·옵션·재고 관리를 봅니다.

준비

• 권한: 소유자·관리자·스태프 또는 product:rw(조회는 product:r)
• 상품 폼의 옵션 섹션에서 설정합니다. API는 POST /v1/products, PUT /v1/products/{productId}, PUT /v1/products/{productId}/options입니다.

1. 옵션명의 두 방식

• 옵션명마다 값은 100개까지입니다. 앞뒤 공백은 지우고, 빈 값은 받지 않습니다. 대소문자만 다른 값(Box·box)은 같은 값으로 봅니다.
• 옵션명은 방식과 관계없이 상품 안에서 겹칠 수 없습니다.
• 조합이 100개를 넘으면 상점 플랫폼이 경고합니다. 조합이 많을수록 재고 관리가 어려워집니다.

조합

색상 × 사이즈처럼 값마다 재고가 따로 있어야 할 때 씁니다. 조합마다 추가금·재고·SKU를 둡니다. 주문에 담긴 조합은 지울 수 없습니다(409 OPTION_HAS_ORDERS). 더 팔지 않을 조합은 판매를 끕니다(usable: false). 조합 응답의 hasOrders가 true이면 주문에 담긴 조합입니다. 상점 플랫폼은 판매 이력이 없는 조합은 바로 지우고, 판매 이력이 있는 조합은 판매 끄기로 안내합니다.

조합에는 속성(attributes)을 둘 수 있습니다. 키(영문 소문자로 시작하는 영숫자·밑줄 40자)와 값(100자) 문자열이고 조합마다 10개까지입니다. 공연 회차 일시처럼 조합마다 다른 사실을 적습니다({ "showAt": "2026-10-20T10:00:00Z" }). 수정에서 생략하면 지금 값을 유지하고 {}이면 비웁니다. 주문상품에는 주문 시점의 속성이 남습니다.

추가 선택

재고가 따로 없는 부가 선택에 씁니다(선물 포장, 각인 서체, 쇼핑백). 값을 고르면 값의 추가금이 단가에 더해지고, 재고는 고른 조합에서 빠집니다. 옵션이 조합 없이 추가 선택뿐이면 상품 재고 하나를 함께 씁니다.

• 필수 선택: 켜면 구매자가 반드시 값을 골라야 담을 수 있습니다. 끄면 고르지 않아도 됩니다(API 필드 required).
• 값 사용: 끈 값은 구매자 화면에서 빠집니다. 끈 값을 담아 둔 장바구니 줄은 구매할 수 없는 줄로 보입니다.
• 재고가 따로 있어야 하는 부가 품목(수량이 정해진 사은품 등)은 추가 선택으로 다루지 않습니다. 조합으로 만들거나 별도 상품으로 등록합니다.

2. 직접 입력

구매자가 글자를 적는 항목입니다(각인 문구, 선물 메시지). 상품마다 5개까지 둡니다.

값은 늘 문자열로 보내고 서버가 타입대로 검사해 저장합니다.

이미지는 POST /storefront/v1/uploads/order-inputs로 업로드 자리를 받아 응답 uploadUrl에 파일을 PUT한 뒤, url을 값에 넣습니다. 이 상점의 주문 입력 업로드 주소가 아니면 400 CUSTOM_INPUT_INVALID입니다. 회원·비회원 모두 쓸 수 있습니다.

상품 수정에서 key·type·options를 생략하면 지금 값을 유지합니다. 타입을 select 밖으로 바꾸면 선택지가 지워집니다. 주문상품에는 주문 시점의 키와 타입이 함께 남습니다.

• 항목별 추가금은 없습니다. 추가금이 필요하면 추가 선택을 함께 둡니다.
• 개인정보는 직접 입력으로 받지 않습니다. 항목명에 연락처·전화·이메일·주소·주민 같은 말이 들어가면 저장되지 않습니다(400 CUSTOM_INPUT_LABEL_FORBIDDEN). 받는 분 정보는 주문의 배송지로 받습니다.

3. 정렬 순서

값을 구매자에게 보일 순서입니다. 상품 하나에 한 가지를 고릅니다.

추가금이 같으면 등록순입니다. API 필드는 optionSort(REGISTERED·NAME·PRICE_ASC·PRICE_DESC)입니다.

4. 구매자 화면과 주문

• 단가 = 판매가(할인 반영) + 조합 추가금 + 고른 추가 선택 추가금입니다. 쿠폰·환불은 이 단가로 계산한 줄 금액을 기준으로 합니다.
• 추가 선택이나 직접 입력값이 다르면 장바구니에서 다른 줄입니다. 같으면 수량이 합쳐집니다.
• 주문상품에는 주문 시점의 옵션명·값·추가금과 직접 입력 항목명·값이 남습니다. 나중에 옵션을 고쳐도 지난 주문의 표시는 바뀌지 않습니다.
• 관리 API 주문상품의 optionSelections·customInputs와 웹훅 ORDER.PAID의 itemOptions(주문상품별 같은 값)로 볼 수 있습니다. 각인처럼 셀러가 작업해야 하는 값을 이것으로 받습니다.

스토어프론트를 직접 만든다면 상품 상세의 addonGroups·customInputs를 그리고, 장바구니 담기와 바로 구매에 addons·customInputs를 보냅니다. 직접 입력값에는 구매자가 적은 글이 들어가므로 URL 검색 파라미터·브라우저 저장소·로그에 두지 않고 요청 본문으로만 보냅니다.

await client.cart.addItem({
  productId,
  optionId: variantId,
  quantity: 1,
  addons: [{ groupId: wrapGroupId, valueId: boxValueId }],
  customInputs: [{ inputId: engraveInputId, value: "FOR MOM" }],
});

같은 조합이 여러 줄에 있는 주문서에서 상품 쿠폰을 걸 줄은 주문서 줄의 lineId로 지목합니다. 쿠폰

5. 저장 옵션

자주 쓰는 옵션 구성을 이름 붙여 저장해 두고 상품 등록에서 불러옵니다. 상점 플랫폼에서 상점 관리 › 상품 › 옵션 관리로 이동합니다.

• 저장하는 것: 옵션명·방식·값·값별 추가금, 추가 선택의 필수 여부, 직접 입력 항목, 정렬 순서
• 저장하지 않는 것: 재고, SKU, 사용 여부. 상품마다 다르기 때문입니다.
• 이름은 50자까지이고 상점 안에서 겹칠 수 없습니다(대소문자·앞뒤 공백 무시). 상점당 200개까지입니다.

불러오기는 복사입니다. 불러오면 상품 폼의 옵션 입력이 채워질 뿐이고, 저장 옵션을 고치거나 지워도 이미 불러온 상품의 옵션은 바뀌지 않습니다. 목록의 불러온 상품은 이 저장 옵션을 불러와 저장한 상품 수입니다. 같은 상품은 한 번만 세고, 지운 상품은 빠집니다.

상품 폼의 옵션 섹션에서 옵션 불러오기를 누르면 저장 옵션이나 다른 상품의 옵션을 골라 입력을 채웁니다.

상품에서 저장

상품 폼의 옵션 섹션에서 저장 옵션으로 저장을 누르면 지금 옵션을 저장 옵션으로 만듭니다. 조합 추가금은 값별 추가금으로 되돌려 저장합니다. 예를 들어 블랙 +0·화이트 +500 × S +0·L +1,000이면 네 조합의 추가금이 값 추가금의 합과 같아 그대로 저장됩니다. 블랙 / L만 +3,000처럼 조합마다 제각각이면 값별로 되돌릴 수 없어 추가금을 빼고 저장하고, 그 사실을 알려 줍니다.

API: /v1/saved-option-sets(목록·만들기·조회·수정·삭제), 상품에서 저장은 POST /v1/saved-option-sets/from-product입니다. 상품을 저장할 때 본문의 sourceOptionSetIds에 불러온 저장 옵션 id를 넣으면 불러온 상품 수에 들어갑니다.