> 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-event-callback.md).

# 주문 이벤트 수신 (Push)

발급한 링크로 발생한 구매·전체 취소·구매확정 이벤트를 제휴사 서버가 등록한 HTTPS 주소로 받습니다. 캐시백·리워드 연동의 기본 전달 경로입니다.

구매·전체 취소·구매확정이 발생한 사실을 이벤트로 전달합니다. 값은 이벤트를 만들 때 저장한 값이며, 주문상품의 현재 상태와 확정 수익금·정산 회차는 [주문상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-products.md)에서 확인합니다.

```
POST {제휴사가 등록한 수신 URL}      (토스 → 제휴사 방향)
```

필요 스코프: 없음. 토스 발신 여부는 **6. 서명 검증 (HMAC-SHA256)** 절차로 확인합니다.

> Push는 지연·중복·순서 역전·누락이 있을 수 있고 **실패한 전송을 다시 보내지 않습니다.** 5분마다 [주문 이벤트 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-events.md)(Pull)로 누락을 채우는 대사를 함께 구현해 주세요.

이벤트 단위는 주문상품입니다. 한 주문에 상품이 여러 개면 이벤트도 여러 건 오고, 구매·취소·구매확정은 각각 별개 이벤트입니다. 부분 수량 취소가 없어 2개 이상 산 주문상품도 `CANCEL` 1건으로 전체 수량이 취소됩니다. 한 주문에 서로 다른 상품이 여러 개면 상품별로 따로 취소될 수 있습니다.

***

## 1. 설계 전에 알아 둘 것

| 항목                           | 내용                                                                                                                                                                                                                                                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 이벤트 3종                       | `PURCHASE`(구매) · `CANCEL`(해당 주문상품 전체 취소) · `CONFIRM`(구매확정). 모두 수신을 켠 URL로 같은 구조의 본문이 도착                                                                                                                                                                                                                      |
| `eventId`는 고정값               | 주문상품 하나 + 이벤트 종류(구매/취소/구매확정)당 하나로 고정. 다시 오거나 Pull로 조회해도 같은 값이므로, 이벤트를 쌓아 저장할 때 **`eventId`에 유일 제약**을 걸면 Push·Pull 중복과 여러 수신 URL로 도착한 같은 이벤트가 모두 걸러짐. 같은 주문상품이라도 구매·취소·구매확정의 `eventId`는 서로 다르므로 주문을 식별하는 값으로 쓰지 않음                                                                                            |
| 주문을 식별하는 값은 `orderProductId` | 같은 주문상품의 구매·취소·구매확정 이벤트와 주문상품 조회에서 같은 값. 이벤트끼리, 그리고 주문상품 조회와 연결할 때 사용. 주문상품당 한 행으로 상태를 관리한다면 **`orderProductId`에 유일 제약**을 걸고 이벤트 종류에 따라 상태를 갱신                                                                                                                                                               |
| 도착 순서를 보장하지 않음               | 취소나 구매확정이 구매보다 먼저 올 수 있음. 먼저 받은 취소·구매확정 상태를 유지하고, 뒤늦게 온 구매로 되돌리지 않음                                                                                                                                                                                                                                          |
| 구매 이벤트가 없는 취소·구매확정도 있음       | 원래 구매가 2026-09-16 이전이면 구매 이벤트가 만들어진 적이 없고, 90일이 지났으면 이미 삭제됨. `purchaseEventId`에 값이 있어도 구매를 기다리지 말고 받은 이벤트만으로 처리                                                                                                                                                                                              |
| 구매확정이 마지막 상태                 | 구매확정된 주문상품에는 이후 `CANCEL` 이벤트를 발행하지 않으므로, 캐시백 확정 시점을 "구매 후 며칠 홀드" 대신 `CONFIRM` 수신으로 잡을 수 있음. 주문 이벤트에는 확정 수익금이 담기지 않으며, 주문상품별 확정 수익금과 정산 회차는 [주문상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-products.md)의 `confirmedCommissionAmount`·`settlementMonth`로 확인. 지급 확정(정산금 지급) 신호는 전달되지 않음 |
| 구매확정 이벤트의 값                  | 수량·금액·`partnerRefId`·`subTagId`·`attribution`은 보관된 구매 이벤트 값을 승계. 구매확정 시점에 다시 계산하지 않으며, 구매 Push 전용 `orderSummary`는 포함되지 않음                                                                                                                                                                                    |
| 금액 2종의 의미                    | `commissionBaseAmount`는 수수료 산정 기준액, `expectedCommissionAmount`는 예상 수익금(원천징수 전). 실제 결제액이나 확정 금액이 아님. 산출 방식은 **7. 이벤트 필드**의 **금액 2종이 정해지는 방식**                                                                                                                                                                 |
| 보관 90일, 기록 시작 2026-09-16     | 이벤트는 종류별로 각자의 `recordedAt` 기준 90일 뒤 삭제. 더 긴 이력은 자체 보관. 2026-09-16 이전 주문은 이 방식으로 제공되지 않으며, 구매확정 이벤트는 기능 적용 이후 발생한 구매확정부터 기록(소급 생성하지 않음)                                                                                                                                                                       |

***

## 2. 링크에 `partner_ref_id` 붙이기 (선택)

제휴사의 사용자·유입·캐시백 신청을 이벤트와 연결하려면 `originUrl`에 `partner_ref_id`를 붙입니다. 방법과 허용 값은 [쉐어링크 발급](https://sharelink-docs.toss.im/developers/open-api/api/link.md)의 **제휴사 추적 식별자 붙이기**에 있습니다.

형식에 맞지 않는 값은 링크에서는 오류 없이 버려져 이벤트의 `partnerRefId`가 `null`로 오고, [주문 이벤트 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-events.md)의 `partnerRefId` 필터에서는 거절됩니다.

***

## 3. 수신 URL 준비·등록

수신 URL과 그 경로는 제휴사가 정합니다(예: `https://partner.example.com/webhooks/toss-sharelink/orders`). 쉐어링크 크리에이터 어드민의 API 연동 화면 아래 "주문 이벤트 수신" 카드에서 거래처당 최대 3개까지 등록하고, URL마다 수신을 켜고 끕니다.

| 항목           | 규칙                                                                                                                                                                                                         |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 프로토콜·길이      | HTTPS, 최대 400자. 포트는 생략하면 443이며 1\~65535 지정 가능                                                                                                                                                              |
| 허용하지 않는 것    | URL에 포함한 사용자 이름·비밀번호, fragment(`#` 뒤 부분)                                                                                                                                                                   |
| 쿼리 파라미터      | 붙일 수 있음(예: `https://partner.example.com/webhooks/orders?source=toss`). 등록한 쿼리를 바꾸지 않고 그대로 붙여 보내며, 서명에는 URL이 들어가지 않아 검증 방법은 같음. 쿼리까지 크리에이터 어드민 화면과 토스 요청 로그에 남으므로 출처 구분 같은 고정 식별값만 넣고 토큰·비밀번호 같은 비밀값은 넣지 않음 |
| 접근성          | 공개 인터넷 주소만 등록 가능. 발송할 때마다 도메인을 다시 해석하며, 결과가 사설·루프백·예약 대역이면 전송하지 않음                                                                                                                                         |
| 리다이렉트        | 따라가지 않음. 최종 수신 URL을 등록                                                                                                                                                                                     |
| 중복 등록        | 이미 등록한 URL과 문자열이 같은 URL은 다시 등록할 수 없음. 쿼리만 다른 URL(예: `?source=a`와 `?source=b`)은 서로 다른 URL로 등록됨                                                                                                              |
| 여러 URL로 받을 때 | 수신을 켠 URL마다 같은 이벤트를 같은 본문·서명으로 등록한 순서대로 하나씩 전송. 한 URL이 실패해도 나머지 URL에는 보내며, 실패한 URL에 다시 보내지 않음                                                                                                              |
| 인증 정보가 바뀌면   | 토스 운영자가 인증 정보를 폐기하면 등록한 모든 URL의 수신이 꺼짐. 다시 발급받아도 꺼진 상태이므로 같은 카드에서 URL마다 다시 켜야 함. Secret Key 재발급으로는 수신이 꺼지지 않고 서명 키만 바뀜(**8. Secret Key가 바뀌면** 참고)                                                          |
| 설정 변경 시      | 변경 전에 이미 시작된 HTTP 요청은 도착할 수 있음                                                                                                                                                                             |

***

## 4. 방화벽 열기

IP 허용 목록을 운영한다면 아래 토스 발신 IP 전체를 인바운드 출발지로 등록하세요. 포트는 등록한 URL의 포트(기본 443)입니다.

| 발신 IP / 범위                     | CIDR 표현            |
| ------------------------------ | ------------------ |
| 117.52.3.4                     | `117.52.3.4/32`    |
| 117.52.3.11                    | `117.52.3.11/32`   |
| 117.52.3.80 \~ 117.52.3.87     | `117.52.3.80/29`   |
| 211.115.96.4                   | `211.115.96.4/32`  |
| 211.115.96.11                  | `211.115.96.11/32` |
| 211.115.96.80 \~ 211.115.96.87 | `211.115.96.80/29` |
| 106.249.5.80 \~ 106.249.5.87   | `106.249.5.80/29`  |

`.80 ~ .87`은 8개 전체입니다. 허용 IP에서 온 요청도 서명을 검증하세요.

Open API의 IP 등록은 두 방향입니다.

| 구분                                                                                | 방향       | 무엇을           | 어디에            |
| --------------------------------------------------------------------------------- | -------- | ------------- | -------------- |
| 출발지 IP 등록 ([연동 시작하기](https://sharelink-docs.toss.im/developers/open-api/auth.md)) | 제휴사 → 토스 | 제휴사 서버의 공인 IP | 쉐어링크 크리에이터 어드민 |
| 발신 IP 허용 (이 절)                                                                    | 토스 → 제휴사 | 위 토스 발신 IP    | 제휴사 방화벽        |

***

## 5. 토스가 보내는 요청과 제휴사가 돌려줄 응답

| 항목         | 내용                                                                                            |
| ---------- | --------------------------------------------------------------------------------------------- |
| 메서드·형식     | HTTPS `POST`, `Content-Type: application/json`                                                |
| 본문         | 아래 이벤트 객체 1건 그 자체. `event`나 `partnerId`로 감싸지 않음                                               |
| 헤더         | `sharelink-webhook-transmission-time`, `sharelink-webhook-signature`. Secret 원문이나 인증키는 보내지 않음 |
| 성공 판정      | 제휴사 응답이 HTTP 2xx이면 성공. 본문은 필수가 아니며 `204 No Content`도 가능                                       |
| 토스 쪽 시간 제한 | 연결 1초, 응답 3초, 한 번의 전송 전체 5초. 토스 발신 측 타임아웃이며 전달 지연을 보장하는 SLA가 아님                               |

이벤트를 저장한 뒤 바로 응답하고, 후속 처리는 비동기로 돌리시길 권장합니다.

| 상황                                     | 토스 동작                                                                                                           |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 2xx 응답                                 | 성공으로 기록. 같은 이벤트가 다시 전송될 수는 있음                                                                                   |
| 2xx 외 응답(3xx 리다이렉트 포함) · 시간 초과 · 연결 실패 | 실패로 기록하고 다시 보내지 않음. 복구 수단은 [주문 이벤트 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-events.md)뿐 |
| 서명 키(Secret)를 가져오지 못함                  | 서명 없이 보내지 않으며 전송 자체를 하지 않음                                                                                      |

***

## 6. 서명 검증 (HMAC-SHA256)

토스는 Secret Key(OAuth `client_secret`) 원문으로 만든 서명을 헤더에 실어 보냅니다. 이벤트를 처리하기 전에 검증하세요.

| 헤더                                    | 값                                                                          |
| ------------------------------------- | -------------------------------------------------------------------------- |
| `sharelink-webhook-transmission-time` | 서명 생성 시각. ISO 8601 KST 문자열 (예: `2026-09-14T12:00:00+09:00`). 소수 초가 붙을 수 있음 |
| `sharelink-webhook-signature`         | `v1:` 뒤에 HMAC-SHA256 결과를 표준 Base64로 인코딩한 값                                 |

```
key       = UTF8(Secret Key 원문)
message   = raw HTTP body bytes  +  UTF8(":")  +  UTF8(transmission-time 헤더 원문)
signature = "v1:" + Base64( HMAC-SHA256(key, message) )
```

| 확인할 것                | 이유                                                                               |
| -------------------- | -------------------------------------------------------------------------------- |
| 키는 Secret Key **원문** | Base64 디코딩하거나 앞뒤를 자르면 값이 달라짐. 액세스 토큰·Access Key는 키가 아님                           |
| 본문은 **수신한 원본 바이트**   | JSON을 파싱했다가 다시 만들거나 공백·필드 순서가 바뀌면 실패. 프레임워크가 본문을 먼저 파싱하면 원본을 따로 잡아 두어야 함 (아래 예시) |
| 시각은 **헤더 원문**        | 파싱해서 다시 만든 문자열이 아니라 `+09:00`이 포함된 원문 그대로                                         |
| 헤더가 없거나 형식이 틀리면 거절   | 서명이 맞지 않는 요청을 "서명 없는 요청"으로 봐서 처리하면 안 됨                                           |
| 전송 시각이 현재와 ±5분 이내인지  | 재전송 공격 완화. 서버 시계를 동기화                                                            |
| 상수 시간 비교             | 문자열 `==` 비교는 타이밍 공격에 노출                                                          |

### 수신 핸들러 예시 (Node.js / Express)

검증 → `eventId` 중복 제거 → 저장 → `204` 응답의 뼈대입니다. `saveIfNew`·`enqueueCashbackJob`은 제휴사가 구현합니다.

```javascript
const crypto = require("crypto");
const express = require("express");
const app = express();

// 원본 바이트를 그대로 받습니다. express.json() 으로 먼저 파싱하면 서명 검증에 쓸 원본이 남지 않습니다.
app.post("/webhooks/toss-sharelink/orders", express.raw({ type: "application/json" }), (req, res) => {
  if (!Buffer.isBuffer(req.body)) return res.status(400).end();
  const time = req.get("sharelink-webhook-transmission-time");
  const sig = req.get("sharelink-webhook-signature");
  if (!time || !sig || !sig.startsWith("v1:")) return res.status(401).end();

  const sentAt = Date.parse(time);
  if (Number.isNaN(sentAt) || Math.abs(Date.now() - sentAt) > 5 * 60 * 1000) return res.status(401).end();

  const expected = crypto
    .createHmac("sha256", Buffer.from(process.env.SHARELINK_CLIENT_SECRET, "utf8"))
    .update(req.body)            // 원본 Buffer
    .update(":")
    .update(Buffer.from(time, "utf8"))
    .digest();
  const received = Buffer.from(sig.slice(3), "base64");
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));   // 검증을 마친 뒤에 파싱
  const inserted = saveIfNew(event.eventId, event);       // eventId 유일 제약으로 중복 제거
  if (inserted) enqueueCashbackJob(event.orderProductId); // 후속 처리는 비동기
  return res.status(204).end();                           // 중복이어도 2xx
});
```

Spring은 `@RequestBody byte[]`로 받아 같은 순서로 처리합니다.

### 서명 값 직접 계산해 보기 (터미널)

원본 본문을 `body.json`에 저장해 실행한 결과가 헤더의 `v1:` 뒤 값과 같아야 합니다. 편집기로 저장하면 끝에 개행이 붙어 값이 달라질 수 있습니다. Secret이 셸 이력에 남으므로 **운영 Secret으로는 실행하지 마세요.**

```bash
# TRANSMISSION_TIME: sharelink-webhook-transmission-time 헤더 원문 / CLIENT_SECRET: 테스트용 Secret Key
{ cat body.json; printf ':%s' "$TRANSMISSION_TIME"; } \
  | openssl dgst -sha256 -hmac "$CLIENT_SECRET" -binary \
  | base64
```

***

## 7. 이벤트 필드

아래 기본 필드는 주문 이벤트 조회(Pull)와 같고, **Push 추가 필드**는 Push에만 있습니다. 알 수 없는 필드는 무시하고, 선택 필드는 없거나 `null`일 수 있음을 전제로 구현합니다.

| 필드                         | 타입                 | 설명                                                                                                                     |
| -------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `eventId`                  | string             | 이벤트 식별자(UUID 36자). 주문상품+이벤트 종류당 하나로 고정. 형식에 의존하지 말고 문자열로 저장. 주문 식별자가 아님                                                |
| `eventType`                | string             | `PURCHASE`(구매) / `CANCEL`(해당 주문상품 전체 취소) / `CONFIRM`(구매확정)                                                             |
| `orderId`                  | string             | 토스쇼핑 주문 식별자                                                                                                            |
| `orderProductId`           | string             | 토스쇼핑 주문상품 식별자. 이벤트의 기준 단위이며, 같은 주문상품의 구매·취소·구매확정 이벤트와 주문상품 조회에서 같은 값                                                   |
| `productId`                | string             | 상품 옵션 ID. [용어](https://sharelink-docs.toss.im/developers/open-api/glossary.md)의 `tacaItemId`와 같은 값이지만 실적 조회와 달리 문자열    |
| `productName`              | string             | 이벤트 발행 시점 상품명                                                                                                          |
| `partnerMallType`          | string \| null, 선택 | 판매자 제휴몰 유형. `NONE`(일반 셀러) / `OASIS`(오아시스마켓). 확인할 수 없으면 `null`이거나 필드 생략                                                 |
| `productCommissionType`    | string \| null, 선택 | 상품 기반 수수료 유형. 결제 시점에 선착순특가 수수료율이 적용된 주문상품이면 `EPIC_DEAL`. 해당하지 않으면 `null`이거나 필드 생략                                      |
| `quantity`                 | number             | 이벤트 대상 수량. `CONFIRM`은 구매 이벤트 값을 승계                                                                                     |
| `commissionBaseAmount`     | number             | 수수료 산정 기준액 (원). 실제 결제액·환불액이 아님. 산출 방식은 아래 **금액 2종이 정해지는 방식**                                                           |
| `expectedCommissionAmount` | number             | 예상 수익금 (원, 원천징수 전). 확정 금액이 아님. 산출 방식은 아래 **금액 2종이 정해지는 방식**                                                            |
| `partnerRefId`             | string \| null     | 귀속된 방문의 `partner_ref_id`. 없거나 형식 위반이면 `null`                                                                           |
| `subTagId`                 | string \| null     | 귀속된 [subTag](https://sharelink-docs.toss.im/developers/open-api/api/sub-tags.md). 없으면 `null`                           |
| `attribution`              | string             | 공유한 상품을 샀는지 여부. `DIRECT`(직접) / `INDIRECT`(간접) / `UNKNOWN`(미확인). 수수료율을 구분하는 값이 아님. 수수료 유형은 `productCommissionType`으로 확인 |
| `purchaseEventId`          | string \| null     | `CANCEL`·`CONFIRM`이 대응하는 구매 `eventId`. `PURCHASE`는 `null`. 값이 있어도 구매 이벤트가 없을 수 있음 (**1. 설계 전에 알아 둘 것** 참고)             |
| `occurredAt`               | string             | 구매·취소·구매확정 상태 전환 시각. ISO 8601 KST(`+09:00`)                                                                            |
| `recordedAt`               | string             | 이벤트 기록 시각. ISO 8601 KST(`+09:00`). 90일 보관의 기준                                                                          |

예상 수익금은 원천징수 전 금액이며 일반과세 개인사업자·법인사업자는 부가세가 포함된 금액입니다. [정산내역 조회](https://sharelink-docs.toss.im/developers/open-api/api/settlement.md)의 **원천징수와 부가세**를 확인해 주세요.

### 판매자 제휴몰 유형

| 값               | 의미                            |
| --------------- | ----------------------------- |
| `NONE`          | 일반 셀러                         |
| `OASIS`         | 오아시스마켓                        |
| `null` 또는 필드 누락 | 유형 미확인. 일반 셀러를 뜻하는 `NONE`과 구분 |

* `partnerMallType`은 이벤트를 만들 때 확인한 값이며 전송·조회 시점에 다시 판별하지 않습니다.
* 취소·구매확정은 보관된 구매 이벤트의 값을 `null`이어도 승계합니다. 보관된 구매 이벤트가 없으면 이벤트를 만들 때 확인한 상품 정보를 씁니다.
* 지원하지 않는 카탈로그 유형은 `NONE`입니다. 알 수 없는 값은 오류 없이 일반 셀러처럼 처리하세요.

### 상품 기반 수수료 유형

| 값               | 의미                                           |
| --------------- | -------------------------------------------- |
| `EPIC_DEAL`     | 결제 시점에 선착순특가 수수료율이 적용된 주문상품                  |
| `null` 또는 필드 누락 | 상품 기반 수수료율이 적용되지 않았거나 이 필드를 제공하기 전에 만들어진 이벤트 |

* `productCommissionType`은 결제 시점의 값이며 전송·조회 시점에 다시 판별하지 않습니다.
* 수수료율 값은 담기지 않습니다. 예상 수익금은 `expectedCommissionAmount`를 그대로 사용합니다.
* 선착순특가 상품이어도 거래처에 별도로 정한 수수료율이 적용되면 `EPIC_DEAL`이 아닙니다.
* 취소·구매확정은 보관된 구매 이벤트의 값을 `null`이어도 승계합니다. 보관된 구매 이벤트가 없으면 주문상품에 기록된 결제 시점 수수료 기준으로 판정합니다.
* 결제 완료 시각이 2026-11-13 00:04(한국 시간) 이전인 주문상품은 주문 이벤트에서 `null`이어도 주문상품 조회에서는 `EPIC_DEAL`일 수 있습니다. 두 값이 다르면 주문상품 조회의 값을 따릅니다.
* 값이 추가될 수 있으니 알 수 없는 값도 오류로 처리하지 마세요.

### Push 추가 필드

| 필드                       | 타입             | 설명                                                                                                   |
| ------------------------ | -------------- | ---------------------------------------------------------------------------------------------------- |
| `buyerType`              | string         | 토스쇼핑 전체 첫 구매 여부. `FIRST_PURCHASE`(첫 구매), `REPURCHASE`(재구매), `UNKNOWN`(판정 불가). 제휴사 링크를 통한 첫 구매 여부가 아님 |
| `priceAmount`            | number \| null | 해당 주문상품의 전체 수량에 대한 상품 금액(원). 배송비는 별도                                                                 |
| `orderDeliveryFeeAmount` | number \| null | 해당 주문상품에 배분된 배송비(원). 배송비 할인을 뺀 금액                                                                    |
| `shoppingDiscountAmount` | number \| null | 해당 주문상품에 적용된 쇼핑 할인금액(원)                                                                              |
| `tossPayPointAmount`     | number \| null | 해당 주문상품에 사용한 토스포인트 금액(원). 배송비에 사용한 포인트도 포함                                                           |
| `orderSummary`           | object, 선택     | 같은 주문에서 이 제휴사에 귀속된 주문상품의 구매 시점 합계. `PURCHASE`에만 포함될 수 있으며, 제공할 수 없으면 필드 자체가 생략됨                      |

금액 구성을 확인할 수 없는 과거 이벤트 등은 금액 필드가 `null`일 수 있으니 0원과 구분하세요.

### 구매 시점 주문 합계

`orderSummary`는 같은 주문에서 수신 제휴사에 귀속된 주문상품만 합산하므로 전체 주문금액과 다를 수 있습니다. 있으면 아래 7개 필드가 모두 포함됩니다.

| `orderSummary` 내부 필드       | 타입     | 설명                                                                    |
| -------------------------- | ------ | --------------------------------------------------------------------- |
| `productCount`             | number | 합산한 주문상품 건수. 상품별 구매 수량의 합이 아님                                         |
| `priceAmount`              | number | 상품 금액 합계(원, 배송비 제외)                                                   |
| `orderDeliveryFeeAmount`   | number | 배분 배송비 합계(원, 배송비 할인 후)                                                |
| `shoppingDiscountAmount`   | number | 쇼핑 할인금액 합계(원)                                                         |
| `tossPayPointAmount`       | number | 토스포인트 사용금액 합계(원, 배송비에 사용한 포인트 포함)                                     |
| `commissionBaseAmount`     | number | 수수료 산정 기준액 합계(원)                                                      |
| `expectedCommissionAmount` | number | 상품별로 계산·반올림한 최초 예상 수익금의 합계(원, 원천징수 전). 주문 합계에 하나의 수수료율을 곱해 다시 계산하지 않음 |

```
orderSummary.commissionBaseAmount
  = orderSummary.priceAmount + orderSummary.orderDeliveryFeeAmount
    − orderSummary.shoppingDiscountAmount − orderSummary.tossPayPointAmount
```

* **주문당 한 번만 사용합니다.** 같은 주문의 구매 Push마다 같은 합계가 반복될 수 있으므로 수신 제휴사와 `orderId` 기준으로 한 번만 저장하고, 이벤트 수만큼 더하지 않습니다. 구매 시점 값이며 취소 후 남은 금액이나 확정 정산금액이 아닙니다.
* 최상위 금액 필드는 해당 주문상품 한 건의 값입니다.
* 주문 합계가 필요하면 [주문상품 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-products.md)로 해당 구매기간의 마지막 페이지까지 수집하거나 자사에 저장한 값에서 같은 `orderId`의 주문상품을 `orderProductId`별로 한 번만 합산합니다. 기준액과 예상 수익금은 `commissionBaseAmount`·`expectedCommissionAmount`를, 상품 금액·배송비·할인·포인트 합계는 구매 Push로 저장한 필드를 씁니다.

### 금액 2종이 정해지는 방식

아래에서 판매가는 배송비(배송비 할인 후)를 포함한 상품 금액입니다.

```
commissionBaseAmount     = priceAmount + orderDeliveryFeeAmount − shoppingDiscountAmount − tossPayPointAmount
expectedCommissionAmount = commissionBaseAmount × 수수료율   (원 단위 반올림)
```

| 항목         | 기준액에 어떻게 반영되나                                                                  |
| ---------- | ------------------------------------------------------------------------------ |
| 상품 금액·배송비  | (+) 해당 주문상품의 전체 수량 금액과 배분 배송비(배송비 할인 후). 상품 카드의 표시 가격으로 대신 계산하지 않음             |
| 수량         | (+) 판매가는 주문한 수량 전체 기준. 2개를 사면 2개 값이 출발점                                        |
| 쿠폰 할인      | (−) 구매자가 사용한 셀러 쿠폰·토스 쿠폰 등                                                     |
| 토스포인트      | (−) 구매자가 결제에 사용한 포인트. 배송비에 사용한 포인트도 뺌                                          |
| 토스 부담 즉시할인 | 판매가에 이미 반영돼 있어 여기서 또 빠지지 않음                                                    |
| 수수료율       | 거래처·상품에 적용된 율. 이벤트 본문에는 담기지 않음. 선착순특가 수수료율 적용 여부는 `productCommissionType`으로 확인 |

| 상황                    | 결과                                                                   |
| --------------------- | -------------------------------------------------------------------- |
| 같은 상품인데 주문마다 기준액이 다르다 | 정상. 쿠폰·포인트 사용액은 구매자마다 다름                                             |
| 기준액이 판매가보다 작다         | 정상. 기준액은 판매가를 넘지 않음                                                  |
| 기준액이 `0`으로 왔다         | 쿠폰과 포인트가 판매가 전액을 덮은 경우. `expectedCommissionAmount`도 `0`이며 데이터 누락이 아님 |

판매가 20,000원 상품의 예입니다(가상 데이터, 수수료율은 10%로 가정).

| 쿠폰 할인 |  토스포인트 | `commissionBaseAmount` | `expectedCommissionAmount` |
| ----: | -----: | ---------------------: | -------------------------: |
|     0 |      0 |                 20,000 |                      2,000 |
| 3,000 |      0 |                 17,000 |                      1,700 |
| 3,000 | 15,000 |                  2,000 |                        200 |
| 5,000 | 15,000 |                      0 |                          0 |

> **판매가로 캐시백을 미리 고지하지 마세요.** 쿠폰이나 포인트를 쓰면 `판매가 × 수수료율`과 어긋납니다. 캐시백 금액은 이벤트의 `commissionBaseAmount`를 받은 뒤 확정해 주세요.

`CANCEL`·`CONFIRM`은 보관된 구매 이벤트의 상품별 금액을 승계합니다.

`recordedAt`이 2026-11-13 20:39:40(한국 시간) 전인 이벤트와, 그런 구매 이벤트의 값을 승계한 취소·구매확정 이벤트는 `orderDeliveryFeeAmount`가 배송비 할인 전 금액이고 `tossPayPointAmount`에 배송비에 사용한 포인트가 빠져 있을 수 있으며, 기준액과 예상 수익금도 그 값으로 계산됩니다.

### 구매 이벤트 예시

가상 데이터입니다. 이 제휴사에 귀속된 주문상품이 2건인 주문의 1건이며, 나머지 1건의 기준액은 20,000원, 예상 수익금은 1,000원입니다.

```json
{
  "eventId": "c6514386-e795-3b67-86ab-7c4174f95801",
  "eventType": "PURCHASE",
  "orderId": "900001",
  "orderProductId": "900002",
  "productId": "100003",
  "productName": "예시 상품",
  "partnerMallType": "NONE",
  "productCommissionType": null,
  "quantity": 2,
  "commissionBaseAmount": 30000,
  "expectedCommissionAmount": 1500,
  "priceAmount": 30000,
  "orderDeliveryFeeAmount": 2500,
  "shoppingDiscountAmount": 2000,
  "tossPayPointAmount": 500,
  "buyerType": "REPURCHASE",
  "orderSummary": {
    "productCount": 2,
    "priceAmount": 50000,
    "orderDeliveryFeeAmount": 2500,
    "shoppingDiscountAmount": 2000,
    "tossPayPointAmount": 500,
    "commissionBaseAmount": 50000,
    "expectedCommissionAmount": 2500
  },
  "partnerRefId": "cashback_20260914_a1",
  "subTagId": "campaign_202609",
  "attribution": "DIRECT",
  "purchaseEventId": null,
  "occurredAt": "2026-09-14T10:00:00+09:00",
  "recordedAt": "2026-09-14T10:00:01+09:00"
}
```

### 전체 취소 이벤트 예시

보관된 구매 이벤트에 위 예시와 같은 상품별 금액이 있는 경우입니다.

```json
{
  "eventId": "f36944ca-97e8-3a3e-a2f0-e55cbf42a102",
  "eventType": "CANCEL",
  "orderId": "900001",
  "orderProductId": "900002",
  "productId": "100003",
  "productName": "예시 상품",
  "partnerMallType": "NONE",
  "productCommissionType": null,
  "quantity": 2,
  "commissionBaseAmount": 30000,
  "expectedCommissionAmount": 1500,
  "priceAmount": 30000,
  "orderDeliveryFeeAmount": 2500,
  "shoppingDiscountAmount": 2000,
  "tossPayPointAmount": 500,
  "buyerType": "REPURCHASE",
  "partnerRefId": "cashback_20260914_a1",
  "subTagId": "campaign_202609",
  "attribution": "DIRECT",
  "purchaseEventId": "c6514386-e795-3b67-86ab-7c4174f95801",
  "occurredAt": "2026-09-14T11:00:00+09:00",
  "recordedAt": "2026-09-14T11:00:01+09:00"
}
```

### 구매확정 이벤트 예시

주요 필드만 발췌했습니다. 실제 본문에는 상품 정보와 금액 등도 포함됩니다.

```json
{
  "eventId": "3f0d5c22-9b41-3a77-ae65-2c8f6d1b4703",
  "eventType": "CONFIRM",
  "partnerMallType": "NONE",
  "productCommissionType": null,
  "purchaseEventId": "c6514386-e795-3b67-86ab-7c4174f95801",
  "occurredAt": "2026-09-21T09:00:00+09:00",
  "recordedAt": "2026-09-21T09:00:01+09:00"
}
```

***

## 8. Secret Key가 바뀌면

서명은 전송 시점의 Secret Key 하나로만 만들며 구 키 유예 기간이 없으니, 재발급 직후 검증 키를 교체하세요. 재발급 직전에 시작된 요청은 구 키로 서명됐을 수 있으니 검증 실패 건은 거절한 뒤 [주문 이벤트 조회](https://sharelink-docs.toss.im/developers/open-api/api/order-events.md)로 채우세요. 재발급은 토스 운영자에게 문의해 주세요([연동 시작하기](https://sharelink-docs.toss.im/developers/open-api/auth.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/order-event-callback.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.
