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

# 용어

tacaId와 tacaItemId의 차이 등 API에 등장하는 식별자와 용어를 정리했습니다.

**특히 `tacaId` 와 `tacaItemId` 는 이름이 비슷하지만 다른 값이므로 꼭 구분해 주세요.**

***

## 자주 나오는 용어

| 용어           | 뜻                                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| 제휴사 · 거래처    | 토스와 계약해 Open API를 쓰는 사업자. 이 문서에서 제휴사와 거래처는 같은 대상이며, 인증 정보(Access Key / Secret Key)와 각종 한도가 이 단위로 적용됩니다             |
| 토스 운영자       | 쉐어링크를 운영하는 토스 담당자. 사용 승인, 인증 정보 폐기, Secret Key 재발급을 수행합니다                                                          |
| 크리에이터 · 퍼블리셔 | 링크를 발급해 수익을 받는 회원. API에서는 `publisherId`(퍼블리셔 UUID)로 가리킵니다                                                          |
| 귀속           | 어떤 구매를 어떤 링크의 성과로 인정하는 것. 구매 시점 기준 과거 24시간 안에 링크를 통한 상품 페이지 방문이 있으면 그 링크에 귀속됩니다. 여러 링크를 거쳤다면 가장 마지막에 방문한 링크에 귀속됩니다 |
| 대사           | Push로 받은 이벤트와 Pull로 조회한 이벤트를 맞춰 보고 빠진 건을 채우는 작업                                                                    |
| 정산 회차        | 정산을 묶는 단위. `YYYY-MM`으로 지정하며 그 회차에 구매확정된 주문이 대상입니다                                                                  |
| 구매확정         | 구매자가 상품을 받은 뒤 확정하거나 배송 완료 후 일정 기간이 지나 자동 확정되는 것. 수익금은 이 시점에 확정됩니다                                                  |

***

## 상품 식별자

토스쇼핑의 상품은 두 단계로 나뉩니다.

```
tacaId (상품 그룹)  =  "무선 이어폰 A"
   └── tacaItemId (상품 옵션)  =  "무선 이어폰 A - 화이트"
   └── tacaItemId (상품 옵션)  =  "무선 이어폰 A - 블랙"
```

| 용어             | 무엇인가                                                                    | 어디서 얻는가                                     |
| -------------- | ----------------------------------------------------------------------- | ------------------------------------------- |
| `tacaItemId`   | **상품 옵션 식별자.** 색상·용량 등 실제로 팔리는 단위입니다                                    | 상품 목록 API 응답에 들어 있습니다                       |
| `tacaId`       | **상품 그룹 식별자.** 여러 옵션을 묶는 단위입니다. 상품 페이지 주소 `.../t/{tacaId}` 의 숫자가 이 값입니다 | 상품 상세 조회 응답, 또는 상품 페이지 주소에서                 |
| 대표 상품 (winner) | 한 `tacaId` 안에서 **지금 대표로 보여지는 옵션 하나**입니다. 판매 상황에 따라 바뀝니다                 | 직접 조회하지 않습니다. `tacaId` 로 요청하면 서버가 자동으로 고릅니다 |

### 어느 쪽을 써야 하나요

**`tacaItemId` 사용을 권장드립니다.**

`tacaId` 로 요청하면 서버가 그 시점의 대표 상품을 골라 처리합니다. 편리하지만, 대표 상품이 바뀌면 **같은 `tacaId` 로 요청해도 다른 옵션이 잡힙니다.** 링크 발급에서는 이 때문에 새 링크가 발급되어 성과가 나뉩니다.

| 상황                     | 권장                                |
| ---------------------- | --------------------------------- |
| 상품 목록 API로 받은 상품을 다룰 때 | `tacaItemId` (목록 응답에 이미 들어 있습니다)  |
| 상품 페이지 주소만 알고 있을 때     | `tacaId` (주소에서 뽑을 수 있는 값이 이것뿐입니다) |

***

## 링크 관련

| 용어               | 무엇인가                                                                                                                                                                                    | 수익 집계                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `productUrl`     | 일반 상품 페이지 주소. 조회 API 응답에 들어 있습니다                                                                                                                                                        | ❌ **집계되지 않습니다**       |
| `shortUrl`       | 발급받은 추적 링크(단축형)                                                                                                                                                                         | ✅ 집계됩니다               |
| `originUrl`      | 발급받은 추적 링크(단축 전 원본)                                                                                                                                                                     | ✅ 집계됩니다               |
| `publisherId`    | 발급 주체를 가리키는 UUID입니다. 어드민 API 연동 화면에서 **회원 연동 ID**로 확인하실 수 있습니다. 링크 발급 시 필수이며, 이 값으로 수익이 귀속됩니다                                                                                           | —                     |
| `partner_ref_id` | 제휴사가 `originUrl`에 직접 붙이는 선택 쿼리 파라미터. 자기 사용자·캐시백 신청을 주문 이벤트와 연결하는 제휴사 내부 식별자이며, 이벤트·조회에서는 `partnerRefId`로 표기됩니다. 형식·사용법은 [쉐어링크 발급](/developers/open-api/api/link.md)의 **제휴사 추적 식별자 붙이기** | — (부착 여부와 무관하게 집계됩니다) |

***

## 하위 채널 식별 (subTag)

거래처 하나에 인증 정보가 1벌만 발급되므로, 하위 채널(크리에이터·매체·노출 영역)별로 실적을 나눠 보시려면 subTag를 씁니다.

| 용어         | 무엇인가                                                                           |
| ---------- | ------------------------------------------------------------------------------ |
| subTag     | 제휴사가 자기 하위 채널을 구분하려고 미리 등록해 두는 식별 단위                                           |
| `subTagId` | subTag의 식별자. **토스가 값을 만들어 드리지 않고 제휴사가 직접 정합니다.** 거래처 안에서 유일하며, 등록 후 변경할 수 없습니다 |
| `label`    | subTag의 표시용 이름. 선택 항목이며 식별에는 쓰지 않습니다                                           |

`subTagId`는 링크 발급 시 선택 파라미터이고, 넣지 않으시면 채널 구분 없이 발급됩니다. 형식 규칙과 등록 절차는 [subTag 관리](/developers/open-api/api/sub-tags.md)를 봐 주세요.

***

## 실적 관련

| 용어            | 무엇인가                                                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `attribution` | 기여 방식. `DIRECT`(공유한 링크의 그 상품이 구매됨) / `INDIRECT`(링크를 타고 들어와 다른 상품을 구매함) / `UNKNOWN`. 수수료율은 동일하며, 귀속 기준은 위 **귀속** 항목과 같습니다 |
| `productId`   | 실적·정산 응답에서 상품을 가리키는 값. **`tacaItemId`(상품 옵션 ID)와 같은 값**입니다                                                               |

기간 기준이 다르므로 [실적 조회](/developers/open-api/api/performance.md)와 [정산 실적 조회](/developers/open-api/api/settlement.md)의 금액은 다를 수 있습니다. 실적 조회의 판매·수익금은 결제일 기준이고, 클릭은 방문일 기준입니다. 정산 실적은 구매확정된 정산 회차를 기준으로 조회합니다.

***

## 주문 이벤트 관련

[주문 이벤트 수신](/developers/open-api/api/order-event-callback.md)(Push)과 [주문 이벤트 조회](/developers/open-api/api/order-events.md)(Pull)에 등장하는 값입니다. 두 경로는 같은 이벤트 구조를 씁니다.

| 용어                   | 무엇인가                                                                                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 주문 이벤트               | 발급 링크에 귀속된 **주문상품** 하나의 구매(`PURCHASE`) · 전체 취소(`CANCEL`) · 구매확정(`CONFIRM`). 한 주문에 상품이 여러 개면 이벤트도 여러 건입니다. 토스쇼핑에는 부분 수량 취소가 없어, 취소는 항상 해당 주문상품의 전체 수량 취소입니다 |
| `eventId`            | 이벤트 식별자(UUID 36자). 주문상품+이벤트 종류당 하나로 고정되며 **Push와 Pull이 같은 값을 쓰는 중복 제거 키**입니다                                                                               |
| `productId` (주문 이벤트) | 실적·정산 조회의 `productId`(number)와 같은 값(`tacaItemId`)이지만 주문 이벤트에서는 **문자열**로 옵니다                                                                                |

***

## 그 밖의 필드

응답 형식·오류 필드와 상품 카드 공통 필드는 [공통 규약](/developers/open-api/convention.md), 인증 정보와 스코프는 [연동 시작하기](/developers/open-api/auth.md), 그 밖의 응답 필드는 각 API 문서에 정리되어 있습니다.


---

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