클레임 처리하기

클레임은 결제완료 이후에 일어난 취소, 반품, 교환 요청이에요.

클레임 이해하기

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

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

각 클레임을 처리하는 자세한 방법은 상세 가이드에서 확인해보세요.

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

클레임 요청 확인하기

구매자가 요청한 클레임은 클레임 목록 조회 API로 확인해주세요. API의 쿼리 파라미터로 취소·교환·반품을 지정하면 '요청중' 상태인 클레임을 모두 확인할 수 있어요.

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

클레임 요청 목록 조희 API

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

필수 쿼리 파라미터	설명
type ・ 필수	클레임 유형입니다. 아래 ENUM 중 하나를 사용해주세요. - CANCEL: 취소 요청을 불러옵니다. - EXCHANGE: 교환 요청을 불러옵니다. - RETURN: 반품 요청을 불러옵니다.
status ・ 필수	조회할 클레임의 상태입니다. 항상 REQUESTED로 고정해주세요. '요청' 상태인 클레임을 반환합니다.

Request

  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

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

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

토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 연동/개발 문의에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.

상세 가이드 확인하기

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

취소

교환

반품

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

토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 연동/개발 문의에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.