# 클레임 (취소/교환/반품)

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

> 가맹점의 클레임(취소, 반품, 교환) 목록을 조회합니다.\
> \
> \## 사용처\
> \- 고객이 요청한 취소/반품/교환 클레임을 조회하고 관리할 수 있습니다\
> \- 클레임 유형, 상태, 기간 등으로 필터링하여 조회할 수 있습니다\
> \
> \## 페이지네이션\
> \- \`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\`: 반품 (상품 반품 요청)

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"GetClaimListFepResponse":{"required":["hasNext","items","nextToken"],"type":"object","properties":{"items":{"type":"array","description":"클레임 상세 목록","items":{"$ref":"#/components/schemas/GetClaimFepResponse"}},"nextToken":{"type":"string","description":"다음 페이지를 위한 커서 정보"},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부"}},"description":"클레임 목록 응답"},"GetClaimFepResponse":{"required":["id","order","product","refundOneWayDeliveryFee","requestDeliveryPenaltyCharger","requestImages","requestReason","roundTripDeliveryFee","status","type"],"type":"object","properties":{"id":{"type":"integer","description":"클레임 ID","format":"int64"},"requestedDt":{"type":"string","description":"클레임 요청 일시","format":"date-time"},"type":{"type":"string","description":"클레임 타입","enum":["CANCEL","EXCHANGE","RETURN"]},"status":{"type":"string","description":"클레임 상태","enum":["REQUESTED","REVOKED_REQUEST","REJECTED_REQUEST","COLLECTING","COLLECTED","REJECTED","DELIVERING","COMPLETED","CANCELLED_ORDER"]},"requestReason":{"type":"string","description":"클레임 요청 사유"},"requestDetailReason":{"type":"string","description":"클레임 요청 상세 사유"},"requestImages":{"type":"array","description":"클레임 요청 시 첨부한 이미지 URL 목록","items":{"type":"string","description":"클레임 요청 시 첨부한 이미지 URL 목록"}},"requestDeliveryPenaltyCharger":{"type":"string","description":"클레임 요청 시 배송비 페널티 부담자","enum":["USER","MERCHANT"]},"refundOneWayDeliveryFee":{"type":"integer","description":"편도 배송비 환불 금액","format":"int32"},"roundTripDeliveryFee":{"type":"integer","description":"왕복 배송비","format":"int32"},"returnAddress":{"type":"string","description":"반품/교환 수거 주소"},"order":{"$ref":"#/components/schemas/GetClaimFepResponseOrder"},"product":{"$ref":"#/components/schemas/GetClaimFepResponseProduct"},"claimDeliveryPaymentAmount":{"type":"integer","description":"클레임 배송비 결제 금액","format":"int64"}},"description":"클레임 상세 응답"},"GetClaimFepResponseOrder":{"required":["address","createdDt","id","orderProductId","ordererName","ordererPhoneNumber","price","receiverName","receiverPhoneNumber"],"type":"object","properties":{"id":{"type":"integer","description":"주문을 식별하는 유니크한 값","format":"int64"},"orderProductId":{"type":"integer","description":"각 주문의 유니크한 상품 식별용 ID","format":"int64"},"ordererName":{"type":"string","description":"주문자명"},"ordererPhoneNumber":{"type":"string","description":"주문자 연락처"},"receiverName":{"type":"string","description":"수령인명"},"receiverPhoneNumber":{"type":"string","description":"수령인 연락처"},"deliveryCompany":{"type":"string","description":"원주문 배송 택배사","enum":["CJ대한통운","우체국택배","한덱스","합동택배","한의사랑택배","굿투럭","우리택배","홈픽택배","용마로지스","컬리넥스트마일","큐런택배","지니고","한샘서비스원","LG전자","썬더히어로","핑퐁","GTS로지스","UFO로지스","에이치케이홀딩스","더바오","탱고앤고","ARGO","한진택배","로젠택배","대신택배","CU편의점택배","천일택배","애니트랙","우리한방택배","IK물류","원더스퀵","풀앳홈","두발히어로","오늘의픽업","NDEXKOREA","부릉","팀프레시","발렉스","로지스팟","딜리래빗","HTNS","라스트마일","투데이","자이언트","롯데택배","일양로지스","경동택배","GS25편의점택배","건영택배","SLX택배","농협택배","성훈물류","로지스밸리택배","삼성전자물류","위니아딤채","큐익스프레스","로지스밸리","도도플렉스","1004홈","롯데칠성","엔티엘피스","홈픽","지오피","케이제이티","오늘회러쉬","현대글로비스","위니온로지스","딜리박스","이스트라","hy","CR로지텍","나은물류","지케이글로벌","유피로지스(제주)","반얀로지스틱스","삼다수 가정배송","프리즘코리아","올인닷컴","물류대장(택배)","풀무원샘물","SLO","바로스","레터스","벤더피아","세븐일레븐(착한택배)","물류대장(설치)","BoxN","리터니즈","직접전달"]},"shippingTrackingNumber":{"type":"string","description":"원주문 송장번호"},"address":{"type":"string","description":"배송 주소"},"price":{"type":"integer","description":"상품 가격","format":"int64"},"createdDt":{"type":"string","description":"주문 생성 일시","format":"date-time"}},"description":"클레임 관련 주문 정보"},"GetClaimFepResponseProduct":{"required":["id","name","optionName","quantity"],"type":"object","properties":{"id":{"type":"integer","description":"상품 식별용 ID","format":"int64"},"name":{"type":"string","description":"상품명"},"optionName":{"type":"string","description":"옵션명"},"quantity":{"type":"integer","description":"주문 수량","format":"int32"}},"description":"클레임 관련 상품 정보"}}},"paths":{"/api/v3/shopping-fep/claims":{"get":{"tags":["클레임"],"summary":"클레임(취소, 반품, 교환) 목록 조회","description":"가맹점의 클레임(취소, 반품, 교환) 목록을 조회합니다.\n\n## 사용처\n- 고객이 요청한 취소/반품/교환 클레임을 조회하고 관리할 수 있습니다\n- 클레임 유형, 상태, 기간 등으로 필터링하여 조회할 수 있습니다\n\n## 페이지네이션\n- `size`: 페이지 크기 (기본값: 20, 최대: 100)\n- 첫 페이지 조회 시 `nextToken`을 생략합니다\n- 다음 페이지 조회 시 응답으로 받은 `nextToken` 값을 그대로 전달합니다\n\n## 필터 조건\n- status와 type을 보내지 않으면 모든 유형과 모든 상태의 클레임을 반환합니다. status와 type은 모두 포함하거나 모두 없어야 합니다.\n- fromRequestDate, toRequestDate는 REQUESTED status일 때 유효합니다. 기본 값을 fromRequestDate는 7일 전, toRequestDate는 오늘이며, 조회 기간은 최대 7일입니다.\n- fromRequestRevokedDate, toRequestRevokedDate는 REVOKED_REQUEST status일 때 유효합니다. 기본 값을 fromRequestRevokedDate는 7일 전, toRequestRevokedDate는 오늘이며, 조회 기간은 최대 7일입니다.\n\n## 클레임 유형\n- `CANCEL`: 취소 (결제 완료 이후 상태에서 취소 요청. 결제 완료 상태에서 사용자 취소나 이후 단계에서 판매자 취소는 클레임으로 잡히지 않습니다.)\n- `EXCHANGE`: 교환 (상품 교환 요청)\n- `RETURN`: 반품 (상품 반품 요청)","operationId":"getClaims","parameters":[{"name":"type","in":"query","description":"조회용 클레임 유형. 값을 입력하지 않으면 모든 type에 대해 내려줍니다. type 값을 입력하지 않을 때는 status도 입력하지 않아야 합니다.","required":false,"schema":{"type":"string","enum":["CANCEL","EXCHANGE","RETURN"]}},{"name":"status","in":"query","description":"조회용 클레임 상태. 값을 입력하지 않으면 모든 status에 대해 내려줍니다. status 값을 입력하지 않을 때는 type도 입력하지 않아야 합니다.","required":false,"schema":{"type":"string","enum":["REQUESTED","REVOKED_REQUEST"]}},{"name":"fromRequestDate","in":"query","description":"조회 시작일자 yyyy-MM-dd 형태 (기본값: 오늘)","required":false,"schema":{"type":"string","format":"date"}},{"name":"toRequestDate","in":"query","description":"조회 종료일자 yyyy-MM-dd 형태 (기본값: fromRequestDate의 7일 전)","required":false,"schema":{"type":"string","format":"date"}},{"name":"fromRequestRevokedDate","in":"query","description":"클레임 요청 철회 조회 시작일자 yyyy-MM-dd 형태 (기본값: 7일 전, status가 REVOKED_REQUEST일 때 유효)","required":false,"schema":{"type":"string","format":"date"}},{"name":"toRequestRevokedDate","in":"query","description":"클레임 요청 철회 조회 종료일자 yyyy-MM-dd 형태 (기본값: 오늘, status가 REVOKED_REQUEST일 때 유효)","required":false,"schema":{"type":"string","format":"date"}},{"name":"orderIds","in":"query","description":"주문 번호 목록 (복수 조회, orderId와 함께 사용 가능)","required":false,"schema":{"type":"array","items":{"type":"integer","format":"int64"}}},{"name":"nextToken","in":"query","description":"다음 페이지를 위한 커서 정보 (직전 호출에서 받은 nextToken을 그대로 넘겨 호출)","required":false,"schema":{"type":"string"}},{"name":"size","in":"query","description":"페이지 사이즈 (기본값: 20, 최대 100)","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/GetClaimListFepResponse"}}}}}}}}}}}
```

## 판매자 주문 취소

> 결제 완료 상태의 주문 상품에 대해 판매자가 취소 처리합니다.\
> \
> \## 판매자 취소 처리 가능한 주문 상품 상태\
> \- \`CANCELED\_PAYMENT\`: 결제취소\
> \- \`EXCHANGE\`: 결제완료\
> \- \`RETURN\`: 상품준비중\
> \- \`DELAY\_SHIPPING\`: 발송지연\
> \- \`DELIVERING\`: 배송중\
> \- \`DELIVERED\`: 배송완료\
> \- \`CONFIRMED\_ORDER\`: 구매확정\
> \- \`REQUESTED\_EXCHANGE\`: 교환접수\
> \- \`ONGOING\_EXCHANGE\`: 교환처리중\
> \- \`COMPLETED\_EXCHANGE\`: 교환완료\
> \- \`REQUESTED\_RETURN\`: 반품접수\
> \- \`ONGOING\_RETURN\`: 반품처리중

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CancelOrderBySellerRequest":{"required":["deliveryPenaltyCharger"],"type":"object","properties":{"deliveryPenaltyCharger":{"type":"string","description":"배송비 부과 책임자","enum":["USER","MERCHANT"]},"reason":{"type":"string","description":"주문 취소 사유 (100자 이내)\n\n- 100자를 초과할 경우 100자까지만 저장됩니다"},"detailReason":{"type":"string","description":"주문 취소 상세 사유 (250자 이내)\n\n- 250자를 초과할 경우 250자까지만 저장됩니다"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"판매자 주문 취소 요청"}}},"paths":{"/api/v3/shopping-fep/order-products/{orderProductId}/seller-cancel":{"post":{"tags":["주문"],"summary":"판매자 주문 취소","description":"결제 완료 상태의 주문 상품에 대해 판매자가 취소 처리합니다.\n\n## 판매자 취소 처리 가능한 주문 상품 상태\n- `CANCELED_PAYMENT`: 결제취소\n- `EXCHANGE`: 결제완료\n- `RETURN`: 상품준비중\n- `DELAY_SHIPPING`: 발송지연\n- `DELIVERING`: 배송중\n- `DELIVERED`: 배송완료\n- `CONFIRMED_ORDER`: 구매확정\n- `REQUESTED_EXCHANGE`: 교환접수\n- `ONGOING_EXCHANGE`: 교환처리중\n- `COMPLETED_EXCHANGE`: 교환완료\n- `REQUESTED_RETURN`: 반품접수\n- `ONGOING_RETURN`: 반품처리중","operationId":"cancelOrderBySeller","parameters":[{"name":"orderProductId","in":"path","description":"주문 상품 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelOrderBySellerRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 취소 요청 승인

> 고객의 취소 요청을 승인하여 환불 처리를 진행합니다.\
> \
> \## 처리 흐름\
> 1 고객이 취소 요청 (status: REQUESTED)\
> 2 판매자가 취소 요청 승인 (이 API 호출)\
> 3 환불 처리 완료

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/cancel/approval":{"post":{"tags":["클레임"],"summary":"취소 요청 승인","description":"고객의 취소 요청을 승인하여 환불 처리를 진행합니다.\n\n## 처리 흐름\n1 고객이 취소 요청 (status: REQUESTED)\n2 판매자가 취소 요청 승인 (이 API 호출)\n3 환불 처리 완료","operationId":"approveCancelRequest","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 취소 요청 거절

> 고객의 취소 요청을 거절하고 배송을 진행합니다.\
> \
> \## 처리 흐름\
> 1 고객이 취소 요청 (status: REQUESTED)\
> 2 판매자가 취소 요청 거절 (이 API 호출)\
> 3 배송 회사와 송장번호를 등록하여 배송 진행

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RejectCancelRequestFepRequest":{"required":["deliveryCompany"],"type":"object","properties":{"deliveryCompany":{"type":"string","description":"배송 회사","enum":["CJ대한통운","우체국택배","한덱스","합동택배","한의사랑택배","굿투럭","우리택배","홈픽택배","용마로지스","컬리넥스트마일","큐런택배","지니고","한샘서비스원","LG전자","썬더히어로","핑퐁","GTS로지스","UFO로지스","에이치케이홀딩스","더바오","탱고앤고","ARGO","한진택배","로젠택배","대신택배","CU편의점택배","천일택배","애니트랙","우리한방택배","IK물류","원더스퀵","풀앳홈","두발히어로","오늘의픽업","NDEXKOREA","부릉","팀프레시","발렉스","로지스팟","딜리래빗","HTNS","라스트마일","투데이","자이언트","롯데택배","일양로지스","경동택배","GS25편의점택배","건영택배","SLX택배","농협택배","성훈물류","로지스밸리택배","삼성전자물류","위니아딤채","큐익스프레스","로지스밸리","도도플렉스","1004홈","롯데칠성","엔티엘피스","홈픽","지오피","케이제이티","오늘회러쉬","현대글로비스","위니온로지스","딜리박스","이스트라","hy","CR로지텍","나은물류","지케이글로벌","유피로지스(제주)","반얀로지스틱스","삼다수 가정배송","프리즘코리아","올인닷컴","물류대장(택배)","풀무원샘물","SLO","바로스","레터스","벤더피아","세븐일레븐(착한택배)","물류대장(설치)","BoxN","리터니즈","직접전달"]},"shippingTrackingNumber":{"type":"string","description":"송장번호. 직접전달일 때는 null 가능. 하이픈(-)은 자동 제거됩니다"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"취소 요청 거절 요청"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/cancel/rejection":{"post":{"tags":["클레임"],"summary":"취소 요청 거절","description":"고객의 취소 요청을 거절하고 배송을 진행합니다.\n\n## 처리 흐름\n1 고객이 취소 요청 (status: REQUESTED)\n2 판매자가 취소 요청 거절 (이 API 호출)\n3 배송 회사와 송장번호를 등록하여 배송 진행","operationId":"rejectCancelRequest","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectCancelRequestFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 교환 요청 승인

> 고객의 교환 요청을 승인하여 상품 수거를 시작합니다.\
> \
> \## 처리 흐름\
> 1 고객이 교환 요청 (status: REQUESTED)\
> 2 판매자가 교환 요청 승인 (이 API 호출)\
> 3 수거 진행 (status: 수거중)\
> 4 수거 완료 후 상품 입고 확인\
> 5 교환 재배송

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/exchange/approval":{"post":{"tags":["클레임"],"summary":"교환 요청 승인","description":"고객의 교환 요청을 승인하여 상품 수거를 시작합니다.\n\n## 처리 흐름\n1 고객이 교환 요청 (status: REQUESTED)\n2 판매자가 교환 요청 승인 (이 API 호출)\n3 수거 진행 (status: 수거중)\n4 수거 완료 후 상품 입고 확인\n5 교환 재배송","operationId":"approveExchangeRequest_1","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 교환 요청 거절

> 고객의 교환 요청을 거절합니다.\
> \
> \## 처리 흐름\
> 1 고객이 교환 요청 (status: REQUESTED)\
> 2 판매자가 교환 요청 거절 (이 API 호출)\
> 3 교환 요청이 반려되고 주문은 정상 진행

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RejectExchangeRequestFepRequest":{"required":["requestRejectReason"],"type":"object","properties":{"requestRejectReason":{"type":"string","description":"교환 요청 거절 사유 (최대 300자, 초과 시 잘림)"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"교환 요청 거절 요청"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/exchange/rejection":{"post":{"tags":["클레임"],"summary":"교환 요청 거절","description":"고객의 교환 요청을 거절합니다.\n\n## 처리 흐름\n1 고객이 교환 요청 (status: REQUESTED)\n2 판매자가 교환 요청 거절 (이 API 호출)\n3 교환 요청이 반려되고 주문은 정상 진행","operationId":"rejectExchangeRequest","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectExchangeRequestFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 교환 수거 완료

> 교환 상품의 수거를 완료하고 상품 입고를 확인합니다.\
> \
> \## 처리 흐름\
> 1 교환 요청 승인 후 수거 진행\
> 2 상품 수거 완료 (이 API 호출)\
> 3 상품 입고 확인 (status: 수거완료)\
> 4 교환 재배송 준비

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/exchange/collection":{"post":{"tags":["클레임"],"summary":"교환 수거 완료","description":"교환 상품의 수거를 완료하고 상품 입고를 확인합니다.\n\n## 처리 흐름\n1 교환 요청 승인 후 수거 진행\n2 상품 수거 완료 (이 API 호출)\n3 상품 입고 확인 (status: 수거완료)\n4 교환 재배송 준비","operationId":"completeExchangeCollection","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 교환 완료

> 교환 재배송이 완료되어 교환 프로세스를 종료합니다.\
> \
> \## 처리 흐름\
> 1 교환 재배송 진행\
> 2 고객이 상품 수령\
> 3 교환 완료 처리 (이 API 호출)\
> 4 교환 프로세스 종료

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/exchange/completion":{"post":{"tags":["클레임"],"summary":"교환 완료","description":"교환 재배송이 완료되어 교환 프로세스를 종료합니다.\n\n## 처리 흐름\n1 교환 재배송 진행\n2 고객이 상품 수령\n3 교환 완료 처리 (이 API 호출)\n4 교환 프로세스 종료","operationId":"completeExchange","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 교환 반려

> 수거된 상품의 상태가 불량하여 교환을 반려합니다.\
> \
> \## 처리 흐름\
> 1 교환 요청 승인 후 수거 진행\
> 2 수거된 상품 확인\
> 3 상품 상태 불량으로 교환 반려 (이 API 호출)\
> 4 교환 거절 처리 완료

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RejectExchangeCollectionFepRequest":{"required":["rejectReason"],"type":"object","properties":{"rejectReason":{"type":"string","description":"교환 반려 사유 (최대 300자, 초과 시 잘림)"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"교환 반려 요청"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/exchange/collection-rejection":{"post":{"tags":["클레임"],"summary":"교환 반려","description":"수거된 상품의 상태가 불량하여 교환을 반려합니다.\n\n## 처리 흐름\n1 교환 요청 승인 후 수거 진행\n2 수거된 상품 확인\n3 상품 상태 불량으로 교환 반려 (이 API 호출)\n4 교환 거절 처리 완료","operationId":"rejectExchangeCollection_1","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectExchangeCollectionFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 교환 재배송

> 수거 완료된 교환 상품을 재배송합니다.\
> \
> \## 처리 흐름\
> 1 교환 수거 완료\
> 2 상품 입고 확인\
> 3 교환 재배송 시작 (이 API 호출)\
> 4 배송 회사와 송장번호 등록\
> 5 재배송 진행 (status: 재배송중)

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"StartExchangeDeliveryFepRequest":{"required":["deliveryCompany","shippingTrackingNumber"],"type":"object","properties":{"deliveryCompany":{"type":"string","description":"배송 회사","enum":["CJ대한통운","우체국택배","한덱스","합동택배","한의사랑택배","굿투럭","우리택배","홈픽택배","용마로지스","컬리넥스트마일","큐런택배","지니고","한샘서비스원","LG전자","썬더히어로","핑퐁","GTS로지스","UFO로지스","에이치케이홀딩스","더바오","탱고앤고","ARGO","한진택배","롯데택배","로젠택배","대신택배","CU편의점택배","천일택배","애니트랙","우리한방택배","IK물류","원더스퀵","풀앳홈","두발히어로","오늘의픽업","NDEXKOREA","부릉","팀프레시","발렉스","로지스팟","딜리래빗","HTNS","라스트마일","투데이","자이언트","일양로지스","경동택배","GS25편의점택배","건영택배","SLX택배","농협택배","성훈물류","로지스밸리택배","삼성전자물류","위니아딤채","큐익스프레스","로지스밸리","도도플렉스","1004홈","롯데칠성","엔티엘피스","홈픽","지오피","케이제이티","오늘회러쉬","현대글로비스","위니온로지스","딜리박스","이스트라","hy","CR로지텍","나은물류","지케이글로벌","유피로지스(제주)","반얀로지스틱스","삼다수 가정배송","프리즘코리아","올인닷컴","물류대장(택배)","풀무원샘물","SLO","바로스","레터스","벤더피아","세븐일레븐(착한택배)","물류대장(설치)","BoxN","리터니즈","직접전달"]},"shippingTrackingNumber":{"type":"string","description":"송장번호. 하이픈(-)은 자동 제거됩니다"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"교환 재배송 요청"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/exchange/delivery":{"post":{"tags":["클레임"],"summary":"교환 재배송","description":"수거 완료된 교환 상품을 재배송합니다.\n\n## 처리 흐름\n1 교환 수거 완료\n2 상품 입고 확인\n3 교환 재배송 시작 (이 API 호출)\n4 배송 회사와 송장번호 등록\n5 재배송 진행 (status: 재배송중)","operationId":"startExchangeDelivery","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartExchangeDeliveryFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 반품 요청 승인

> 고객의 반품 요청을 승인하여 상품 수거를 시작합니다.\
> \
> \## 처리 흐름\
> 1 고객이 반품 요청 (status: REQUESTED)\
> 2 판매자가 반품 요청 승인 (이 API 호출)\
> 3 수거 진행 (status: 수거중)\
> 4 수거 완료 후 상품 입고 확인\
> 5 반품 완료 및 환불 처리

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/return/approval":{"post":{"tags":["클레임"],"summary":"반품 요청 승인","description":"고객의 반품 요청을 승인하여 상품 수거를 시작합니다.\n\n## 처리 흐름\n1 고객이 반품 요청 (status: REQUESTED)\n2 판매자가 반품 요청 승인 (이 API 호출)\n3 수거 진행 (status: 수거중)\n4 수거 완료 후 상품 입고 확인\n5 반품 완료 및 환불 처리","operationId":"approveReturnRequest_1","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 반품 요청 거절

> 고객의 반품 요청을 거절합니다.\
> \
> \## 처리 흐름\
> 1 고객이 반품 요청 (status: REQUESTED)\
> 2 판매자가 반품 요청 거절 (이 API 호출)\
> 3 반품 요청이 반려되고 주문은 정상 진행

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RejectReturnRequestFepRequest":{"required":["requestRejectReason"],"type":"object","properties":{"requestRejectReason":{"type":"string","description":"반품 요청 거절 사유 (최대 300자, 초과 시 잘림)"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"반품 요청 거절 요청"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/return/rejection":{"post":{"tags":["클레임"],"summary":"반품 요청 거절","description":"고객의 반품 요청을 거절합니다.\n\n## 처리 흐름\n1 고객이 반품 요청 (status: REQUESTED)\n2 판매자가 반품 요청 거절 (이 API 호출)\n3 반품 요청이 반려되고 주문은 정상 진행","operationId":"rejectReturnRequest","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectReturnRequestFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 반품 수거 완료

> 반품 상품의 수거를 완료하고 상품 입고를 확인합니다.\
> \
> \## 처리 흐름\
> 1 반품 요청 승인 후 수거 진행\
> 2 상품 수거 완료 (이 API 호출)\
> 3 상품 입고 확인 (status: 수거완료)\
> 4 반품 완료 및 환불 준비

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/return/collection":{"post":{"tags":["클레임"],"summary":"반품 수거 완료","description":"반품 상품의 수거를 완료하고 상품 입고를 확인합니다.\n\n## 처리 흐름\n1 반품 요청 승인 후 수거 진행\n2 상품 수거 완료 (이 API 호출)\n3 상품 입고 확인 (status: 수거완료)\n4 반품 완료 및 환불 준비","operationId":"completeReturnCollection","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 반품 반려

> 수거된 상품의 상태가 불량하여 반품을 반려합니다.\
> \
> \## 처리 흐름\
> 1 반품 요청 승인 후 수거 진행\
> 2 수거된 상품 확인\
> 3 상품 상태 불량으로 반품 반려 (이 API 호출)\
> 4 반품 거절 처리 완료

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RejectReturnCollectionFepRequest":{"required":["rejectReason"],"type":"object","properties":{"rejectReason":{"type":"string","description":"반품 반려 사유 (최대 300자, 초과 시 잘림)"},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}},"description":"반품 반려 요청"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/return/collection-rejection":{"post":{"tags":["클레임"],"summary":"반품 반려","description":"수거된 상품의 상태가 불량하여 반품을 반려합니다.\n\n## 처리 흐름\n1 반품 요청 승인 후 수거 진행\n2 수거된 상품 확인\n3 상품 상태 불량으로 반품 반려 (이 API 호출)\n4 반품 거절 처리 완료","operationId":"rejectReturnCollection","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectReturnCollectionFepRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

## 반품 완료

> 반품 수거가 완료되어 환불 처리를 진행하고 반품 프로세스를 종료합니다.\
> \
> \## 처리 흐름\
> 1 반품 수거 완료\
> 2 상품 입고 확인\
> 3 반품 완료 처리 (이 API 호출)\
> 4 환불 처리 및 반품 프로세스 종료

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v3/shopping-fep/claims/{claimId}/return/completion":{"post":{"tags":["클레임"],"summary":"반품 완료","description":"반품 수거가 완료되어 환불 처리를 진행하고 반품 프로세스를 종료합니다.\n\n## 처리 흐름\n1 반품 수거 완료\n2 상품 입고 확인\n3 반품 완료 처리 (이 API 호출)\n4 환불 처리 및 반품 프로세스 종료","operationId":"completeReturn","parameters":[{"name":"claimId","in":"path","description":"클레임 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["REQUEST_FAILED","UNKNOWN","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"type":"object","description":"성공시 제공, 별도 내용이 없습니다. {}으로 반환"}}}}}}}}}}}
```

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

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