---
title: "클레임(취소, 반품, 교환) 목록 조회"
method: GET
path: "/api/v3/shopping-fep/claims"
tags: ["클레임"]
---

# 클레임(취소, 반품, 교환) 목록 조회

`GET /api/v3/shopping-fep/claims`

가맹점의 클레임(취소, 반품, 교환) 목록을 조회합니다.

## 사용처
- 고객이 요청한 취소/반품/교환 클레임을 조회하고 관리할 수 있습니다
- 클레임 유형, 상태, 기간 등으로 필터링하여 조회할 수 있습니다

## 페이지네이션
- `size`: 페이지 크기 (기본값: 20, 최대: 100)
- 첫 페이지 조회 시 `nextToken`을 생략합니다
- 다음 페이지 조회 시 응답으로 받은 `nextToken` 값을 그대로 전달합니다

## 필터 조건
- status와 type을 보내지 않으면 모든 유형과 모든 상태의 클레임을 반환합니다. status와 type은 모두 포함하거나 모두 없어야 합니다.
- fromRequestDate, toRequestDate는 REQUESTED status일 때 유효합니다. 기본 값을 fromRequestDate는 7일 전, toRequestDate는 오늘이며, 조회 기간은 최대 7일입니다.
- fromRequestRevokedDate, toRequestRevokedDate는 REVOKED_REQUEST status일 때 유효합니다. 기본 값을 fromRequestRevokedDate는 7일 전, toRequestRevokedDate는 오늘이며, 조회 기간은 최대 7일입니다.

## 클레임 유형
- `CANCEL`: 취소 (결제 완료 이후 상태에서 취소 요청. 결제 완료 상태에서 사용자 취소나 이후 단계에서 판매자 취소는 클레임으로 잡히지 않습니다.)
- `EXCHANGE`: 교환 (상품 교환 요청)
- `RETURN`: 반품 (상품 반품 요청)

## Query parameters

- `type` 'CANCEL' | 'EXCHANGE' | 'RETURN'
- `status` 'REQUESTED' | 'REVOKED_REQUEST'
- `fromRequestDate` string, date
- `toRequestDate` string, date
- `fromRequestRevokedDate` string, date
- `toRequestRevokedDate` string, date
- `orderIds` integer[]
- `nextToken` string
- `size` integer
- `partnerName` string

## Response `200`

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

- object
  - `resultType` 'SUCCESS' | 'FAIL' — 응답 결과 타입
  - `error` object — 에러 응답, resultType FAIL 시 제공
    - `errorCode` 'INVALID_REQUEST' | 'REQUEST_FAILED' | 'UNKNOWN' | 'COMMON_ERROR' — 에러 코드
    - `reason` string — 에러 사유
  - `success` GetClaimListFepResponse — 클레임 목록 응답
    - `items` GetClaimFepResponse[], required — 클레임 상세 목록
      - `id` integer, required — 클레임 ID
      - `requestedDt` string, date-time — 클레임 요청 일시
      - `type` 'CANCEL' | 'EXCHANGE' | 'RETURN', required — 클레임 타입
      - `status` 'REQUESTED' | 'REVOKED_REQUEST' | 'REJECTED_REQUEST' | 'COLLECTING' | 'COLLECTED' | 'REJECTED' | 'DELIVERING' | 'COMPLETED' | 'CANCELLED_ORDER', required — 클레임 상태
      - `requestReason` string, required — 클레임 요청 사유
      - `requestDetailReason` string — 클레임 요청 상세 사유
      - `requestImages` string[], required — 클레임 요청 시 첨부한 이미지 URL 목록
      - `requestDeliveryPenaltyCharger` 'USER' | 'MERCHANT', required — 클레임 요청 시 배송비 페널티 부담자
      - `refundOneWayDeliveryFee` integer, required — 편도 배송비 환불 금액
      - `roundTripDeliveryFee` integer, required — 왕복 배송비
      - `returnAddress` string — 반품/교환 수거 주소
      - `order` GetClaimFepResponseOrder, required — 클레임 관련 주문 정보
        - `id` integer, required — 주문을 식별하는 유니크한 값
        - `orderProductId` integer, required — 각 주문의 유니크한 상품 식별용 ID
        - `ordererName` string, required — 주문자명
        - `ordererPhoneNumber` string, required — 주문자 연락처
        - `receiverName` string, required — 수령인명
        - `receiverPhoneNumber` string, required — 수령인 연락처
        - `deliveryCompany` 'CJ대한통운' | '우체국택배' | '한덱스' | '합동택배' | '한의사랑택배' | '굿투럭' | '우리택배' | '홈픽택배' | '용마로지스' | '컬리넥스트마일' | '큐런택배' | '지니고' | '한샘서비스원' | 'LG전자' | '썬더히어로' | '핑퐁' | 'GTS로지스' | 'UFO로지스' | '에이치케이홀딩스' | '더바오' | '탱고앤고' | 'ARGO' | '한진택배' | '로젠택배' | '대신택배' | 'CU편의점택배' | '천일택배' | '애니트랙' | '우리한방택배' | 'IK물류' | '원더스퀵' | '풀앳홈' | '두발히어로' | '오늘의픽업' | 'NDEXKOREA' | '부릉' | '팀프레시' | '발렉스' | '로지스팟' | '딜리래빗' | 'HTNS' | '라스트마일' | '투데이' | '자이언트' | '롯데택배' | '일양로지스' | '경동택배' | 'GS25편의점택배' | '건영택배' | 'SLX택배' | '농협택배' | '성훈물류' | '로지스밸리택배' | '삼성전자물류' | '위니아딤채' | '큐익스프레스' | '로지스밸리' | '도도플렉스' | '1004홈' | '롯데칠성' | '엔티엘피스' | '홈픽' | '지오피' | '케이제이티' | '오늘회러쉬' | '현대글로비스' | '위니온로지스' | '딜리박스' | '이스트라' | 'hy' | 'CR로지텍' | '나은물류' | '지케이글로벌' | '유피로지스(제주)' | '반얀로지스틱스' | '삼다수 가정배송' | '프리즘코리아' | '올인닷컴' | '물류대장(택배)' | '풀무원샘물' | 'SLO' | '바로스' | '레터스' | '벤더피아' | '세븐일레븐(착한택배)' | '물류대장(설치)' | 'BoxN' | '리터니즈' | '직접전달' — 원주문 배송 택배사
        - `shippingTrackingNumber` string — 원주문 송장번호
        - `address` string, required — 배송 주소
        - `price` integer, required — 상품 가격
        - `createdDt` string, date-time, required — 주문 생성 일시
      - `product` GetClaimFepResponseProduct, required — 클레임 관련 상품 정보
        - `id` integer, required — 상품 식별용 ID
        - `name` string, required — 상품명
        - `optionName` string, required — 옵션명
        - `quantity` integer, required — 주문 수량
      - `claimDeliveryPaymentAmount` integer — 클레임 배송비 결제 금액
    - `nextToken` string, required — 다음 페이지를 위한 커서 정보
    - `hasNext` boolean, required — 다음 페이지 존재 여부

---

[API](https://skmtc.net/toss/apis/shoppingfep-api.md) · [All operations](https://skmtc.net/toss/apis/shoppingfep-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/toss/shoppingfep-api/revisions/57a25c0addc6/schema)