coupang
API 文档
商品 API品类 API品牌 API运输 / 订单 API退货 API换货 API促销 / 优惠券物流信息客服 / 咨询结算CGF / CGF liteRocket Growth
GET/v2/providers/openapi/apis/api/v6/vendors/{vendorId}/returnRequests2609170000

退货/取消申请列表查询

# 01

简介

退货/取消申请列表查询

# 02

详细内容

API支持的买家用户地区：韩国、台湾

您可根据受理日期查询退货/取消申请记录。

发送商品前，请务必通过【退货申请列表查询】确认是否有商品受理了“申请停止发货”。

您可根据searchType=timeframe 设置以分钟/天为单位进行查询。

查询在已付款阶段被取消的订单时，除orderId参数外，还须使用cancelType=CANCEL参数。

请下载以下资料，确认各退货订单的退货原因(reasonCode)。

下载 换货/退货/取消原因代码

您可将查询周期设置为最长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/vendorid/returnRequests?createdAtFrom=2025-07-24&createdAtTo=2025-07-28&cancelType=CANCEL
# 03

Path 参数

NameTypeDescription
vendorId*object
卖家ID

酷澎提供给卖家的固有代码

ex) A00012345
# 04

Query 参数

NameTypeDescription
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”
statusstring
退货状态
代码 描述
RU 申请停止发货
UC 受理退货申请
CC 已退货
PR 申请酷澎介入
“cancelType=CANCEL”时，该参数不可用。
cancelTypestring
nextTokenstring
查询下一页所需的token值

查询第一页时不需要

“searchType=timeFrame”，该参数不可用。
maxPerPagenumber
每页最多可申请查询的值

默认值 = 50

“searchType=timeFrame”时，该参数不可用。

”cancelType=CANCEL“时，输出的结果可能少于申请的maxPerPage。
orderIdnumber
订单号

除status外，查询时参数中还须包含orderId。

“searchType=timeFrame”时，该参数不可用。
# 05

响应体

响应消息

NameTypeDescription
codenumber
Http request status code

Example: 200, 400, 500
messagestring
成功或失败时显示的结果信息
dataobject[]
receiptId
data[].receiptId
number
取消(退货)申请编号
orderId
data[].orderId
number
订单号
paymentId
data[].paymentId
number
付款编号
receiptType
data[].receiptType
string
取消类型
RETURN or CANCEL
receiptStatus
data[].receiptStatus
string
取消(退货)状态
code description
RELEASE_STOP_UNCHECKED 申请停止发货
RETURNS_UNCHECKED 受理退货申请
VENDOR_WAREHOUSE_CONFIRM 已入库
REQUEST_COUPANG_CHECK 申请酷澎介入
RETURNS_COMPLETED 已退货
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

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代码消息
400HTTP_400Bad Request

错误说明

HTTP类型错误消息解决方案
400400 (确认请求参数)

Invalid vendor ID

请确认您输入的卖家ID(vendorId)是否正确。

400400 (确认请求参数)

OrderId can't be null , if doesn't pass the parameter status

请确认是否输入了订单号(orderId)。未输入退货状态(status)数值时，订单号(orderId)为必填项。

400400 (确认请求参数)

搜索时间段不得大于31天。

请确认您输入的搜索时间段是否小于31天。

400400 (确认请求参数)

搜索结束日期早于搜索开始日期。SearchPeriod=-**

请确认您设置开始日期(createdAtFrom)和结束日期(createdAtTo)时是否输入了相反数值。

412412 (服务器错误)

Read timed out

请缩短搜索时间段后再试。点击相关FAQ!