> 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/order-products.md).

# 주문상품 조회

구매기간이나 주문상품 ID로 주문상품별 구매·누적 환불·구매확정 상태와 예상 수익금, 확정 수익금·정산 회차를 조회합니다.

주문상품 한 건의 구매·누적 환불·구매확정 상태와 예상 수익금, 확정 수익금·정산 회차를 조회합니다. 구매기간으로 목록을, `orderProductId`로 한 건을 조회하며 조회 시점의 상태만 반환합니다.

```
GET /openapi/order-products
GET /openapi/order-products/{orderProductId}
```

필요 스코프: `sharelink:read`

현재 거래처의 주문상품만 조회하며 이전 거래처의 내역은 포함하지 않습니다. 인증 준비는 [연동 시작하기](https://sharelink-docs.toss.im/developers/open-api/auth.md)를 확인해 주세요.

## 실적 조회·정산내역 조회와의 차이

|           | [실적 조회](https://sharelink-docs.toss.im/developers/open-api/api/performance.md) | [정산내역 조회](https://sharelink-docs.toss.im/developers/open-api/api/settlement.md) | 주문상품 조회                          |
| --------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------- |
| 조회 단위     | 상품별 합계                                                                         | 상품별 합계                                                                          | 주문상품 한 건                         |
| 조회 기준     | 결제일 기간(최대 31일)                                                                 | 정산 회차(구매확정 시각 기준 월)                                                             | 구매기간(최대 31일) 또는 `orderProductId` |
| 수익금       | 예상 수익금, 그중 구매확정분                                                               | 확정 수익금                                                                          | 예상 수익금, 확정 수익금·정산 회차             |
| 환불        | 판매금액에서 빠진 합계                                                                   | 구매확정 전 환불 건은 제외                                                                 | 주문상품별 환불 상태·수량                   |
| 수수료 유형 구분 | 불가 (수수료율이 다른 주문이 합산됨)                                                          | 불가                                                                              | `productCommissionType`          |
| 클릭 수      | 제공                                                                             | 미제공                                                                             | 미제공                              |
| 알맞은 용도    | 기간별 성과 요약                                                                      | 회차 총액 확인·대사                                                                     | 주문별 수익 연동, 크리에이터·회원별 정산          |

주문별 수익을 연동하거나 수수료 유형을 구분해야 하면 주문상품 조회를 기준으로 사용해 주세요. **`attribution`은 수수료율을 구분하는 값이 아닙니다.**

주문 이벤트는 [주문 이벤트 수신](https://sharelink-docs.toss.im/developers/open-api/api/order-event-callback.md)·[주문 이벤트 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-events.md)를 확인해 주세요.

***

## 목록 조회

### 요청

| 파라미터           | 타입     | 필수     | 설명                                                                                                                                                                     |
| -------------- | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderedFrom`  | string | **필수** | 구매기간 시작 시각 (포함). 오프셋을 포함한 ISO 8601 형식. 다른 오프셋으로 보내도 같은 순간을 기준으로 조회                                                                                                     |
| `orderedTo`    | string | **필수** | 구매기간 종료 시각 (미포함). 오프셋을 포함한 ISO 8601 형식. 시작보다 뒤여야 하며 기간은 최대 31일                                                                                                         |
| `partnerRefId` | string | 선택     | 링크의 `partner_ref_id`와 정확히 일치하는 주문상품만 조회. 영문 소문자·숫자·`_`·`-` 1\~128자. 주문 고유값이 아니라 여러 주문상품이 조회될 수 있습니다                                                                    |
| `subTagId`     | string | 선택     | 등록한 [subTag](https://sharelink-docs.toss.im/developers/open-api/api/sub-tags.md)와 정확히 일치하는 주문상품만 조회. 내부 숫자 ID가 아닌 제휴사가 등록한 값. `partnerRefId`와 함께 보내면 둘 다 만족하는 주문상품만 반환 |
| `cursor`       | string | 선택     | 직전 응답의 `nextCursor`. 첫 요청에는 생략                                                                                                                                         |
| `size`         | number | 선택     | 한 페이지 개수. 기본 50, 1\~100                                                                                                                                                |

`--data-urlencode`를 쓰면 오프셋의 `+`가 공백으로 바뀌지 않습니다.

```bash
curl --get \
  -H "Authorization: Bearer {액세스 토큰}" \
  --data-urlencode "orderedFrom=2026-08-01T00:00:00+09:00" \
  --data-urlencode "orderedTo=2026-09-01T00:00:00+09:00" \
  --data-urlencode "size=50" \
  "https://sharelink.toss.im/openapi/order-products"
```

환불 상태·구매확정 여부·갱신 시각 필터는 없으니 응답의 `refundStatus`·`confirmedAt`으로 판단해 주세요.

### 응답

수량 2개가 모두 환불된 예시입니다. ID와 금액은 가상 값입니다.

```json
{
  "resultType": "SUCCESS",
  "success": {
    "items": [
      {
        "orderProductId": "100000000000000001",
        "orderId": "100000000000000000",
        "productId": "12345",
        "partnerRefId": "reward_202608_001",
        "subTagId": "creator_a1",
        "attribution": "DIRECT",
        "quantity": 2,
        "refundedQuantity": 2,
        "refundStatus": "FULL",
        "commissionBaseAmount": 20000,
        "refundedCommissionBaseAmount": 20000,
        "expectedCommissionAmount": 1000,
        "refundedCommissionAmount": 1000,
        "netExpectedCommissionAmount": 0,
        "orderedAt": "2026-08-10T12:30:00+09:00",
        "updatedAt": "2026-08-12T10:00:00.123+09:00",
        "confirmedAt": null,
        "confirmedCommissionAmount": null,
        "settlementMonth": null,
        "lastRefundedAt": "2026-08-12T10:00:00+09:00",
        "productCommissionType": null
      }
    ],
    "size": 50,
    "hasNext": false,
    "nextCursor": null
  }
}
```

| 필드           | 타입             | 설명                                |
| ------------ | -------------- | --------------------------------- |
| `items`      | array          | 주문상품 목록. 아래 **주문상품 필드** 참고        |
| `size`       | number         | 요청한 페이지 크기. 실제 반환 건수는 더 적을 수 있습니다 |
| `hasNext`    | boolean        | 다음 페이지 존재 여부                      |
| `nextCursor` | string \| null | 다음 페이지 커서. 마지막 페이지면 `null`        |

### 주문상품 필드

목록의 `items[]`와 단건 조회의 `success`는 같은 구조입니다. ID는 숫자로 바꾸면 정밀도를 잃으니 문자열로 취급해 주세요. 시각은 ISO 8601 한국 시간(`+09:00`)이며 소수초가 붙을 수 있습니다.

| 필드                             | 타입                 | 설명                                                                                                                                                             |
| ------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderProductId`               | string             | 주문상품 식별자. 중복 제거·갱신의 키로 사용                                                                                                                                      |
| `orderId`                      | string             | 주문 식별자. 한 주문에 여러 `orderProductId`가 속할 수 있습니다                                                                                                                   |
| `productId`                    | string             | 상품 옵션 ID(`tacaItemId`). 링크 발급·상품 상세 조회에 쓰는 값과 같습니다                                                                                                             |
| `partnerRefId`                 | string \| null     | 링크의 `partner_ref_id` 값. 없으면 `null`                                                                                                                             |
| `subTagId`                     | string \| null     | 연결된 subTag 식별자. 확인할 수 없으면 `null`                                                                                                                               |
| `attribution`                  | string             | `DIRECT`(공유한 상품 구매), `INDIRECT`(다른 상품 구매), `UNKNOWN`(분류 불가)                                                                                                    |
| `quantity`                     | number             | 최초 구매 수량. 환불 수량을 빼기 전 값                                                                                                                                        |
| `refundedQuantity`             | number             | 누적 환불 수량. 환불 수량·금액은 모두 음수가 아닌 절댓값                                                                                                                              |
| `refundStatus`                 | string             | `NONE`(환불 없음), `FULL`(전체 환불), `PARTIAL`(향후 부분 환불 지원을 위한 예약값). 현재는 주문상품 전체 환불만 반영                                                                               |
| `commissionBaseAmount`         | number             | 최초 구매의 수수료 산정 기준액(원). 실제 결제액이 아닙니다                                                                                                                             |
| `refundedCommissionBaseAmount` | number             | 누적 환불의 수수료 산정 기준액(원). 실제 환불액이 아닙니다                                                                                                                             |
| `expectedCommissionAmount`     | number             | 환불 차감 전 예상 수익금(원)                                                                                                                                              |
| `refundedCommissionAmount`     | number             | 환불로 차감된 누적 예상 수익금(원)                                                                                                                                           |
| `netExpectedCommissionAmount`  | number             | 환불 차감 후 예상 수익금(원). `expectedCommissionAmount - refundedCommissionAmount`                                                                                       |
| `orderedAt`                    | string             | 결제 완료 시각. 구매기간의 기준                                                                                                                                             |
| `updatedAt`                    | string             | 상태가 마지막으로 반영된 시각. 모든 변경이 반영됐다고 보장하는 시각은 아닙니다                                                                                                                   |
| `confirmedAt`                  | string \| null     | 구매확정 시각. 미확정이면 `null`. 이후 환불되어도 남을 수 있습니다                                                                                                                      |
| `confirmedCommissionAmount`    | number \| null     | 확정 수익금(원). 구매확정되어 정산에 반영되기 전에는 `null`. `expectedCommissionAmount`와 다를 수 있고 정산 회차 마감 전에는 바뀔 수 있습니다. 구매확정 후 환불되어도 줄지 않습니다                                        |
| `settlementMonth`              | string \| null     | 확정 수익금이 귀속되는 정산 회차 (`YYYY-MM`). 확정 수익금이 `null`이면 함께 `null`                                                                                                     |
| `lastRefundedAt`               | string \| null     | 마지막 환불 시각. 환불이 없으면 `null`                                                                                                                                      |
| `productCommissionType`        | string \| null, 선택 | 수수료 유형. 결제 시점에 선착순특가 수수료율이 적용됐으면 `EPIC_DEAL`, 아니면 `null`이거나 필드 생략. 선착순특가 상품이어도 거래처에 별도로 정한 수수료율이 적용되면 `EPIC_DEAL`이 아닙니다. 값이 추가될 수 있으니 알 수 없는 문자열을 오류로 처리하지 마세요 |

* `confirmedCommissionAmount`와 `settlementMonth`는 정산에 반영될 때 함께 채워지므로 **`confirmedAt`이 있어도 두 값이 `null`일 수 있습니다.** 이때는 나중에 다시 조회해 주세요.
* 예상·확정 수익금은 원천징수 전 금액이며 일반과세 개인사업자·법인사업자는 부가세가 포함된 금액입니다. [정산내역 조회](https://sharelink-docs.toss.im/developers/open-api/api/settlement.md)의 **원천징수와 부가세**를 확인해 주세요.
* 결제 완료 시각이 2026-11-13 00:04(한국 시간) 이전인 주문상품은 주문 이벤트의 `productCommissionType`이 `null`이어도 이 API에서는 `EPIC_DEAL`일 수 있습니다. 두 값이 다르면 이 API의 값을 따라 주세요.

### 다음 페이지

목록은 구매 시각·내부 식별자 오름차순이며 `orderProductId` 순서가 아닙니다. `hasNext: true`이면 `nextCursor`를 그대로 `cursor`에 넣어 `hasNext: false`까지 반복합니다. 커서로 이어 조회하는 동안 구매기간·`partnerRefId`·`subTagId` 조건을 바꾸면 `INVALID_CURSOR`로 거절됩니다. 재수집은 커서 없이 시작합니다.

```bash
curl --get \
  -H "Authorization: Bearer {액세스 토큰}" \
  --data-urlencode "orderedFrom=2026-08-01T00:00:00+09:00" \
  --data-urlencode "orderedTo=2026-09-01T00:00:00+09:00" \
  --data-urlencode "size=50" \
  --data-urlencode "cursor={직전 응답의 nextCursor}" \
  "https://sharelink.toss.im/openapi/order-products"
```

***

## 단건 조회

```
GET /openapi/order-products/{orderProductId}
```

목록에서 받은 `orderProductId`를 그대로 넣습니다. 성공 시 `success`에 **주문상품 필드**의 객체 한 개가 들어갑니다.

```bash
curl -H "Authorization: Bearer {액세스 토큰}" \
  "https://sharelink.toss.im/openapi/order-products/100000000000000001"
```

***

## 오류 처리

애플리케이션 오류는 HTTP 200이어도 `resultType: "FAIL"`로 반환합니다. **HTTP 상태만으로 성공을 판단하지 마세요.** 아래는 인증·IP 인가를 통과한 요청 기준입니다.

| 상황                                                 | 응답                                                           | 조치                                             |
| -------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- |
| 구매기간 누락·형식 오류·오프셋 누락, 시작 ≥ 종료, 31일 초과              | HTTP 200 + `INVALID_ARGUMENT`                                | 두 시각과 오프셋 확인. 긴 기간은 나눠 요청                      |
| `size`가 정수가 아니거나 1\~100 밖                          | HTTP 200 + `INVALID_ARGUMENT`                                | 허용 범위의 정수로 변경                                  |
| `partnerRefId` 형식 오류, 빈 `subTagId`·빈 `cursor`      | HTTP 200 + `INVALID_ARGUMENT`                                | 값 규칙에 맞게 고치거나 선택 필터 생략                         |
| 비어 있지 않지만 형식이 잘못된 `subTagId`, 등록되지 않았거나 다른 거래처의 태그 | HTTP 200 + `SHARELINK_OPENAPI_ACCESS_DENIED`                 | 거래처에 등록된 subTag 값 확인                           |
| 손상된 커서 또는 거래처·조회 조건이 다른 커서                         | HTTP 200 + `INVALID_CURSOR`                                  | 올바른 조건으로 커서 없이 다시 시작                           |
| 단건 `orderProductId`가 양의 64비트 정수 범위의 숫자 문자열이 아님     | HTTP 200 + `INVALID_ARGUMENT`                                | 목록에서 받은 ID 확인                                  |
| 단건 미존재·다른 거래처 소유·상태 미구성                            | HTTP 200 + `NOT_FOUND`                                       | ID와 현재 거래처 범위 확인. 주문 이벤트로 방금 받은 ID면 잠시 뒤 다시 조회 |
| 목록에 일치하는 주문상품이 없음                                  | `SUCCESS`, `items: []`, `hasNext: false`, `nextCursor: null` | 정상적인 빈 결과로 처리                                  |

서버 오류·재시도·호출 제한은 [공통 규약](https://sharelink-docs.toss.im/developers/open-api/convention.md)을 따릅니다.

***

## 반영 시점

구매·전체 환불·구매확정은 정해진 갱신 주기 없이 발생하는 대로 조회 결과에 반영합니다. 다만 반영까지 걸리는 시간은 보장하지 않습니다.

방금 발생한 구매는 목록에 없거나 단건 조회에서 `NOT_FOUND`일 수 있고, 환불·구매확정도 바로 보이지 않을 수 있습니다. 이때는 잠시 뒤 다시 조회해 주세요.

변경을 빠르게 받아 처리하려면 [주문 이벤트 수신](https://sharelink-docs.toss.im/developers/open-api/api/order-event-callback.md)을 함께 사용해 주세요. 주문 이벤트도 지연되거나 누락될 수 있으니 최종 상태는 이 API로 확인합니다.

***

## 자사 주문 내역을 갱신하는 방법

수량·금액은 증분이 아니라 **조회 시점의 누적 값**이니 더하지 말고 덮어써 주세요.

1. 구매기간을 31일 이하로 나눠 마지막 페이지까지 조회하고 `orderProductId`를 키로 저장·갱신합니다.
2. 환불·구매확정·확정 수익금은 원래 구매기간이나 단건을 다시 조회해 확인합니다. 8월에 산 주문이 9월에 환불되면 8월 구매기간을 조회해야 합니다.
3. `settlementMonth`에 값이 있는 주문상품을 확정 실적으로 처리합니다. 정산 회차는 구매확정 시각 기준이라 이전 달에 구매한 주문도 이번 회차에 들어올 수 있으니, 이전 구매기간까지 조회해 `settlementMonth`로 거릅니다.
4. 회차별 확정 수익금은 회차가 마감된 다음 달 2영업일부터 조회하기를 권장하며, 회차 총액은 [정산내역 조회](https://sharelink-docs.toss.im/developers/open-api/api/settlement.md)와 대사할 수 있습니다.

`updatedAt`이 같은 두 응답은 어느 쪽이 최신인지 알 수 없습니다. 순차 갱신과 주기적인 재대사를 함께 적용해 주세요.


---

# 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/order-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.
