> For the complete documentation index, see [llms.txt](https://sharelink-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sharelink-docs.toss.im/developers/open-api/api/products.md).

# 카테고리 베스트 상품 조회

특정 카테고리에서 잘 팔리는 상품 목록을 조회합니다.

카테고리별 상품 노출 영역을 구성하실 때 사용하시면 됩니다.

```
GET /openapi/products/best-categories/{categoryId}
```

필요 스코프: `sharelink:read`

{% hint style="warning" %}
이 API는 토스쇼핑이 인증한 크리에이터만 쓸 수 있습니다. 토스쇼핑 인증을 받지 않은 크리에이터가 호출하면 HTTP 200과 함께 `errorCode: "SHARELINK_OPENAPI_PARTNER_NOT_AUTHORIZED"`로 거절됩니다. 자세한 내용은 [연동 시작하기](https://sharelink-docs.toss.im/developers/open-api/auth.md)를 확인해 주세요.
{% endhint %}

***

## 요청

### 경로 파라미터

| 파라미터         | 필수 | 설명                                                                                                  |
| ------------ | -- | --------------------------------------------------------------------------------------------------- |
| `categoryId` | 필수 | 조회할 카테고리 ID. [카테고리 조회](https://sharelink-docs.toss.im/developers/open-api/api/categories.md)에서 얻습니다 |

### 쿼리 파라미터

| 파라미터     | 필수 | 기본값  | 설명                                      |
| -------- | -- | ---- | --------------------------------------- |
| `cursor` | 선택 | —    | 다음 페이지 커서. 첫 요청에는 넣지 않습니다               |
| `size`   | 선택 | `30` | 한 번에 받을 개수. **1\~100** (범위를 벗어나면 자동 보정) |

```bash
curl -H "Authorization: Bearer {액세스 토큰}" \
  "https://sharelink.toss.im/openapi/products/best-categories/101?size=30"
```

[카테고리 조회](https://sharelink-docs.toss.im/developers/open-api/api/categories.md)의 **모든 레벨** `categoryId`를 사용하실 수 있습니다. 다만 랭킹 데이터가 없는 카테고리도 있습니다.

| 상황                   | 응답                                  |
| -------------------- | ----------------------------------- |
| 존재하지 않는 `categoryId` | 오류 (`INVALID_ARGUMENT`)             |
| 유효하지만 랭킹 상품이 없는 카테고리 | 정상 응답에 빈 `items` + `hasNext: false` |

***

## 응답

`partnerMallType`의 값과 처리 규칙은 [상품 카드 공통 필드](https://sharelink-docs.toss.im/developers/open-api/convention.md)의 **제휴몰 유형**을 확인해 주세요.

```json
{
  "resultType": "SUCCESS",
  "success": {
    "category": {
      "categoryId": 101,
      "displayName": "여성의류"
    },
    "items": [
      {
        "rank": 1,
        "tacaItemId": 12345,
        "displayName": "상품명",
        "partnerMallType": "NONE",
        "thumbnailUrl": "https://.../thumb.jpg",
        "productUrl": "https://toss.shopping/t/9876",
        "displayPrice": 19900,
        "originalPrice": 29900,
        "discountRate": 33,
        "isSoldOut": false,
        "reviewScore": 4.8,
        "reviewCount": 1523,
        "categoryIds": [100, 101, 10125]
      }
    ],
    "nextCursor": "eyJ...",
    "hasNext": true
  }
}
```

### 필드

| 필드                        | 타입             | 설명                                                             |
| ------------------------- | -------------- | -------------------------------------------------------------- |
| `category.categoryId`     | number         | 조회한 카테고리 ID                                                    |
| `category.displayName`    | string         | 조회한 카테고리 이름                                                    |
| `items`                   | array          | 상품 목록. 순위대로 정렬되어 있습니다                                          |
| `items[].partnerMallType` | string         | 판매자 제휴몰 유형. 일반 셀러는 `NONE`, 오아시스는 `OASIS`. 모르는 값은 일반 셀러처럼 처리합니다 |
| `nextCursor`              | string \| null | 다음 페이지 커서. 다음 페이지가 없으면 `null`                                  |
| `hasNext`                 | boolean        | 다음 페이지 존재 여부                                                   |

`items`의 각 항목은 [상품 카드 공통 필드](https://sharelink-docs.toss.im/developers/open-api/convention.md)와 같습니다. `rank`는 해당 카테고리 내 순위입니다.

페이징 방법은 [커서 페이징](https://sharelink-docs.toss.im/developers/open-api/convention.md)을 참고해 주세요.

***

## 사용 팁

**랭킹은 매일 오전 9시(KST)에 한 번 갱신됩니다.** 매번 호출하지 마시고, 하루 한 번 조회해 저장해 두고 사용하시는 것을 권장합니다.

노출하실 상품이 정해지면, 각 상품의 `tacaItemId`로 [쉐어링크를 발급](https://sharelink-docs.toss.im/developers/open-api/api/link.md)받아 게시글에 넣어 주세요. 응답의 `productUrl`은 추적이 되지 않아 수익으로 집계되지 않습니다.

[상품 상세 조회](https://sharelink-docs.toss.im/developers/open-api/api/product-detail.md)로 이미지 정보를 보강하실 수 있습니다. 사용 전에 [공통 규약](https://sharelink-docs.toss.im/developers/open-api/convention.md)의 **공통 주의사항**에서 이미지 사용 범위를 먼저 확인해 주세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://sharelink-docs.toss.im/developers/open-api/api/products.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
