Products Categories Brands Shipments & Orders Returns Exchanges Promotions & Coupons Logistics Info Customer Service Settlement CGF / CGF lite Rocket Growth

Returns

GET/v2/providers/openapi/apis/api/v6/vendors/{vendorId}/returnRequests2609170000

Return / Cancellation Request List Query

# 01

Summary

# 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

URL API Name

GET_RETURN_REQUEST_BY_QUERY

# 03

Path parameters

Name	Type	Description
vendorId*	string	Seller ID Unique code issued to a seller by Coupang Ex) A00012345

# 04

Query parameters

Name

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'.

# 05

Response 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

object[]

receiptId

data[].receiptId

number

Cancellation (return) registration number

orderId

data[].orderId

number

Order number

paymentId

data[].paymentId

number

Payment number

receiptType

data[].receiptType

string

Cancellation type;

RETURN or CANCEL

receiptStatus

data[].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

data[].createdAt

string

Time of cancellation (return) request received
yyyy-MM-ddThh:mm:ss

modifiedAt

data[].modifiedAt

string

Last time of cancellation (return) status changed
yyyy-MM-ddThh:mm:ss

requesterName

data[].requesterName

string

Name of the person who requested a return

requesterPhoneNumber

data[].requesterPhoneNumber

string

Phone number of the person who requested a return (safe number)

requesterRealPhoneNumber

data[].requesterRealPhoneNumber

string

Actual phone number of the person who requested a return
null

requesterAddress

data[].requesterAddress

string

Return pick-up address

requesterAddressDetail

data[].requesterAddressDetail

string

Detailed return pick-up address

requesterZipCode

data[].requesterZipCode

string

Postal code for return pick-up address

cancelReasonCategory1

data[].cancelReasonCategory1

string

Reason for return, Category 1

cancelReasonCategory2

data[].cancelReasonCategory2

string

Reason for return, Category 2

cancelReason

data[].cancelReason

string

Detailed reason for cancellation

cancelCountSum

data[].cancelCountSum

number

Total quantity cancelled

returnDeliveryId

data[].returnDeliveryId

number

Return delivery number

returnDeliveryType

data[].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

data[].releaseStopStatus

string

Shipment suspended status

Unprocessed
Processed (Already shipped)
Processed (Shipment suspended)
Auto-processed (Already shipped)
Not applicable

enclosePrice

data[].enclosePrice

object

Shipping fee, enclosed

currencyCode

data[].enclosePrice.currencyCode

string

Three-letter uppercase string (format follows ISO-4217)

units

data[].enclosePrice.units

number

64-bit integer representing the integer part of the monetary value

nanos

data[].enclosePrice.nanos

number

32-bit integer representing the decimal part of the monetary value, in the range of [-999999999, 999999999]

faultByType

data[].faultByType

string

Type of fault

	Value
Coupang's	COUPANG
Partner's (seller's)	VENDOR
Customer's	CUSTOMER
Logistics	WMS
General	GENERAL

preRefund

data[].preRefund

boolean

Quick refund or not

completeConfirmType

data[].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

data[].completeConfirmDate

string

Time of confirmation completed
yyyy-MM-ddTHH:mm:ss

returnItems

data[].returnItems

object[]

Return item list

vendorItemPackageId

data[].returnItems[].vendorItemPackageId

number

Deal number

vendorItemPackageName

data[].returnItems[].vendorItemPackageName

string

Deal name

vendorItemId

data[].returnItems[].vendorItemId

number

Option ID

*Return requests are submitted by "vendorItemId". The option ID must be confirmed for return requests.

vendorItemName

data[].returnItems[].vendorItemName

string

Option name

cancelCount

data[].returnItems[].cancelCount

number

Cancelled quantity

*Partial return is allowed. Make sure to check the cancelled (return) quantity.

purchaseCount

data[].returnItems[].purchaseCount

number

Order quantity

shipmentBoxId

data[].returnItems[].shipmentBoxId

number

Original shipping number

sellerProductId

data[].returnItems[].sellerProductId

number

Seller's listed product number

sellerProductName

data[].returnItems[].sellerProductName

string

Seller's listed product name

releaseStatus

data[].returnItems[].releaseStatus

string

Product shipment status

Code	Status
Y	Shipped
N	Not shipped
S	Shipment suspended
A	Already shipped

cancelCompleteUser

data[].returnItems[].cancelCompleteUser

string

Person who handles order cancellation
(3P_CANCEL: Cancelled in "Product in Preparation" status)

returnDeliveryDtos

data[].returnDeliveryDtos

object[]

Pick-up waybill information;
There could be multiple counts of pick-up waybill information for each receiptId.

deliveryCompanyCode

data[].returnDeliveryDtos[].deliveryCompanyCode

string

Pick-up courier code

deliveryInvoiceNo

data[].returnDeliveryDtos[].deliveryInvoiceNo

string

Pick-up waybill number;
Disregard if the pick-up waybill number is "" or null.

reasonCode

data[].reasonCode

string

Reason for return code;
Go to the top of the page to download and confirm the VOC reason code.

reasonCodeText

data[].reasonCodeText

string

Explanation for the reason codes

returnShippingCharge

data[].returnShippingCharge

object

Estimated shipping fee for return

Type	Shipping Fee Paid by
Positive number (+)	Seller
Negative number (-)	Customer

currencyCode

data[].returnShippingCharge.currencyCode

string

Three-letter uppercase string (format follows ISO-4217)

units

data[].returnShippingCharge.units

number

64-bit integer representing the integer part of the monetary value

nanos

data[].returnShippingCharge.nanos

number

32-bit integer representing the decimal part of the monetary value, in the range of [-999999999, 999999999]

nextToken

data[].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: ""
}

# 06

Error codes

HTTP	Code	Message
400	HTTP_400	Bad Request

Error specification

HTTP	Type	Error message	Solution
400	400 (Check Request Parameter)	Invalid vendor ID	Make sure that the seller ID (vendorId) is correct.
400	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	400 (Check Request Parameter)	Up to 31 days in query time range	Make sure that the time range is less than 31 days.
400	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	412 (Server Error)	Read timed out	Reduce the time range, and call back after some time. Relevant FAQ. Click!