GET
/v2/providers/openapi/apis/api/v6/vendors/{vendorId}/returnRequests2609170000반품 / 취소 요청 목록 조회
KRTW
# 01
요약
반품 / 취소 요청 목록 조회
# 02
상세
API 적용 가능한 구매자 사용자 지역: 한국, 대만
접수 일자를 기준으로 반품 / 취소 접수 내역을 조회할 수 있습니다.
상품 발송 전, [반품 요청 목록 조회]를 통해 '출고중지요청'이 들어온 상품은 없는지 반드시 확인해 주시기 바랍니다.
searchType=timeframe 설정에 따라 분단위 또는 일단위로 목록을 조회할 수 있습니다.
결제완료 단계에서 취소된 주문 조회를 위해서는 status, orderId 파라메터를 제외하고 cancelType=CANCEL 파라메터를 사용해야 합니다
각 반품 건에 대한 접수사유(reasonCode)는 아래 자료를 다운받아 확인해주세요.
Download 교환/반품/취소 사유 코드
최대 31일 까지 조회기간 설정이 가능하나, 데이터가 많을 경우 조회 시 타임아웃 에러가 발생할 수 있어 되도록 짧은 기간 설정을 권장합니다.
고객이 출고중지요청 시(상품준비중 단계에서 반품을 접수할 경우) RU(출고중지요청) 와 UC(반품접수) 상태에서 조회됩니다.
경로
GET/v2/providers/openapi/apis/api/v6/vendors/{vendorId}/returnRequests
예시 엔드포인트
https://api-gateway.coupang.com/v2/providers/openapi/apis/api/v6/vendors/A00012345/returnRequests?searchType=timeFrame&createdAtFrom=2017-08-27T11:00&createdAtTo=2017-09-03T11:00&status=UCURL API Name
GET_RETURN_REQUEST_BY_QUERY
# 03
Path 파라미터
| Name | Type | Description |
|---|---|---|
| vendorId* | string | 판매자 ID 쿠팡에서 업체에게 발급한 고유 코드 예) A00012345 |
# 04
Query 파라미터
| Name | Type | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| searchType* | string | 반품요청 목록 조회를 분단위로 조회 시에는 "searchType=timeFrame"파라메터를 전송하여야 합니다.
| ||||||||||
| createdAtFrom* | string | 검색 시작일 (yyyy-MM-dd) searchType=timeFrame 일 경우: yyyy-MM-ddTHH:mm 형식으로 입력 | ||||||||||
| createdAtTo* | string | 검색 종료일 (yyyy-MM-dd) searchType=timeFrame 일 경우: yyyy-MM-ddTHH:mm 형식으로 입력 | ||||||||||
| status | string | 반품상태
| ||||||||||
| cancelType | string |
| ||||||||||
| nextToken | string | 다음 페이지 조회를 위한 token값 첫번째 페이지 조회 시에는 필요하지 않습니다. searchType=timeFrame일 경우 지원하지 않는 파라메터입니다. | ||||||||||
| maxPerPage | number | 페이지당 최대 조회 요청 값 default = 50 searchType=timeFrame일 경우 지원하지 않는 파라메터입니다. cancelType=CANCEL일 경우 요청한 maxPerPage보다 적은 수의 결과가 출력될 수 있습니다. | ||||||||||
| orderId | number | 주문번호 status 파라메터를 제외하고 조회할 경우에는 orderId가 파라메터에 포함되어야 합니다. searchType=timeFrame일 경우 지원하지 않는 파라메터입니다. |
# 05
응답 본문
응답 메시지
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| code | number | Http request status code Example: 200, 400, 500 | ||||||||||||
| message | string | 성공 혹은 실패시 해당 결과메시지가 나타남
| ||||||||||||
| data | object[] | |||||||||||||
| receiptId data[].receiptId | number | 취소(반품)접수번호
| ||||||||||||
| orderId data[].orderId | number | 주문번호
| ||||||||||||
| paymentId data[].paymentId | number | 결제번호
| ||||||||||||
| receiptType data[].receiptType | string | 취소유형 RETURN or CANCEL | ||||||||||||
| receiptStatus data[].receiptStatus | string | 취소(반품)진행 상태
| ||||||||||||
| createdAt data[].createdAt | string | 취소(반품) 접수시간 yyyy-MM-ddThh:mm:ss | ||||||||||||
| modifiedAt data[].modifiedAt | string | 취소(반품) 상태 최종 변경시간 yyyy-MM-ddThh:mm:ss | ||||||||||||
| requesterName data[].requesterName | string | 반품 신청인 이름
| ||||||||||||
| requesterPhoneNumber data[].requesterPhoneNumber | string | 반품 신청인 전화번호(안심번호)
| ||||||||||||
| requesterRealPhoneNumber data[].requesterRealPhoneNumber | string | 반품 신청인 실전화번호 null | ||||||||||||
| requesterAddress data[].requesterAddress | string | 반품 회수지 주소
| ||||||||||||
| requesterAddressDetail data[].requesterAddressDetail | string | 반품 회수지 상세주소
| ||||||||||||
| requesterZipCode data[].requesterZipCode | string | 반품 회수지 우편번호
| ||||||||||||
| cancelReasonCategory1 data[].cancelReasonCategory1 | string | 반품 사유 카테고리 1
| ||||||||||||
| cancelReasonCategory2 data[].cancelReasonCategory2 | string | 반품 사유 카테고리 2
| ||||||||||||
| cancelReason data[].cancelReason | string | 취소사유 상세내역
| ||||||||||||
| cancelCountSum data[].cancelCountSum | number | 총 취소수량
| ||||||||||||
| returnDeliveryId data[].returnDeliveryId | number | 반품배송번호
| ||||||||||||
| returnDeliveryType data[].returnDeliveryType | string | 회수종류
| ||||||||||||
| releaseStopStatus data[].releaseStopStatus | string | 출고중지처리상태
| ||||||||||||
| enclosePrice data[].enclosePrice | object | 동봉배송비
| ||||||||||||
| currencyCode data[].enclosePrice.currencyCode | string | 통화 코드(ISO-4217 표준을 준수), 3자리 대문자
| ||||||||||||
| units data[].enclosePrice.units | number | 통화 정수 부분, 64비트
| ||||||||||||
| nanos data[].enclosePrice.nanos | number | 통화 소수 부분, 32비트, 값 범위 [-999999999, 999999999]
| ||||||||||||
| faultByType data[].faultByType | string | 귀책타입
| ||||||||||||
| preRefund data[].preRefund | boolean | 선환불 여부
| ||||||||||||
| completeConfirmType data[].completeConfirmType | string | 완료 확인 종류
| ||||||||||||
| completeConfirmDate data[].completeConfirmDate | string | 완료 확인 시간 yyyy-MM-ddTHH:mm:ss | ||||||||||||
| returnItems data[].returnItems | object[] | 반품 아이템 목록
| ||||||||||||
| vendorItemPackageId data[].returnItems[].vendorItemPackageId | number | 딜번호
| ||||||||||||
| vendorItemPackageName data[].returnItems[].vendorItemPackageName | string | 딜명
| ||||||||||||
| vendorItemId data[].returnItems[].vendorItemId | number | 옵션아이디 *vendorItemId 단위로 반품이 접수됩니다. 반품 접수 시, 반드시 확인 필요한 옵션아이디 | ||||||||||||
| vendorItemName data[].returnItems[].vendorItemName | string | 옵션명
| ||||||||||||
| cancelCount data[].returnItems[].cancelCount | number | 취소 수량 *부분 반품이 가능하므로, 취소(반품) 수량을 반드시 확인해주세요. | ||||||||||||
| purchaseCount data[].returnItems[].purchaseCount | number | 주문 수량
| ||||||||||||
| shipmentBoxId data[].returnItems[].shipmentBoxId | number | 원 배송번호
| ||||||||||||
| sellerProductId data[].returnItems[].sellerProductId | number | 업체등록상품번호
| ||||||||||||
| sellerProductName data[].returnItems[].sellerProductName | string | 업체등록상품명
| ||||||||||||
| releaseStatus data[].returnItems[].releaseStatus | string | 상품출고여부
| ||||||||||||
| cancelCompleteUser data[].returnItems[].cancelCompleteUser | string | 주문취소처리 담당자 (3P_CANCEL: 상품준비중 단계에서 취소된 경우) | ||||||||||||
| returnDeliveryDtos data[].returnDeliveryDtos | object[] | 회수 운송장 정보 receiptId 별로 복수의 회수 운송장정보가 발생할 수 있음 | ||||||||||||
| deliveryCompanyCode data[].returnDeliveryDtos[].deliveryCompanyCode | string | 회수 택배사코드
| ||||||||||||
| deliveryInvoiceNo data[].returnDeliveryDtos[].deliveryInvoiceNo | string | 회수 운송장번호 회수 운송장번호 값이 "" 또는 null일 경우 무시 | ||||||||||||
| reasonCode data[].reasonCode | string | 반품사유코드 해당 페이지 상단에서 VOC 사유코드를 다운받아 확인해주세요. | ||||||||||||
| reasonCodeText data[].reasonCodeText | string | 반품사유설명
| ||||||||||||
| returnShippingCharge data[].returnShippingCharge | object | 예상 반품배송비
| ||||||||||||
| currencyCode data[].returnShippingCharge.currencyCode | string | 통화 코드(ISO-4217 표준을 준수), 3자리 대문자
| ||||||||||||
| units data[].returnShippingCharge.units | number | 통화 정수 부분, 64비트
| ||||||||||||
| nanos data[].returnShippingCharge.nanos | number | 통화 소수 부분, 32비트, 값 범위 [-999999999, 999999999]
| ||||||||||||
| nextToken data[].nextToken | string | 다음 호출시 필요한 토큰 값 searchType=timeFrame일 경우 지원하지 않는 파라미터입니다. |
Response Example
{
"code": 200,
"message": "OK",
"data": [
{
"receiptId": 50229613,
"orderId": 28000008707838,
"paymentId": 28000009486604,
"receiptType": "RETURN",
"receiptStatus": "RETURNS_UNCHECKED",
"createdAt": "2025-01-15T14:17:13.973885-08:00",
"modifiedAt": "2025-01-15T14:17:13.973885-08:00",
"requesterName": "구*숙",
"requesterPhoneNumber": "+1(555)444-1234",
"requesterRealPhoneNumber": null,
"requesterAddress": "서울특별시 송파구 송파대로 570 (신천동)",
"requesterAddressDetail": "Tower 730",
"requesterZipCode": "05510",
"cancelReasonCategory1": "고객변심",
"cancelReasonCategory2": "단순변심(사유없음)",
"cancelReason": "",
"cancelCountSum": 1,
"returnDeliveryId": 20234047,
"returnDeliveryType": "연동택배",
"releaseStopStatus": "처리(이미출고)",
"enclosePrice": {
"currencyCode": "KRW",
"units": 0,
"nanos": 0
},
"faultByType": "CUSTOMER",
"preRefund": false,
"completeConfirmDate": "",
"completeConfirmType": "UNDEFINED",
"returnItems": [
{
"vendorItemPackageId": 0,
"vendorItemPackageName": "스파오(SPAO) (#)시원하고 편안한 캉캉 롱스커트",
"vendorItemId": 3187044096,
"vendorItemName": "스파오(SPAO) (#)시원하고 편안한 캉캉 롱스커트, (19)Black, S",
"purchaseCount": 1,
"cancelCount": 1,
"shipmentBoxId": 123456789012345678,
"sellerProductId": 57623797,
"sellerProductName": "스파오 (#)시원하고 편안한 캉캉 롱스커트,(19)Black S",
"releaseStatus": "S",
"cancelCompleteUser": "l******"
}
],
"returnDeliveryDtos": [
{
"deliveryCompanyCode": "CJGLS",
"deliveryInvoiceNo": "*******"
}
],
"reasonCode": "CHANGEMIND",
"reasonCodeText": "필요 없어짐 (단순 변심)",
"returnShippingCharge": {
"currencyCode": "KRW",
"units": -3000,
"nanos": 0
}
}
]
nextToken: ""
}# 06
에러 코드
| HTTP | 코드 | 메시지 |
|---|---|---|
| 400 | HTTP_400 | Bad Request |
오류 사양
| HTTP | 유형 | 오류 메시지 | 해결 방법 |
|---|---|---|---|
| 400 | 400 (요청변수확인) | Invalid vendor ID | 판매자 ID(vendorId) 값을 올바로 입력했는지 확인합니다. |
| 400 | 400 (요청변수확인) | OrderId can't be null , if doesn't pass the parameter status | 주문번호(orderId)를 입력했는지 확인합니다. 반품상태(status) 값 입력이 없을 경우 주문번호(orderId) 입력은 필수입니다. |
| 400 | 400 (요청변수확인) | 검색기간은 최대 31일입니다. | 조회기간을 31일 이내로 입력했는지 확인합니다. |
| 400 | 400 (요청변수확인) | 검색기간의 끝이 시작 보다 앞섭니다. SearchPeriod=-** | 조회시간 설정 시 시작일(createdAtFrom) 과 종료일(createdAtTo)의 값을 바꿔 입력했는지 확인합니다. |
| 412 | 412 (서버오류) | Read timed out | 조회기간을 줄여서 일정시간 이후 재호출합니다. 관련 FAQ 클릭! |