...
{
"id": 14817,
"name": "가구/홈데코",
"level": 1,
"parentId": null,
"isLeaf": false,
"policy": null
}
...
...
{
"id": 14819,
"name": "가구",
"level": 2,
"parentId": 14817,
"isLeaf": false,
"policy": null
}
...
...
{
"id": 14835,
"name": "리클라이너",
"level": 3,
"parentId": 14819,
"isLeaf": true, // 마지막 단계
"policy": {
"isCultureDeductionTarget": false,
"discountLimitPercentage": null
}
...
{
"resultType": "SUCCESS",
"success": {
"categoryName": "가구/홈데코 > 가구 > 리클라이너",
"categoryId": 14835,
// 카테고리 옵션 정보
"categorySalesOptions": [
{
"id": 1,
"key": "색상",
"valueCandidates": [], // 자유롭게 입력할 수 있습니다.
"isOption": false, // 상품등록 API에 필수로 입력합니다.
"placeholder": "",
"unitValues": null,
"keyComment": null,
"valueComment": null,
"isOneOfRequiredGroup": false
}
],
// 검색 옵션 정보
"categorySearchOptions": [
{
"key": "책상/PC용 의자종류",
"valueCandidates": [
"사무/학생용의자",
"게이밍의자",
"중역의자",
"좌식의자",
"아동용의자"
], // 보기 중 하나를 선택해 입력합니다.
"isOption": true,
"placeholder": "선택해주세요",
"unitValues": null,
"keyComment": null,
"valueComment": null
},
{
"key": "가로길이",
"valueCandidates": [],
"isOption": true,
"placeholder": "",
"unitValues": [
"cm",
"mm",
"m",
"km"
],
"keyComment": null,
"valueComment": "[단위수량 옵션정보 입력안내]\\n'숫자+단위' 형식으로만 입력가능합니다.\\n\\n[입력가능단위]\\nmm, cm, m, km\\n\\n[입력가이드]\\n1. 상세정보 또는 이미지에 나온 가로 길이를 단위(mm, cm)와 함께 작성하세요.\\n\\n※ 도마 상품의 경우, 길이는 더 긴 사이드의 길이를 기준으로 작성\\n※ 패션 상품의 경우, 대부분 A가로xB세로xC높이로 표기되기 때문에 A를 가로로 작성\\n※ 가구 상품의 경우, '최대 사이즈'를 작성\\n※ 매트 상품의 경우\\n일반 매트 : 길이가 '긴면'을 가로로 작성\\n롤타입 : '폭 또는 가로' 라고 명시되어 있으면 가로길이로 작성하며, 명시 없을경우 '긴면'을 가로길이로 작성\\n※ 캠핑테이블의 경우\\n- 가로x세로 정보가 없는 경우 펼쳤을때 가장 긴 길이 기준으로 작업 (II: 137611629 > 60cm 로 작업)\\n- 쿠킹테이블과 같이 조립하여 하나가되는 테이블의 경우에도 완성했을때 가장 긴 길이 기준으로 작업 (II: 5141110810 > 138cm로 작업)\\"\\"\\"\\"\\n※고양이화장실의 경우\\n- 이미지 상 가로, 세로 구분이 가능한 경우 가로 길이 입력\\n- 이미지 상 가로, 세로 구분이 불가능한 경우 A x B x C 표기 중 A 입력\\n※ 베개/바디필로우 상품의 경우, 길이는 더 긴 사이드의 길이를 기준으로 작성\\n※ 접이식 캠핑침대 상품의 경우 접었을 때 더 긴 사이즈를 기준으로 작성 \\n※ 포장 관련 상품의 경우 위 아래의 가로길이가 상이한 경우 짧은쪽으로 작성\\n※ 밀대 상품의 경우 \\"\\"밀대판\\"\\"의 가로길이를 작성해주세요."
}
],
"productNoticeInfoTemplateTypes": [
"FURNITURE",
"ETC_GOODS"
]
}
}
| 응답 필드 | 설명 |
|---|---|
구매옵션 ( | 색상, 사이즈, 수량 등 구매자에게 제공하는 상품의 선택지입니다. |
검색옵션 ( | 검색 알고리즘에 활용됩니다. 정보가 많을 수록 검색 맞춤 추천에 유리해요. |
| 필드명 | 설명 |
|---|---|
key | 상품 옵션명입니다. |
isOption | 상품 등록할 때 옵션의 필수・선택 여부를 나타내요. 상품 등록 API의 stocks.options.groupName에 사용됩니다.- false: 상품등록할 때 필수 옵션입니다.- true: 상품등록할 때 선택 옵션입니다. |
valueCandidates | 상품 옵션으로 사용할 수 있는 value 값의 목록입니다. valueCandidates 에 빈 배열이 돌아오면 판매자가 원하는 옵션을 자유롭게 입력할 수 있어요. |
unitValues | 상품 옵션으로 사용할 수 있는 value의 단위입니다. unitValues 에 값이 있다면 상품 옵션 값으로 반드시 숫자를 입력해야 돼요. |
.png?alt=media&token=a81c8008-4f16-4afb-89fd-a262d29fc108)
{% endhint %}
## 배송 묶음그룹 등록 및 조회하기
배송 묶음그룹을 지정하면 여러 상품을 한 번에 배송하고 배송비를 절감할 수 있어요. 같은 배송 묶음그룹 ID로 설정된 상품은 같이 배송돼요. [배송비 묶음그룹 ID 조회 API](https://shopping-docs.toss.im/dev/api-2/delivery#get-api-v3-shopping-fep-merchants-group-delivery-delivery-location-v2)로 기존에 등록된 배송 묶음그룹 ID를 확인해주세요.
**GET** `api/v3/shopping-fep/merchants/group-delivery/delivery-location/v2`
{% code title="요청" %}
```bash
curl --request GET \
--url 'https://shopping-fep.toss.im/api/v3/shopping-fep/merchants/group-delivery/delivery-location/v2\
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json'
```
{% endcode %}
{% code title="응답" %}
```bash
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "string"
},
"success": {
"items": [
{
"id": 1001,
"name": "기본 배송 그룹",
"isMain": true
}
],
"nextToken": "eyJpZCI6MTAwMX0=",
"hasNext": true
}
}
```
{% endcode %}
응답의 `items.id` 를 나중에 상품 등록 API `deliveryPolicy.deliveryLocationId`의 값으로 사용해주세요. 이 값을 `null` 로 두면 개별배송돼요.
{% hint style="info" %}
아직 배송 묶음그룹을 등록하지 않았어요
등록된 배송 묶음그룹 ID가 없으면 토스쇼핑 파트너스 > 좌측 목록 '셀러 정보' > 배송·교환·반품 정보 > [배송 정보](https://shopping-seller-alpha.toss.im/group-delivery) 페이지나 [배송비 묶음그룹 ID 등록 API](https://shopping-docs.toss.im/dev/api-2/delivery#post-api-v3-shopping-fep-merchants-group-delivery-delivery-location)로 배송 묶음그룹을 등록해주세요.
.png?alt=media&token=554f5919-91a9-4c76-aaf2-fec9ee8c0b82)
{% endhint %}
## 상품 등록하기
앞 단계에서 필요한 정보를 모두 확인했다면, 이제 등록 요청을 보낼 수 있어요.
이 가이드에서는 아래 파라미터를 설정하는 방법에 대해서 알아봤어요. 이 외에도 필요한 파라미터는 [상품 등록 API](https://shopping-docs.toss.im/dev/api-2/product)를 참고해주세요.
* `categoryID`: [상품 카테고리 ID](#undefined-3)
* [`stocks`](#undefined-4)
* `stocks.options.groupName`: 구매옵션 그룹 이름
* `stocks.options.valueName`: 구매옵션 입력 값
* `stocks.searchOption.searchOptionWithValue`: \[키: 검색옵션 이름, 값: 검색옵션 값]
* [`deliveryPolicy`](#undefined-9)
* `deliveryPolicy.deliveryLcationId` : 배송 묶음 그룹 ID
* [`exchangeReturnPolicy`](#undefined-8)
* `exchangeReturnPolicy.exchangeRefundLocationId`: 교환반품지 ID
* `notice`
* `notice.categoryCode` : [고시 카테고리 코드](#undefined-6)
* `notice.items.id` : [고시 항목 ID](#undefined-7)
* `notice.items.content` : 고시 항목 내용
{% hint style="info" %}
상품 등록 API 호출 제한\
상품 등록/수정시에는 초당 10건 이하로 요청해주세요. 초과시에는 호출이 실패할 수 있어요.
{% endhint %}
**POST**`/api/v3/shopping-fep/products/v2`
**Request**
{% code expandable="true" %}
```json
{
"name": "토스 리클라이너", // 필수, 상품명
"brandName": "토스", // 선택, 브랜드명
"categoryId": "14835", // 필수, 카테고리 ID
"stocks": [
{
"options": [ // 옵션 그룹명 및 값은 카테고리 제약 사항에 따라 제한됩니다
{
"groupName": "색상",
"valueName": "검정"
}
],
"searchOption": {
"searchOptionWithValue": {
"가로길이": "50cm",
"책상/PC용 의자종류": "사무/학생용의자"
}
}
"remainingCount": 99, // 필수, 재고 수량
"isHide": false, // 필수, 숨김 여부
"isMainPrice": true, // 필수, 대표 가격 여부, stocks 중 최소 1개는 true여야합니다.
"isSoldOut": false, // 필수, 품절 여부
"originPrice": 20000, // 필수, 정상가
"salePrice": 18000, // 필수, 판매가
"isPurchasableAlone": true,// 선택, 단독 구매 가능 여부
"managementCode": "ABC-1234", // 선택, 옵션 관리 코드
"representativeThumbnailImage": "이미지url" // 선택, 옵션 별 대표 썸네일 이미지 url
},
{
"options": [ // 옵션 그룹명 및 값은 카테고리 제약 사항에 따라 제한됩니다
{
"groupName": "색상",
"valueName": "파랑"
}
],
"searchOption": {
"searchOptionWithValue": {
"가로길이": "50cm",
"책상/PC용 의자종류": "사무/학생용의자"
}
}
"remainingCount": 99, // 필수, 재고 수량
"isHide": false, // 필수, 숨김 여부
"isMainPrice": false, // 필수, 대표 가격 여부, stocks 중 최소 1개는 true여야합니다.
"isSoldOut": false, // 필수, 품절 여부
"originPrice": 22000, // 필수, 정상가
"salePrice": 20000, // 필수, 판매가
"isPurchasableAlone": true,// 선택, 단독 구매 가능 여부
"managementCode": "ABC-1235", // 선택, 옵션 관리 코드
"representativeThumbnailImage": "이미지url" // 선택, 옵션 별 대표 썸네일 이미지 url
}
],
"images": [
{
"type": "THUMBNAIL", // 필수, 이미지 유형 (THUMBNAIL, DESCRIPTION, AD, DESCRIPTION_HTML)
"url": "이미지 url", // 선택, 최대 255자
"order": "0" // 필수, 정렬 순서 (0부터 증가)
},
{
"type": "DESCRIPTION", // 필수, 이미지 유형 (THUMBNAIL, DESCRIPTION, AD, DESCRIPTION_HTML)
"url": "이미지 url", // 선택, 최대 255자, url
"order": "1" // 필수, 정렬 순서 (0부터 증가)
}
],
"exposure": {
"searchKeywords": ["리클라이너", "의자"], // 필수, 검색 키워드 리스트, 없으면 emptyList로 요청. 키워드 당 1~10 글자 허용
"description": "토스 쇼핑의 리클라이너 입니다", // 필수, 상품 설명
"serialNumber": "a1234" // 선택, 모델명 허용 정규식: [0-9a-zA-Z가-힣 -_]{1,5
},
"isTaxFree": false, // 필수, 면세 여부
"deliveryPolicy": {
"deliveryMethod": "NORMAL", // 필수, 배송 방식 (NORMAL, TODAY_DELIVERY)
"deliveryDeadline": "14:00", // 선택, 출고 마감 시각 (HH:mm, 30분 단위)
"deliveryLocationId": 1, // 선택, 배송비 묶음 그룹 ID, null이면 묶음배송 불가
"deliveryFeeType": "CONDITIONALLY_FREE", // 필수, 배송비 유형 (FREE, PAID, CONDITIONALLY_FREE) : (무료, 유료, 조건부 무료배송)
"deliveryFee": "1500", // 필수, 기본 배송비
"minimumPurchasePrice": "20000", // 필수, 조건부 무료배송 시 무료배송 조건 금액
"isJejuAndIslandsMountainsDelivery": true, // 필수, 제주/도서산간 배송 가능여부 true/false
"jejuDeliveryFee": 3000, // 필수, 제주도 추가 배송비, isJejuAndIslandsMountainsDelivery 가 true일 경우 적용됩니다.
"islandsMountainsDeliveryFee": 3000 // 필수, 도서 산간 추가 배송비, isJejuAndIslandsMountainsDelivery 가 true일 경우 적용됩니다.
},
"exchangeReturnPolicy": {
"exchangeRefundLocationId": 111, // 조건부필수, 교환/반품지 ID
"refundOneWayDeliveryFee": 1500, // 필수, 반품 편도 배송비
"exchangeRoundTripDeliveryFee": 3000, // 필수, 교환 왕복 배송비
"applicationMethodDescription": "고객센터 연락 후 교환/반품 신청", // 필수, 교환,환불 방법 설명, 500자 이내
"applicationTermDescription": "상품 수령 후 7일 이내" // 필수, 교환,환불 신청 가능 기간 설명, 500자 이내
},
"notice": {
"categoryCode": "CLOTHING", // 필수, 상품 정보제공 고시 카테고리 코드 (아래 참조)
"items": [
{
"id": 27, // 필수, 정보제공 고시 항목 ID
"content": "2025년 11월" // 필수, 고시 항목 내용(판매자 입력 정보) 1~4000자
},
{
"id": 29,
"content": "품질보증기준에 따른 교환/환불 가능"
}
],
"isCultureDeduction": false, // 선택, 문화비 소득공제 가능 여부
"managementCode": "b1234" // 선택, 상품 관리 코드
}
```
{% endcode %}
**Response**
```json
{
"resultType": "SUCCESS",
"error": null,
"success": {
"id": 123 // 생성된 상품 ID
}
}
```
상품 등록에 성공하면 `resultType`필드의 값으로 `SUCCESS` 가 돌아와요. `success` 필드에서는 생성된 상품의 ID를 확인할 수 있어요.
**Error**
```json
{
"resultType": "FAIL",
"error": {
"errorType": 0,
"errorCode": "InvalidRequest",
"reason": "잘못된 타입의 파라미터가 전달되었습니다. (productId)",
"data": {},
"title": null
},
"success": null
}
```
등록에 실패하면 `resultType`필드의 값으로 `FAIL`이 돌아와요. `error.reason`필드에서 등록에 실패한 이유를 확인해주세요.
> ### API 연동 중 문의사항이나 개선 제안이 있으신가요?
{% hint style="info" %}
토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 [연동/개발 문의](https://discord.gg/xPz6H9NZ3P)에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.
{% endhint %}