# 클레임 처리하기

## 클레임 이해하기

단순변심, 상품하자 등 다양한 이유로 구매자는 취소, 반품, 교환을 요청할 수 있어요. 판매자는 구매자의 요청을 확인하고 적절한 조치를 취해야 됩니다.

먼저 토스쇼핑의 클레임 과정을 살펴볼게요. 아래 그림에 보이듯이 구매자는 구매확정을 제외한 모든 주문 상태에서 클레임을 요청할 수 있어요. 판매자는 요청된 클레임을 승인 또는 거절할 수 있어요. 취소 요청을 승인하면 주문이 즉시 취소되고 구매자에게 주문금액이 환불돼요. 반면, 교환・반품 요청을 승인하면 주문 상품이 수거되고, 수거된 상품을 검토한 다음에 클레임을 최종 승인 및 거절해야 됩니다.

각 클레임을 처리하는 자세한 방법은 [상세 가이드](#undefined-2)에서 확인해보세요.

<figure><img src="https://1893239884-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5jZ0MNZGU289cgosea36%2Fuploads%2FhK1NlyC1xmKdLvFhuNcg%2Fimage.png?alt=media&#x26;token=8b5e95d0-c625-4c5e-b30f-fa73b6c82fc0" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="137.8565673828125">클레임 유형</th><th width="160.22869873046875">요청 가능한 주문상태</th><th>특징</th></tr></thead><tbody><tr><td>취소(<code>CANCEL</code>)</td><td>결제완료, 발송지연, 상품준비중</td><td><ul><li>결제완료 상태에서 요청된 취소는 즉시 취소되며 별도 셀러 액션이 필요 없음</li><li>발송지연, 상품준비중 상태에서 요청된 취소는 셀러의 승인 또는 거절이 필요함</li></ul></td></tr><tr><td>교환(<code>EXCHANGE</code>)</td><td> 배송중, 배송완료</td><td><ul><li>판매자는 교환 요청을 승인 또는 거절할 수 있음</li><li>판매자는 상품 수거 이후 교환을 재배송 또는 반려할 수 있음</li><li>재배송이 완료되면 셀러는 교환을 완료해야 됨</li></ul></td></tr><tr><td>반품(<code>RETURN</code>)</td><td>배송중, 배송완료</td><td><ul><li>판매자는 반품 요청을 승인 또는 거절할 수 있음</li><li>판매자는 상품 수거 이후 반품을 완료 또는 반려할 수 있음</li></ul></td></tr></tbody></table>

## 클레임 요청 확인하기

구매자가 요청한 클레임은 [클레임 목록 조회 API](https://shopping-docs.toss.im/dev/api-2/claim#get-api-v3-shopping-fep-claims)로 확인해주세요. API의 쿼리 파라미터로 취소·교환·반품을 지정하면 '요청중' 상태인 클레임을 모두 확인할 수 있어요.

특정 트리거로 클레임 요청 목록 조희 API를 호출하거나 10\~60분 주기로 API를 Polling해주세요. 10분 이하의 주기로 Polling하면 토스쇼핑 API의 이용이 제한될 수 있으니 주의해주세요.

### 클레임 요청 목록 조희 API

**GET**  `/api/v3/shopping-fep/claims?type={CLAIM_TYPE}&status={CLAIM_STATUS}`

| 필수 쿼리 파라미터                                               | 설명                                                                                                                                                                |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type** ・ <mark style="color:$success;">**필수**</mark>   | <p>클레임 유형입니다. 아래 ENUM 중 하나를 사용해주세요.<br>- <code>CANCEL</code>: 취소 요청을 불러옵니다.<br>- <code>EXCHANGE</code>: 교환 요청을 불러옵니다.<br>- <code>RETURN</code>: 반품 요청을 불러옵니다.</p> |
| **status** ・ <mark style="color:$success;">**필수**</mark> | 조회할 클레임의 상태입니다. 항상 `REQUESTED`로 고정해주세요. '요청' 상태인 클레임을 반환합니다.                                                                                                      |

#### Request

```bash
  curl --request GET \
  --url 'https://shopping-fep.toss.im/api/v3/shopping-fep/claims?type=CANCEL&status=REQUESTED' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'Content-Type: application/json'
```

#### Response

```json
{
    "resultType":"SUCCESS",
    "success":
        {
            "items":[
                "id": "5EnNZRJGvaBX7zk2yd8y" // 클레임 ID
                "requestedDt": "2025-04-29T21:12:55" // 클레임이 요청된 시간
                "status": "REQUESTED" // 클레임의 상태
                "requestReason": "주문 실수" // 클레임 이유
                ...    
            ],
            "nextToken":"eyJsYXN0Q2xhaW1JZCI6bnVsbH0=" // 다음 API 호출에 사용할 수 있는 cursor
        }
}
```

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

{% hint style="info" %}
토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 [연동/개발 문의](https://discord.gg/xPz6H9NZ3P)에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.
{% endhint %}

## 상세 가이드 확인하기

클레임 목록을 요청하는 방법은 같지만 취소, 교환, 반품을 처리하는 방법은 조금씩 달라요. 아래 가이드에서 각 클레임을 어떻게 처리하는지 안내드릴게요.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>취소</td><td><a href="claim/cancel">cancel</a></td></tr><tr><td>교환</td><td><a href="claim/exchange">exchange</a></td></tr><tr><td>반품</td><td><a href="claim/return">return</a></td></tr></tbody></table>

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

{% hint style="info" %}
토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 [연동/개발 문의](https://discord.com/invite/rpSmJ2Su)에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.
{% endhint %}