OptionRequest

옵션관리 API에서 사용합니다. 옵션정보와 본상품 재고수량를 포함합니다.

Option

옵션의 type 필드는 필수 값이며, 옵션 없는 상품일 경우 “NONE” type 으로 전송하시면 됩니다.

독립형 옵션일 경우 정렬 기준을 선택할 수 있으며, simpleSortType 필드 (OptionSortType 타입) 의 값이 비어 있을 경우 default (등록순) 기준이 적용 됩니다.

조합형 옵션일 경우 정렬 기준을 선택할 수 있으며,combinationSortType 필드 (OptionSortType 타입)의 값이 비어 있을 경우 default (등록순) 기준이 적용 됩니다.

작성형 옵션일 경우에는 정렬 기준은 default (등록순) 기준이 적용 됩니다.

조합형 옵션일 경우 combinations 필드 (Array<Combinations> 타입) 와 combinationAttributes 필드(Array<CombinationAttribute> 타입) 는 필수 입력 값입니다.

일정형 옵션일 경우 schedule 필드(Schedule 타입)에 일정 설정과 일정가격을 입력합니다. 자세한 규칙은 아래 Schedule 항목을 참고해 주세요.

수정 시 주의사항

상품 수정 또는 옵션 수정 요청 시,기 등록한 옵션의 옵션값 텍스트/재고수량/옵션가격 등 일부 정보를 변경하는 
경우에도 옵션 전체 목록 데이터를 모두 입력해야하며, 모든 옵션의 옵션 id값이 포함되어야 합니다. 

기 등록한 옵션명 하위에 일부 옵션값을 추가/삭제하거나, 옵션명 구분을 추가해야하는 경우에는 옵션 전체 목록을
신규 등록해 주셔야 합니다. 
*조합형 옵션 등록 시, 옵션가 0원인 옵션이 최소 1개 이상 등록되어야 합니다. 
*일정형 옵션은 위 규칙 대신 아래 Schedule 항목의 규칙을 따릅니다.

<옵션 없는 상품 샘플>

{
  "type":"NONE"
}

<독립형 옵션 샘플>

{
  "type":"SIMPLE",
  "simples":[
    {
      "name":"사이즈",
      "value":"M",
      "usable":true
    }
  ]
}

<조합형 옵션 샘플>

{
  "type":"COMBINATION",
  "combinations":[
    {
      "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
      ],
      "price":"0",
      "stockQuantity":50,
      "managedCode":"SY",
      "usable":true,
      "deliveryScheduleType": "NORMAL"
    }
  ],
  "combinationAttributes":[
    {
      "name":"사이즈",
      "value":"M"
    },
    {
      "name":"컬러",
      "value":"RED"
    }
  ],
  "optionDisplay": {
    "useInstantOrder": true,
    "instantOrderTemplateType": "TYPE_1"
  }
}

<작성형 옵션 샘플>

{
  "type":"CUSTOM",
  "customs":[
    {
      "name":"길이를 입력해 주세요.",
      "usable":true
    }
  ]
}

<독립형+작성형 옵션 샘플>

{
  "type":"SIMPLE_CUSTOM",
  "simples":[
    {
      "name":"사이즈",
      "value":"M",
      "usable":true
    }
  ],
  "customs":[
    {
      "name":"길이를 입력해 주세요.",
      "usable":true
    }
  ]
}

<조합형+작성형 옵션 샘플>

{
  "type":"COMBINATION_CUSTOM",
  "combinations":[
    {
      "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
      ],
      "price":"0",
      "stockQuantity":50,
      "managedCode":"SY",
      "usable":true
    }
  ],
  "combinationAttributes":[
    {
      "name":"사이즈",
      "value":"M"
    },
    {
      "name":"컬러",
      "value":"RED"
    }
  ],
  "customs":[
    {
      "name":"길이를 입력해 주세요.",
      "usable":true
    }
  ],
  "optionDisplay": {
    "useInstantOrder": true,
    "instantOrderTemplateType": "TYPE_1"
  }
}

<일정형 옵션 샘플 — 상품 등록·일정형 전환>

{
  "type": "SCHEDULE",
  "schedule": {
    "dateSelectionType": "RANGE",
    "prices": [
      {
        "scheduleDate": "20261105000000",
        "axes": [
          {
            "key": "객실타입",
            "value": "스탠다드"
          }
        ],
        "price": 0,
        "availableQuantity": 5,
        "usable": true
      },
      {
        "scheduleDate": "20261105000000",
        "axes": [
          {
            "key": "객실타입",
            "value": "디럭스"
          }
        ],
        "price": 30000,
        "availableQuantity": 3,
        "usable": true,
        "managedCode": "DLX"
      },
      {
        "scheduleDate": "20261106000000",
        "axes": [
          {
            "key": "객실타입",
            "value": "스탠다드"
          }
        ],
        "price": 20000,
        "availableQuantity": 5,
        "usable": true
      }
    ]
  }
}

샘플의 날짜는 예시입니다. 오늘 이후(1년 이내) 날짜로 바꿔 사용해 주세요. 이미 일정형인 상품의 수정 샘플은 옵션 등록 및 수정 API 문서를 참고해 주세요.

필드상세

OptionType

옵션타입은 크게 선택형과 작성형으로 구분됩니다.

선택형은 주문시 판매자가 미리 설정해둔 옵션 리스트 중에서 구매자가 선택하는 방식이고, 작성형은 주문시 구매자가 주문하려는 옵션 내용을 직접 작성하는 방식입니다.

‘선택형’은 다시 독립형과 조합형으로 옵션형태가 구분되어 선택할 수 있는데, 그중 조합형만 옵션가, 옵션별 재고수량, 옵션별 발송예정일, 옵션 관리코드 및 옵션이미지를 설정할 수 있습니다.

일정형(SCHEDULE)도 날짜별 옵션가와 재고를 설정할 수 있습니다. 아래 Schedule 항목을 참고해 주세요.

OptionSortType

독립형 및 조합형 옵션의 정렬 기준을 나타냅니다.

Simple

필드 제약사항

# 옵션명
  - 컬러, 사이즈, 스타일 등 상품 선택 속성을 의미하는 옵션명은 숫자로만 이루어 질 수 없습니다.
  - 선택형 옵션의 옵션명은 최대 3개까지 등록 가능하며, 옵션명별 하위 옵션값은 최대 100개까지만 등록 가능합니다.

[
  {
    "name":"사이즈",
    "value":"M",
    "usable":true
  }
]

Combination

필드 제약사항

# 옵션가
  - 옵션가는 판매가 -50% 이상 +100% 이하 설정 가능 합니다.
  - 최소 10원 단위 설정 가능합니다.
  - 마이너스 옵션가 등록 시도시 즉시할인 설정 체크하여 ‘(판매가+마이너스옵션가(최대값))-즉시할인’ 금액이 마이너스인 경우 
설정 불가 합니다.

# 재고수량
  - 재고수량은 최소 0개 이상 최대 9999개 이하로 설정 가능합니다. 단, 0개로 설정 시 해당 옵션은 '품절' 상태로 노출됩니다.

# 문자열 길이제한
  - 선택형,조합형, 작성형 옵션명은 25자까지 입력 가능합니다.
  - 선택형,조합형 옵션값은 25자까지 입력 가능합니다.

# 옵션 등록 갯수 제한
  - 컬러, 사이즈, 스타일 등 상품 선택 속성을 의미하는 옵션명은 최대 3개까지 등록 가능하며, 옵션명별 하위 옵션값은 
최대 100개 까지만 등록 가능합니다.
  - 상품의 하위 최종 옵션 갯수는 최대 1000개로 제한됩니다.

# 오늘출발 가능옵션 여부
  - 배송유형이 오늘출발이고 & 조합형 옵션이면서 & 오늘출발 가능 일부옵션(deliveryScheduledPerOption)
   설정이 true일 때만 설정 가능 합니다.

[
  {
    "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
    ],
    "price":300,
    "stockQuantity":50,
    "managedCode":"SY",
    "usable":true,
    "deliveryScheduleType": "NORMAL"
  }
]

CombinationAttribute

필드 제약사항

# 옵션명
  - 상품 선택 속성을 의미하는 옵션명은 숫자로만 이루어 질 수 없습니다.

# 옵션이미지 설정
  - 조합형 옵션의 최상위 옵션명 하위 옵션값 단위로 옵션이미지 설정이 가능합니다. 
  설정 시, 상품상세 옵션 선택 영역에 해당 이미지가 함께 노출됩니다.
  - 옵션이미지를 설정한 경우, '옵션 바로구매' 설정이 가능합니다. 
  상품상세설명 하단에 옵션별 이미지/상세 이미지/옵션 추가금액 및 옵션별 구매 버튼이 노출되어 옵션 선택이 편리합니다.
  - 옵션상세이미지까지 등록하시면 옵션바로구매 영역에 [자세히] 버튼을 해당 이미지 확인이 가능합니다.

# 옵션이미지/상세이미지 제약사항
  - 옵션이미지 : 1:1 비율로 고정 노출
  - 옵션상세이미지 : 최대 3개까지 등록가능
  - 외부 이미지의 경우, UTF-8 방식을 사용해서 인코딩된 URL만 허용합니다. 

[
  {
    "name":"사이즈",
    "value":"M",
    "optionImage": {
      "representImage": {
        "url":"https://st.kakaocdn.net/shoppingstore/product/a.png"
      },
      "optionalImages": [
        {
          "url":"https://st.kakaocdn.net/shoppingstore/product/b.png"
        },{
          "url":"https://st.kakaocdn.net/shoppingstore/product/c.png"
        }
      ]
    }
  },
  {
    "name":"사이즈",
    "value":"L",
    "optionImage": {
      "representImage": {
        "url":"https://st.kakaocdn.net/shoppingstore/product/a.png"
      },
      "optionalImages": [
        {
          "url":"https://st.kakaocdn.net/shoppingstore/product/b.png"
        },{
          "url":"https://st.kakaocdn.net/shoppingstore/product/c.png"
        }
      ]
    }
  },
  {
    "name":"컬러",
    "value":"RED"
  }
]

Custom

필드 제약사항

# 옵션명
  - 상품 선택 속성을 의미하는 옵션명은 숫자로만 이루어 질 수 없습니다.
  - 작성형 옵션명은 최대 5개 까지 등록 가능합니다.

[
  {
    "name":"사이즈를 입력해주세요.",
    "usable":true
  },
  {
    "name":"컬러는 어떤걸 하시겠습니까?",
    "usable":true
  }
]

OptionDisplay

필드 제약사항

# 옵션 바로구매
  - 조합형 옵션에 옵션 이미지를 등록하신 경우에만 설정이 가능합니다.

{
  "useInstantOrder": true,
  "instantOrderTemplateType": "TYPE_1"
}

InstantOrderTemplateType

useShippingDueDate

필드 제약사항

• useShippingDueDate 필드를 true로 설정하면 발송예정일 옵션을 사용할 수 있습니다. 
• 이 경우, 조합형 옵션 컬럼의 마지막 항목에 반드시 발송예정일을 포함해야 합니다. 
• 설정 가능한 발송예정일 유형은 즉시 순차 발송, 날짜 지정 선택 2가지입니다.

발송예정일 설정 방법
• 즉시 순차 발송을 설정하려면 value 값에 "즉시 순차 발송" 입력
• 날짜 지정 발송을 설정하려면 value 값에 "yyyyMMddHHmmss" 형식의 날짜를 입력
• 날짜는 설정 시점 기준, 최소 1일 ~ 최대 30일 이내로 설정. 시/분/초는 23시 59분 59초로 입력
- 예시: "20251030235959" (2025년 10월 30일 23시 59분 59초)

<요청 바디샘플>

{
    "type": "COMBINATION",
    "combinations": [
        {
            "name": [
                {
                    "key": "사이즈",
                    "value": "M"
                },
                {
                    "key": "컬러",
                    "value": "RED"
                },
                {
                    "key": "발송예정일",
                    "value": "즉시 순차 발송"
                }
            ],
            "price": "0",
            "stockQuantity": 50,
            "usable": true
        },
        {
            "name": [
                {
                    "key": "사이즈",
                    "value": "M"
                },
                {
                    "key": "컬러",
                    "value": "RED"
                },
                {
                    "key": "발송예정일",
                    "value": "20251030235959"
                }
            ],
            "price": "0",
            "stockQuantity": 50,
            "usable": true
        }
    ],
    "combinationAttributes": [
        {
            "name": "사이즈",
            "value": "M"
        },
        {
            "name": "컬러",
            "value": "RED"
        },
        {
            "name": "발송예정일",
            "value": "즉시 순차 발송"
        },
        {
            "name": "발송예정일",
            "value": "20251030235959"
        }
    ],
    "optionDisplay": {
        "useInstantOrder": true,
        "instantOrderTemplateType": "TYPE_1"
    },
    "useShippingDueDate": true
}

Reservation

필드 제약사항

• 사용일 옵션은 여행/숙박/이용권/e쿠폰 등 예약속성 카테고리이고 & 조합형 옵션 상품에만 설정할 수 있습니다. 
  - 사용일 옵션이란? 유저가 구매시점에 상품의 실제 사용일을 직접 선택하여 구매 가능하도록 날짜형식으로 
  등록한 조합형 옵션을 의미합니다. (ex. 숙박일, 여행 출발일)
  
• 사용일 옵션 설정 시, 아래 사항을 준수해야 합니다. 
 - 조합형 첫번째 옵션값에만 사용일 옵션 설정이 가능합니다. 
 - 사용일 옵션값은 최소 1개 ~ 최대 100개까지만 설정 가능합니다. 
 - 사용일 옵션값은 당일 ~ + 180일까지의 날짜만 설정 가능합니다. 
 - 사용일 옵션값은 상품 판매기간의 시작일시보다 과거 날짜로 설정이 불가합니다. 
 - 사용일 옵션값은 "yyyyMMddHHmmss" 형식의 날짜를 입력해야 하고,
   이때 시/분/초는 반드시 '23시 59분 59초'로 입력해야 합니다.  
   예시) "20251030235959" (2025년 10월 30일 23시 59분 59초)

DateSetType

<요청 바디샘플>

{
  "type": "COMBINATION",
  "reservation": {
    "useUsageDate": true,
    "dateSetType": "LIST"
  },
  "combinationSortType": "CREATE",
  "combinationAttributes": [
    {
      "name": "사용일",
      "value": "20251212235959",
      "optionImage": {}
    },
    {
      "name": "사용일",
      "value": "20251213100000",
      "optionImage": {}
    }
  ],
  "combinations": [
    {
      "name": [
        {
          "key": "사용일",
          "value": "20251212235959"
        }
      ],
      "usable": true,
      "price": 100000,
      "stockQuantity": 1,
      "saleStatus": "ON_SALE"
    },
    {
      "name": [
        {
          "key": "사용일",
          "value": "20251213100000"
        }
      ],
      "usable": true,
      "price": 100000,
      "stockQuantity": 1,
      "saleStatus": "ON_SALE"
    }
  ]
}

deliveryScheduledPerOption

필드 제약사항

• 일부 조합형 옵션의 '오늘출발 가능옵션 여부'를 설정하기 위해서는 
'오늘출발 가능 일부옵션 설정(deliveryScheduledPerOption)'을 true로 설정해야 합니다. 

<요청 바디샘플>

 {
  "type":"COMBINATION",
  "combinations":[
    {
      "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
      ],
      "price":"0",
      "stockQuantity":50,
      "managedCode":"SY",
      "usable":true,
      "deliveryScheduleType": "TODAY_DEPARTURE"
    }
  ],
  "combinationAttributes":[
    {
      "name":"사이즈",
      "value":"M"
    },
    {
      "name":"컬러",
      "value":"RED"
    }
  ],
  "optionDisplay": {
    "useInstantOrder": true,
    "instantOrderTemplateType": "TYPE_1"
  },
  "deliveryScheduledPerOption": true
}

deliveryScheduleType

필드 제약사항

• 오늘출발 가능 일부옵션 설정(deliveryScheduledPerOption)이 true일 때만 설정 가능 합니다.
• 배송유형이 오늘출발이고 & 조합형 옵션이면서 & 오늘출발 가능 일부옵션(deliveryScheduledPerOption)
설정이 true일 때만 설정 가능 합니다.
• 데이터가 없는 경우, 해당 상품의 배송유형(delivery>scheduleType) 속성과 동일하게 설정됩니다. 

<요청 바디샘플>

 [
  {
    "name":[
        {
          "key":"사이즈",
          "value":"M"
        },
        {
          "key":"컬러",
          "value":"RED"
        }
    ],
    "price":300,
    "stockQuantity":50,
    "managedCode":"SY",
    "usable":true,
    "deliveryScheduleType": "TODAY_DEPARTURE"
  }
]

Schedule

일정형(SCHEDULE) 옵션의 일정 정보입니다. 여행·숙박처럼 날짜별로 옵션가와 재고를 관리하며, 카테고리 조회 응답의 scheduleOptionSupported 가 true 인 카테고리에서만 사용할 수 있습니다. 상품 조회 응답에는 포함되지 않고 옵션 조회 응답에 포함됩니다.

일정형 옵션은 날짜 옵션에 추가 옵션(객실 타입 등, 최대 3개)을 조합해 등록하는 일정 기반 옵션입니다(예: 숙박일, 여행 출발일). 추가 옵션은 조합형 옵션처럼 옵션명·옵션값으로 정하며, 독립형·작성형 옵션과 함께 쓸 수 없습니다.

등록/수정 시 주의사항

• 상품 등록: 옵션의 type 이 SCHEDULE 이면 schedule 이 필수이며, 상품과 일정형 옵션이 한 번에 저장됩니다. 상품 수정 요청에는 schedule 을 넣지 않습니다(넣으면 오류).
• 옵션 등록 및 수정: 일반 상품을 일정형으로 바꿀 때 필수입니다. 이미 일정형인 상품은 선택이며, 없으면 일정을 바꾸지 않습니다. schedule 이 있으면 prices 로 일정 전체를 교체하고, prices 를 생략하면 일정가격은 그대로 두고 일정 설정만 저장합니다.
• 상품 등록 시 또는 일반 상품을 일정형으로 바꿀 때는 모든 일정이 새로 등록되므로 scheduleOptionId 와 baseModifiedAt 을 넣지 않습니다.
• 이미 일정형인 상품의 일정을 수정할 때는 옵션 조회 응답의 scheduleOptionId 와 baseModifiedAt 을 그대로 넣습니다. scheduleOptionId 를 넣은 일정은 그 일정을 수정하고(추가 옵션값은 바꿀 수 있고 날짜는 바꿀 수 없음), 비워 둔 일정은 날짜·추가 옵션값이 같은 기존 일정을 수정하거나 없으면 새로 등록합니다. 요청에 없는 기존 일정은 삭제됩니다.
• 지난 날짜의 일정이 있으면 조회 응답의 usable 값을 그대로 보내 주세요. usable 을 생략하면 true 로 처리되어, 사용안함인 지난 일정은 오류(scheduleOption.usable.pastReactivation)가 납니다.
• 옵션의 type 이 SCHEDULE 이면 simples·combinations·combinationAttributes·customs·simpleSortType·combinationSortType 은 저장되지 않으니 빼고 보내 주세요.

필드 상세

SchedulePrice

날짜와 추가 옵션 조합 하나의 옵션가·재고·사용여부입니다.

필드 제약사항

# 날짜
  - 날짜 옵션명은 항상 "날짜" 로 고정됩니다. 등록·수정 때 보낸 값은 무시됩니다.
  - scheduleDate 는 yyyyMMddHHmmss 형식이며 날짜만 사용합니다. 예) 20261105000000
  - 새로 추가하는 날짜는 오늘부터 1년 뒤 같은 날(그날 포함)까지 설정할 수 있고, 판매기간을 설정한 상품은 판매 시작일 이후여야 합니다. 
    이미 등록된 일정을 수정할 때는 날짜 범위를 검사하지 않습니다.
    
# 옵션가(price)
  - price 는 판매가가 아니라 판매가에 더하는 날짜별 증감액입니다. 
  - 옵션가는 판매가 -50% 이상 +100% 이하 설정 가능 합니다. (옵션 정책이 완화된 일부 카테고리는 +500% 이하). 
    날짜가 오늘 이후(오늘 포함)인 옵션은 사용여부와 관계없이 검사하며, 벗어나면 scheduleOption.price.range 오류가 발생합니다. 
  - 마이너스 옵션가 등록 시도시 상품에 설정된 할인 설정(즉시할인/관리자 할인/소문내면 할인/톡딜 할인 등) 체크하여 ‘(판매가+마이너스옵션가(최대값))-상품 할인’ 금액이 100원 이상이어야 하며,
    마이너스인 경우 option.negative 오류 발생하여 설정 불가 합니다.
    예시) 판매가 1,000원, 즉시할인 600원, 옵션가 -450원 설정 시, 1000-450-600 = -50원 이므로 설정 불가. 
  - 사용여부(usable)가 true 이면서 price가 0원인 옵션이 1개 이상 있어야 합니다.
  
# 재고(availableQuantity)
  - 0 이상 99,999,999 이하로 설정할 수 있습니다. 단, 0개로 설정 시 해당 옵션은 '품절' 상태로 노출됩니다.
  - 날짜별 하위옵션 재고 모두 0개로 설정 시 해당 옵션은 날짜 선택 시부터 '품절(예약마감)' 상태로 노출됩니다. 
  
# 사용여부(usable)
  - 생략하면 true 로 처리됩니다. false 이면 해당 옵션은 노출되지 않으며 구매할 수 없습니다.
  - 날짜가 지난 일정은 매일 00시에 자동으로 '사용안함(usable=false) 처리됩니다. 과거 날짜로 사용안함 처리된 옵션은 다시 사용(true) 상태로 변경할 수 없습니다.
  
# 추가 옵션(axes)
  - 추가 옵션은 일정마다 최대 3개입니다. 
  - 옵션명/값은 각각 25자 이내여야 합니다.
  - 날짜만 있는 상품은 axes를 빈 배열로 보내며, 추가 옵션이 있는 일정과 섞을 수 없습니다.

# 등록 개수
  - 일정가격은 상품당 최대 3,000개이며, 동일한 날짜/추가 옵션 조합은 중복으로 넣을 수 없습니다.

필드 상세

ScheduleAxis

ScheduleAxisDefinition

응답 전용 축 정의입니다. 조합형의 combinationAttributes 처럼 선택 가능한 축과 값을 보여 줍니다. 날짜축은 order 0, dateAxis true 이며 값은 scheduleDate 입니다.

DateSelectionType

DateInputType

판매자센터 화면에서 사용 가능일을 입력하는 방식입니다. 구매자 화면에는 영향을 주지 않습니다.