coupang
API 문서
상품 API카테고리 API브랜드 API배송 / 주문 API반품 API교환 API프로모션 / 쿠폰물류 정보고객 문의정산Rocket Growth
GET/v2/providers/openapi/apis/api/v6/vendors/{vendorId}/returnRequestsv1

반품 / 취소 요청 목록 조회

# 01

요약

API 적용 가능한 구매자 사용자 지역 : 한국 , 대만 접수 일자를 기준 으로 반품 / 취소 접수 내역을 조회할 수 있습니다. 상품 발송 전, [반품 요청 목록 조회]를 통해 '출고중지요청'이 들어온 상품은 없는지 반드시 확인해 주시기 바랍니다. searchType=timeframe 설정에 따라 분단위 또는 일단위로 목록을 조회할 수 있습니다.

# 02

상세

API 적용 가능한 구매자 사용자 지역: 한국, 대만

접수 일자를 기준으로 반품 / 취소 접수 내역을 조회할 수 있습니다.
상품 발송 전, [반품 요청 목록 조회]를 통해 '출고중지요청'이 들어온 상품은 없는지 반드시 확인해 주시기 바랍니다. 
searchType=timeframe 설정에 따라 분단위 또는 일단위로 목록을 조회할 수 있습니다.
 
결제완료 단계에서 취소된 주문 조회를 위해서는 status, orderId 파라메터를 제외하고 cancelType=CANCEL 파라메터를 사용해야 합니다 
 
각 반품 건에 대한 접수사유(reasonCode)는 아래 자료를 다운받아 확인해주세요.
[Download] 교환/반품/취소  사유 코드

최대 31일 까지 조회기간 설정이 가능하나, 데이터가 많을 경우 조회 시 타임아웃 에러가 발생할 수 있어 되도록 짧은 기간 설정을 권장합니다.  
고객이 출고중지요청 시(상품준비중 단계에서 반품을 접수할 경우) RU(출고중지요청) 와 UC(반품접수) 상태에서 조회됩니다.

Path

GET

/v2/providers/openapi/apis/api/v6/vendors/{vendorId}/returnRequests

Example Endpoint

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=UC

Request Parameters

Path Segment Parameter

Name Required Type Description
vendorId O  String
판매자 ID
쿠팡에서 업체에게 발급한 고유 코드
예) A00012345 

Query String Parameter

Name Required Type Description
searchType O  String
반품요청 목록 조회를 분단위로 조회 시에는 "searchType=timeFrame"파라메터를 전송하여야 합니다.
createdAtFrom O  String
검색 시작일 (yyyy-MM-dd)
searchType=timeFrame 일 경우: yyyy-MM-ddTHH:mm 형식으로 입력
createdAtTo O  String
검색 종료일 (yyyy-MM-dd)
searchType=timeFrame 일 경우: yyyy-MM-ddTHH:mm 형식으로 입력
status   String 
반품상태
code description
RU 출고중지요청
UC 반품접수
CC 반품완료
PR 쿠팡확인요청
cancelType=CANCEL일 경우 지원하지 않는 파라메터입니다.
cancelType   String
code description
RETURN 반품주문조회 (default)
CANCEL 취소주문조회
default 값은 RETURN 이며, 취소주문을 조회할 경우에는 status 파라메터를 제거해야 합니다. 
nextToken   String
다음 페이지 조회를 위한 token값
첫번째 페이지 조회 시에는 필요하지 않습니다.
searchType=timeFrame일 경우 지원하지 않는 파라메터입니다.
maxPerPage   Number
페이지당 최대 조회 요청 값
default = 50
searchType=timeFrame일 경우 지원하지 않는 파라메터입니다.
cancelType=CANCEL일 경우 요청한 maxPerPage보다 적은 수의 결과가 출력될 수 있습니다.
orderId   Number
주문번호
status 파라메터를 제외하고 조회할 경우에는 orderId가 파라메터에 포함되어야 합니다.
searchType=timeFrame일 경우 지원하지 않는 파라메터입니다. 

Request Example

not require body
 

Response Message

Name Type Description
code Number
Http request status code
Example: 200, 400, 500
message String
성공 혹은 실패시 해당 결과메시지가 나타남
data Array
 
  receiptId Number
취소(반품)접수번호
  orderId Number
주문번호
  paymentId Number
결제번호
  receiptType String
취소유형
RETURN or CANCEL 
  receiptStatus String
취소(반품)진행 상태
code description
RELEASE_STOP_UNCHECKED 출고중지요청
RETURNS_UNCHECKED 반품접수
VENDOR_WAREHOUSE_CONFIRM 입고완료
REQUEST_COUPANG_CHECK 쿠팡확인요청
RETURNS_COMPLETED 반품완료
  createdAt String
취소(반품) 접수시간
yyyy-MM-ddThh:mm:ss
  modifiedAt String
취소(반품) 상태 최종 변경시간
yyyy-MM-ddThh:mm:ss
  requesterName String
반품 신청인 이름
  requesterPhoneNumber String
반품 신청인 전화번호(안심번호)
  requesterRealPhoneNumber String
반품 신청인 실전화번호
null
  requesterAddress String
반품 회수지 주소
  requesterAddressDetail String
반품 회수지 상세주소
  requesterZipCode String
반품 회수지 우편번호
  cancelReasonCategory1 String
반품 사유 카테고리 1
  cancelReasonCategory2 String
반품 사유 카테고리 2
  cancelReason String
취소사유 상세내역
  cancelCountSum Number
총 취소수량
  returnDeliveryId Number
반품배송번호
  returnDeliveryType String
회수종류
  • 전담택배
  • 연동택배
  • 수기관리
고객이 직접 반품상품을 발송했거나 회수할 상품이 없을 때 ""로 표시됩니다.
  releaseStopStatus String
출고중지처리상태
  • 미처리
  • 처리(이미출고)
  • 처리(출고중지)
  • 자동처리(이미출고)
  • 비대상
  enclosePrice Object
동봉배송비
    currencyCode String 통화 코드(ISO-4217 표준을 준수), 3자리 대문자
    units Number 통화 정수 부분, 64비트
    nanos Number 통화 소수 부분, 32비트, 값 범위 [-999999999, 999999999]
  faultByType String
귀책타입
  Value
Coupang 과실 COUPANG
협력사(셀러) 과실 VENDOR
고객 과실 CUSTOMER
물류 과실 WMS
일반 GENERAL
  preRefund Boolean
선환불 여부
  completeConfirmType String
완료 확인 종류
  Value
파트너 확인 VENDOR_CONFIRM
미확인 UNDEFINED
CS 대리확인 CS_CONFIRM
CS 손실확인 CS_LOSS_CONFIRM
  • 완료되지 않은 건들은 UNDEFIND 로 표시됩니다.
  • 직권취소처리된 주문들은 CS_CONFIRM 으로 표시됩니다
  completeConfirmDate String
완료 확인 시간
yyyy-MM-ddTHH:mm:ss
  returnItems Array
반품 아이템 목록
    vendorItemPackageId Number
딜번호
    vendorItemPackageName String
딜명
    vendorItemId Number
옵션아이디
*vendorItemId 단위로 반품이 접수됩니다. 반품 접수 시, 반드시 확인 필요한 옵션아이디
    vendorItemName String
옵션명
    cancelCount Number
취소 수량
*부분 반품이 가능하므로, 취소(반품) 수량을 반드시 확인해주세요.
    purchaseCount Number
주문 수량
    shipmentBoxId Number
원 배송번호
    sellerProductId Number
업체등록상품번호
    sellerProductName String
업체등록상품명
    releaseStatus String
상품출고여부
코드 상태
Y 출고됨
N 미출고
S 출고중지됨
A 이미출고됨
    cancelCompleteUser String
주문취소처리 담당자
(3P_CANCEL: 상품준비중 단계에서 취소된 경우)
  returnDeliveryDtos Array
회수 운송장 정보
receiptId 별로 복수의 회수 운송장정보가 발생할 수 있음
    deliveryCompanyCode String
회수 택배사코드
    deliveryInvoiceNo String
회수 운송장번호
회수 운송장번호 값이 "" 또는 null일 경우 무시
  reasonCode String
반품사유코드
해당 페이지 상단에서 VOC 사유코드를 다운받아 확인해주세요.
  reasonCodeText String
반품사유설명
  returnShippingCharge

Object
예상 반품배송비
형식 배송비 부과
양수(+) 셀러 부담
음수(-) 고객 부담
    currencyCode String 통화 코드(ISO-4217 표준을 준수), 3자리 대문자
    units Number 통화 정수 부분, 64비트
    nanos Number 통화 소수 부분, 32비트, 값 범위 [-999999999, 999999999]
  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: ""
}

Error Spec

HTTP 상태 코드(오류 유형) 오류 메시지 해결 방법
400 (요청변수확인) Invalid vendor ID 판매자 ID(vendorId) 값을 올바로 입력했는지 확인합니다.
400 (요청변수확인) OrderId can't be null , if doesn't pass the parameter status 주문번호(orderId)를 입력했는지 확인합니다. 반품상태(status) 값 입력이 없을 경우 주문번호(orderId) 입력은 필수입니다.
400 (요청변수확인) 검색기간은 최대 31일입니다. 조회기간을 31일 이내로 입력했는지 확인합니다.
400 (요청변수확인) 검색기간의 끝이 시작 보다 앞섭니다. SearchPeriod=-** 조회시간 설정 시 시작일(createdAtFrom) 과 종료일(createdAtTo)의 값을 바꿔 입력했는지 확인합니다.
412 (서버오류) Read timed out 조회기간을 줄여서 일정시간 이후 재호출합니다. 관련 FAQ 클릭!

URL API Name

GET_RETURN_REQUEST_BY_QUERY