coupang
API Documentation
ProductsCategoriesBrandsShipments & OrdersReturnsExchangesPromotions & CouponsLogistics InfoCustomer ServiceSettlementCGF / CGF liteRocket Growth
GET/v2/providers/openapi/apis/api/v6/vendors/{vendorId}/returnRequestsv1

Return / Cancellation Request List Query

# 01

Summary

Available buyer market: Korean, Taiwan You can look up the history of return / cancellation requests based on the date of their submission .

# 02

Details

Available buyer market: Korean, Taiwan

You can look up the history of return / cancellation requests based on the date of their submission.
Before you send your product out, make sure to check [Return Request List Query] and see that you do not have any 'request to suspend shipment' for your products. 
You can look up the list by minute or by day based on your searchType=timeframesettings.
 
To look up the orders that were cancelled in the Payment Completed stage, you need to exclude status and orderId, and use cancelType=CANCEL as the parameter. 
 
To see the reasons for returns (reasonCode), download the following:
[Download] Exchange/Return/Cancellation Reason Code

You can set the time range of your query for up to 31 days, but when there is a lot of data, it could result in timeout error. We recommend that you limit the time range as much as possible. When a Customer requests to suspend the shipment (where the request for return is received in 'Product in Preparation' status), the status will display RU (Request to Suspend Shipment) and UC (Return Request Received) in your query.

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
Seller ID
Unique code issued to a seller by Coupang
Ex) A00012345 

Query String Parameter

Name Required Type Description
searchType O  String
To look up the list of return request by minute, send the "searchType=timeFrame" parameter.
createdAtFrom O  String
Search start date (yyyy-MM-dd)
If 'searchType=timeFrame': Enter as 'yyyy-MM-ddTHH:mm'
createdAtTo O  String
Search end date (yyyy-MM-dd)
If 'searchType=timeFrame': Enter as 'yyyy-MM-ddTHH:mm'
status   String 
Return status
code description
RU Request to suspend shipment
UC Return request received
CC Return completed
PR Coupang Verification Request
The parameter is not supported if 'cancelType=CANCEL'.
cancelType   String
code description
RETURN Returned order query (default)
CANCEL Cancelled order query
The default value is RETURN. To look up a cancelled order, remove the status parameter. 
nextToken   String
The token for the next page query;
You do not need this for your first page query.
The parameter is not supported if 'searchType=timeFrame'.
maxPerPage   Number
Maximum query request per page;
default = 50
The parameter is not supported if 'searchType=timeFrame'.
If 'cancelType=CANCEL', you may have fewer results than the maxPerPage request.
orderId   Number
Order number;
When you exclude the status parameter from your query, orderId should be included in the parameter.
The parameter is not supported if 'searchType=timeFrame'. 

Request Example

not require body
 

Response Message

Name Type Description
code Number
Http request status code
Example: 200, 400, 500
message String
You see the result message at success / failure
data Array
 
  receiptId Number
Cancellation (return) registration number
  orderId Number
Order number
  paymentId Number
Payment number
  receiptType String
Cancellation type;
RETURN or CANCEL 
  receiptStatus String
Cancellation (return) status
code description
RELEASE_STOP_UNCHECKED Request to suspend shipment
RETURNS_UNCHECKED Return request received
VENDOR_WAREHOUSE_CONFIRM Received at the FC/by the seller
REQUEST_COUPANG_CHECK Coupang Verification Request
RETURNS_COMPLETED Return completed
  createdAt String
Time of cancellation (return) request received
yyyy-MM-ddThh:mm:ss
  modifiedAt String
Last time of cancellation (return) status changed
yyyy-MM-ddThh:mm:ss
  requesterName String
Name of the person who requested a return
  requesterPhoneNumber String
Phone number of the person who requested a return (safe number)
  requesterRealPhoneNumber String
Actual phone number of the person who requested a return
null
  requesterAddress String
Return pick-up address
  requesterAddressDetail String
Detailed return pick-up address
  requesterZipCode String
Postal code for return pick-up address
  cancelReasonCategory1 String
Reason for return, Category 1
  cancelReasonCategory2 String
Reason for return, Category 2
  cancelReason String
Detailed reason for cancellation
  cancelCountSum Number
Total quantity cancelled
  returnDeliveryId Number
Return delivery number
  returnDeliveryType String
Type of pick-up
  • Dedicated courier
  • Integrated courier
  • Manual management
"" is displayed when the Customer has directly shipped the return product or when there is no product to pick up.
  releaseStopStatus String
Shipment suspended status
  • Unprocessed
  • Processed (Already shipped)
  • Processed (Shipment suspended)
  • Auto-processed (Already shipped)
  • Not applicable
  enclosePrice Object
Shipping fee, enclosed
    currencyCode String Three-letter uppercase string (format follows ISO-4217)
    units Number 64-bit integer representing the integer part of the monetary value
    nanos Number 32-bit integer representing the decimal part of the monetary value, in the range of [-999999999, 999999999]
  faultByType String
Type of fault
  Value
Coupang's COUPANG
Partner's (seller's) VENDOR
Customer's CUSTOMER
Logistics WMS
General GENERAL
  preRefund Boolean
Quick refund or not
  completeConfirmType String
Type of confirmation
  Value
Confirm partner VENDOR_CONFIRM
Unconfirmed UNDEFINED
Confirmed by CS CS_CONFIRM
Loss confirmed by CS CS_LOSS_CONFIRM
  • Uncompleted items are displayed as UNDEFIND.
  • Discretionary cancellation orders are displayed as CS_CONFIRM.
  completeConfirmDate String
Time of confirmation completed
yyyy-MM-ddTHH:mm:ss
  returnItems Array
Return item list
    vendorItemPackageId Number
Deal number
    vendorItemPackageName String
Deal name
    vendorItemId Number
Option ID
*Return requests are submitted by "vendorItemId". The option ID must be confirmed for return requests.
    vendorItemName String
Option name
    cancelCount Number
Cancelled quantity
*Partial return is allowed. Make sure to check the cancelled (return) quantity.
    purchaseCount Number
Order quantity
    shipmentBoxId Number
Original shipping number
    sellerProductId Number
Seller's listed product number
    sellerProductName String
Seller's listed product name
    releaseStatus String
Product shipment status
Code Status
Y Shipped
N Not shipped
S Shipment suspended
A Already shipped
    cancelCompleteUser String
Person who handles order cancellation
(3P_CANCEL: Cancelled in "Product in Preparation" status)
  returnDeliveryDtos Array
Pick-up waybill information;
There could be multiple counts of pick-up waybill information for each receiptId.
    deliveryCompanyCode String
Pick-up courier code
    deliveryInvoiceNo String
Pick-up waybill number;
Disregard if the pick-up waybill number is "" or null.
  reasonCode String
Reason for return code;
Go to the top of the page to download and confirm the VOC reason code.
  reasonCodeText String
Explanation for the reason codes
  returnShippingCharge Object
Estimated shipping fee for return
Type Shipping Fee Paid by
Positive number (+) Seller
Negative number (-) Customer
    currencyCode String Three-letter uppercase string (format follows ISO-4217)
    units Number 64-bit integer representing the integer part of the monetary value
    nanos Number 32-bit integer representing the decimal part of the monetary value, in the range of [-999999999, 999999999]
  nextToken String
Token value required for the next call;
The parameter is not supported if '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 Status Code (Error Type) Error Message Solution
400 (Check Request Parameter) Invalid vendor ID Make sure that the seller  ID (vendorId) is correct.
400 (Check Request Parameter) OrderId can't be null , if doesn't pass the parameter status Make sure that the order number (orderId) has been entered. When there is no return status input, order number (orderId) is required.
400 (Check Request Parameter) Up to 31 days in query time range Make sure that the time range is less than 31 days.
400 (Check Request Parameter) The end date of the query period is earlier than the start date. SearchPeriod=-** Make sure that the start date (createdAtFrom) and the end date (createdAtTo) in the time range have not been switched.
412 (Server Error) Read timed out Reduce the time range, and call back after some time. Relevant FAQ. Click!

URL API Name

GET_RETURN_REQUEST_BY_QUERY