카테고리

카테고리 항목 조회

get

상품 카테고리 항목을 조회합니다.

카테고리 ID를 미기입한 상태로 요청할 경우, 1차 카테고리 항목들을 반환합니다.

카테고리 구조

기존 4단계 카테고리가 확장되어 2~6 level의 카테고리가 말단 카테고리로 가능하며, 말단 카테고리를 선택하여 상품을 등록할 수 있습니다.

카테고리 정책

말단 카테고리에만 정책이 존재합니다. (나머지는 null)

• 문화비 소득공제: 해당 값이 true라면 상품 등록 시 문화비에 대한 공제 여부를 등록할 수 있습니다.

• 할인율 제한: 해당 값이 null이 아니라면 상품 등록 시 할인율 제한이 있을 수 있습니다. 현재는 도서정가제로 인한 10%만 제한되고 있습니다.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

idinteger · int64Optional

카테고리 ID (미기입 시 1차 카테고리 반환)

Example: 1001

partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑

Responses

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

get

/api/v3/shopping-fep/products/categories/children

HTTPcURLJavaScriptPython

GET /api/v3/shopping-fep/products/categories/children HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "items": [
      {
        "id": 1001,
        "name": "의자",
        "level": 2,
        "parentId": 1,
        "isLeaf": true,
        "policy": {
          "isCultureDeductionTarget": false,
          "discountLimitPercentage": 10
        }
      }
    ]
  }
}

상품 제약 조건 템플릿 조회

get

카테고리별 상품 등록/수정 시 적용되는 제약 조건 템플릿을 조회합니다.

주요 제약사항

• 카테고리는 주기적으로 수정될 수 있습니다.

• 반드시 API를 호출해서 제약사항을 주기적으로 확인 후 기입되도록 구현 부탁드립니다.

• categoryId에 따라 해당 카테고리의 옵션 제약이 적용됩니다.

• categoryId는 버전 2의 isLeaf = true인 카테고리 ID만 허용됩니다.

판매 옵션 (categorySalesOptions)

상품 등록 시 stocks.options에 입력할 수 있는 옵션 정보입니다.

• groupName은 categorySalesOptions의 key, valueName은 valueCandidates에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)

• unitValues가 있을 경우 valueName은 해당 단위로 끝나는 값이어야 합니다.

• keyComment와 valueComment가 있을 경우 해당 내용을 참조하여 입력해야 합니다.

• isOption = false일 경우 필수 (2025.06.16: salesOption은 isOption 여부와 관계없이 전부 필수값입니다.)

• isOneOfRequiredGroup = true인 그룹 중 최소 1개 이상 반드시 포함해야 등록 가능

• categorySalesOptions.id = 373 (key="수량")의 경우 재고 수량이 아닌, 옵션의 구성 수량을 의미합니다. 토스 쇼핑 파트너스에서 노출되는 구성 수량과 일치합니다.

검색 옵션 (categorySearchOptions)

상품 등록 시 stocks.searchOption에 입력할 수 있는 옵션 정보입니다.

• Map<String, String> 형태이며, Map의 key는 categorySearchOptions.key의 내용

• value는 valueCandidates에 포함되는 값만 허용 (valueCandidates가 빈 배열일 경우 자유)

• unitValues가 있을 경우 value는 해당 단위로 끝나는 값이어야 합니다.

• keyComment와 valueComment가 있을 경우 해당 내용을 참조하여 입력해야 합니다.

• isOption = false일 경우 필수

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

categoryIdinteger · int64Required

카테고리 ID (말단 카테고리만 허용)

Example: 1001

Query parameters

partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑

Responses

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

get

/api/v3/shopping-fep/category/{categoryId}/constraint-templates

HTTPcURLJavaScriptPython

GET /api/v3/shopping-fep/category/{categoryId}/constraint-templates HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "categoryName": "리클라이너/소파",
    "categoryId": 1001,
    "categorySalesOptions": [
      {
        "id": 373,
        "key": "색상",
        "valueCandidates": [
          "빨강",
          "파랑",
          "노랑"
        ],
        "isOption": true,
        "placeholder": "색상을 입력하세요",
        "unitValues": [
          "g",
          "kg"
        ],
        "keyComment": "색상 선택 시 주의사항",
        "valueComment": "정확한 색상명을 입력해주세요",
        "isOneOfRequiredGroup": false
      }
    ],
    "categorySearchOptions": [
      {
        "key": "브랜드",
        "valueCandidates": [
          "토스",
          "삼성",
          "LG"
        ],
        "isOption": true,
        "placeholder": "브랜드명을 입력하세요",
        "unitValues": [
          "ml",
          "L"
        ],
        "keyComment": "브랜드 선택 시 주의사항",
        "valueComment": "정확한 브랜드명을 입력해주세요"
      }
    ],
    "productNoticeInfoTemplateTypes": [
      "CLOTHING",
      "SHOES"
    ]
  }
}

정보제공 고시 카테고리 목록 조회

get

상품등록에 필요한 정보제공 고시 카테고리를 조회합니다. 상세내용은 정보제공 고시 항목 조회 API로 조회가 필요합니다.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑

Responses

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

get

/api/v3/shopping-fep/notices/category-codes

HTTPcURLJavaScriptPython

GET /api/v3/shopping-fep/notices/category-codes HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "REQUEST_FAILED",
    "reason": "text"
  },
  "success": {
    "items": [
      {
        "categoryCode": "CLOTHING",
        "firstCategoryName": "패션",
        "secondCategoryName": "의류"
      }
    ]
  }
}

정보제공 고시 항목 조회

get

정보제공 고시 항목을 조회합니다. 정보제공 고시 카테고리 목록 조회 API를 통해 얻은 카테고리 코드를 이용하여 호출합니다. 응답은 상품 등록시에 활용하게 됩니다.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑

categoryCodestring · enumRequired

카테고리 코드

Example: CLOTHINGPossible values:

Responses

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

get

/api/v3/shopping-fep/notices

HTTPcURLJavaScriptPython

GET /api/v3/shopping-fep/notices?categoryCode=CLOTHING HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "REQUEST_FAILED",
    "reason": "text"
  },
  "success": {
    "items": [
      {
        "id": 1,
        "title": "제조사"
      }
    ]
  }
}

API 연동 중 문의사항이나 개선 제안이 있으신가요?

토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 연동/개발 문의에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.