Return / Cancellation Request List Query

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

String

To look up the list of return request by minute, send the "searchType=timeFrame" parameter.

createdAtFrom

String

Search start date (yyyy-MM-dd)

If 'searchType=timeFrame': Enter as 'yyyy-MM-ddTHH:mm'

createdAtTo

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

OPENAPI 관련 안내

Articles in this section

Path

Example Endpoint

Request Parameters

Path Segment Parameter

Query String Parameter

Request Example

Response Message

Response Example

Error Spec

URL API Name

OPENAPI 관련 안내

Articles in this section

Path

Example Endpoint

Request Parameters

Path Segment Parameter

Query String Parameter

Request Example

Response Message

Response Example

Error Spec

URL API Name

Related articles