Shein Return Order
Version | Date | Created / Updated | Notes |
---|---|---|---|
v1.0 | Hristiyan | First publish |
The order returns in Shein will be handled with Hemi Claim functionality. The purpose of this page is to give good understanding on how this will work.
Basically we don’t have the option to accept/decline returns in Shein but rather all returns should be stored as “Accepted” by default.
Standard work flow on Shein requires us to make 3 operations to process the return. These are:
-
Get all returns (provided with very little information)
-
Get the detail for each return with a separate call to ensure we have all the info for each return request
-
When the return is received in the warehouse fire the 3rd operation that will actually make the refund on the marketplace
The first call is a query to return order list.
Query return order list
API Call: POST /open-api/return-order/list
API Docs: https://open.sheincorp.com/documents/apidoc/detail/3000247-2000004
We need to send a content-type
: application/json
as a header.
The first run of the cron should download order refunds from the last 7 days. We want to incorporate the last_date_run
table . Once we have a record in last_date_run
table we want to pick that date and overlap it with 2 hours.
The specific case here is that we must specify startTime
and endTime
but they should be no more than 48hours so if we would like to get all returns from the last 7days we have to make 4 requests each covering 48 hours period for example the first run of the cron will have startTime
: 2024-05-10 00:00:00
endTime
: 2024-05-12 23:59:59
and then the next one startTime
: 2024-05-13 00:00:00
endTime
: 2024-05-15 23:59:59
etc.
Example request :
{
"queryType": 1,
"startTime": "2024-05-23 00:00:00",
"endTime": "2024-05-24 23:59:40",
"page": 1,
"pageSize": 10,
"returnOrderStatus": 5
}
Request mapping :
Shein Field | Hemi Field | Required | Notes |
---|---|---|---|
queryType |
Yes | Hardcoded as “1” | |
startTime |
Yes | last_date_run - 2 hours (please see explanation below) |
|
Format should be yyyy-MM-dd HH:mm:ss | |||
endTime |
Yes | We need to send the current time so NOW() | |
Format should be yyyy-MM-dd HH:mm:ss | |||
page |
Yes | Request page number. By default it should be 1. | |
pageSize |
Yes | This is the page size. It ranges from 1 to 30 and is up to devs to decide from tech point of view how many records we want to call per page. | |
returnOrderStatus |
N/A | No |
After a successful call we should receive a response with the return order list:
{
"code": "0",
"msg": "OK",
"info": {
"count": 1,
"returnOrderList": [
{
"returnOrderNo": "NGGQM0NLE1",
"returnOrderStatus": 5,
"addTime": "2024-05-23 10:49:36",
"requestReturnTime": "2024-05-23 10:49:23",
"updateTime": "2024-05-23 10:49:37"
}
]
},
"bbl": {}
}
From the response we only need the returnOrderNo
as this will be needed for our next call which will get the details about the returned order.
Query return order details
With this call we will get the order details to get an understanding which order is returned and which item(s).
API Call: POST /open-api/return-order/details
API Docs: https://open.sheincorp.com/documents/apidoc/detail/3000270-2000004
We need to send a content-type
: application/json
as a header.
Request body example :
{
"returnOrderNoList": ["NRMFM000MT"]
}
Request Mapping :
Shein Field | Notes | Requried |
---|---|---|
returnOrderNoList |
This is the returnOrderNo from the response on our previous call. Please have in mind the max count in the list is 30 so if we have received more than 30 orders in our previous call, we need to handle this and split into two or more calls. |
Yes |
Response example :
{
"code": "0",
"msg": "OK",
"info": [
{
"returnOrderNo": "NGGQM0NLE1",
"returnOrderStatus": 5,
"noReturnGoodsSign": 0,
"returnOrderTagCode": null,
"orderNo": "GSUNGG26Q00004H",
"site": "shein-us",
"shippingCode": "",
"platformExpressNo": "",
"memberExpressNo": "",
"expressCompanyName": null,
"refundOrderNos": [],
"refundWaybill": "",
"refundExpressCompanyName": "",
"performanceCost": 0.00,
"invoiceStatus": 1,
"requestReturnTime": "2024-05-23 10:49:23",
"allocateTime": "2024-05-23 10:49:36",
"lastUpdateTime": "2024-05-23 10:49:36",
"sellerSignedTime": "2023-07-26 17:25:12",
"cancelTime": "",
"completedTime": "",
"checkStatus": 2,
"stockMode": 2,
"receiveType": 2,
"returnGoodsInfoList": [
{
"goodsId": 2230236437987168500,
"sku": "I367l5rlmgza",
"skc": "sM22041150706078",
"goodsSn": "",
"currency": "USD",
"skuSn": "",
"commodityAttributeList": [
{
"attrValueId": "330,755,1000108",
"attrName": "金黄-XS-冬",
"language": "CN"
},
{
"attrValueId": "330,755,1000108",
"attrName": "Gold-XS-冬",
"language": "US"
},
{
"attrValueId": "330,755,1000108",
"attrName": "Ouro-XS-don77777",
"language": "PT"
},
{
"attrValueId": "330,755,1000108",
"attrName": "ทอง-XS-冬",
"language": "TH"
},
{
"attrValueId": "330,755,1000108",
"attrName": "Dorado-XS-冬",
"language": "ES"
},
{
"attrValueId": "330,755,1000108",
"attrName": "Oro-XS-冬",
"language": "IT"
}
],
"goodsTitle": "GoodsName111111111111",
"imageUrl": "//imgdeal-test01.shein.com/pi_img/2021/11/03/16359230894287290938_thumbnail_220x293.jpg",
"goodsStatus": 5,
"returnImageList": [
{
"type": 1,
"link": ""
}
],
"sellerCurrencyPrice": 26.46,
"sellerCurrencyStoreCouponPrice": 0.00,
"sellerCurrencyPromotionPrice": 0.00,
"estimateCommission": 2.77,
"sellerRealTax": 0.00,
"estimateIncomeMoney": 23.69,
"returnExpense": 0.00,
"performancePrice": 0.00,
"estimateTaxIncomeMoney": 23.69,
"returnReasonList": [
{
"language": "CN",
"reason": "19"
},
{
"language": "EN",
"reason": "????"
},
{
"language": "PT",
"reason": "9"
},
{
"language": "TH",
"reason": "7"
},
{
"language": "ES",
"reason": "14"
}
]
}
]
}
],
"bbl": {}
}
Response mapping :
Shein Field | Hemi Mapping | Notes | |||
---|---|---|---|---|---|
code |
|||||
msg |
|||||
info |
|||||
returnOrderNo |
Order Claim > Marketplace ID |
||||
returnOrderStatus |
Order Claim > Marketplace Status |
We need to do mapping as we will receive integer but we want to store the name of the status : |
1 - Closed;
2 - Applied;
3 - Canceled;
5 - Seller Received Goods;
6 - Delivered;
7 - Pending Handover;
8 - Pending SHEIN Transfer;
9 - Completed; |
| | noReturnGoodsSign
| | | Order Claim
> Type
| We will receive integers of 0 or 1.
0 means that this is a return 1 means that this is “no return” which we will treat as Cancellation. So we need to have a logic :
If we receive noReturnGoodsSign
= 0 we store Order Claim
> Type
= Return
If we receive noReturnGoodsSign
= 1 we store Order Claim
> Type
= Cancel |
| | returnOrderTagCode
| | | N/A | |
| | orderNo
| | | | This will be the Orders
> Marketplace Order ID
that we need to map so we can understand which order is the return for. |
| | site
| | | N/A | |
| | shippingCode
| | | N/A | |
| | platformExpressNo
| | | N/A | |
| | memberExpressNo
| | | N/A | |
| | expressCompanyName
| | | N/A | |
| | refundOrderNos
| | | N/A | |
| | refundWaybill
| | | N/A | |
| | refundExpressCompanyName
| | | N/A | |
| | performanceCost
| | | N/A | |
| | invoiceStatus
| | | N/A | |
| | requestReturnTime
| | | Order Claim
> Marketplace Date
| Will be in format yyyy-MM-dd HH:mm:ss we need to transform it to unix |
| | allocateTime
| | | N/A | |
| | lastUpdateTime
| | | N/A | |
| | sellerSignedTime
| | | N/A | |
| | cancelTime
| | | N/A | |
| | completedTime
| | | N/A | |
| | checkStatus
| | | N/A | |
| | stockMode
| | | N/A | |
| | receiveType
| | | N/A | |
| | returnGoodsInfoList
| | | | |
| | | goodsId
| | | This will be what we have stored in Order Item Line
> Marketplace Order Item ID
. We need to map by this as this will help us understand exactly which line is being returned and we need to create a record in Order Claim Rows
table for this product |
| | | sku
| | N/A | |
| | | skc
| | N/A | |
| | | goodsSn
| | N/A | |
| | | currency
| | N/A | |
| | | skuSn
| | N/A | |
| | | commodityAttributeList
| | N/A | |
| | | | attrValueId
| N/A | |
| | | | attrName
| N/A | |
| | | | language
| N/A | |
| | | goodsTitle
| | N/A | |
| | | imageUrl
| | N/A | |
| | | goodsStatus
| | N/A | |
| | | returnImageList
| | N/A | |
| | | | type
| N/A | |
| | | | link
| N/A | |
| | | sellerCurrencyPrice
| | N/A | |
| | | sellerCurrencyStoreCouponPrice
| | N/A | |
| | | sellerCurrencyPromotionPrice
| | N/A | |
| | | estimateCommission
| | N/A | |
| | | sellerRealTax
| | N/A | |
| | | estimateIncomeMoney
| | N/A | |
| | | returnExpense
| | N/A | |
| | | performancePrice
| | N/A | |
| | | estimateTaxIncomeMoney
| | N/A | |
| | | returnReasonList
| | N/A | |
| | | | language
| N/A | |
| | | | reason
| Order Claim
> Marketplace Reason
| As you can see from the response, we will get a list of reasons translated to different languages. We only want to look for language
: EN
and store the reason. If there is no EN
reason, we don’t want to store any of the other reasons.
Since the reasons are per line, we want to concatinate them. |
| bbl
| | | | N/A | |
We need to store every claim as action “Accept” because Shein does not give us the opportunity to accept or reject a return. Every return that comes in is considered accepted. In addition to the above mapping, when storing the Order Claim
record in Hemi we want to also store Order Claim
> Action
= Accept and Order Claim
> Status
= Completed. Everything else is as per the Claims abstraction - Claims general management
Any errors in the response we want to be displayed in the terminal when the cron is run with DEVMODETRUE.
Once we have successfully stored the claim(s) we need to make a third call which will be the actual refund.
Receive return order
API Call: POST /open-api/return-order/sign-return-order
API Docs: https://open.sheincorp.com/documents/apidoc/detail/3000238-2000004
We need to send a content-type
: application/json
as a header.
With this call we are basically informing Shein that the returned item(s) have been received and a refund is being pushed.
All triggers, validations etc are as per our refunds abstraction - Refunds send general logic
Example request body :
{
"returnOrderNo": "NRMFM000MT",
"goodsIdList": [4277386877782017]
}
Request mapping :
Shein Field | Hemi Field | Notes |
---|---|---|
returnOrderNo |
Order Claim > Marketplace ID |
|
goodsIdList |
Maximum of 50 ids in the list. |
We need to send the Order Item Line
> Marketplace Order Item ID
for the returned product(s) |
Example response :
{
"code": "0",
"msg": "OK",
"info": {
"returnOrderNo": "NRMFM000MT",
"goodsIdList": [
4277386877782017
]
}
}
From the response we don’t want to map anything. Whatever the response is (successful or unsuccessful) we need to act as per the refunds abstraction. We could receive a different code than “0” and this would mean NOT success. In this case we need to store an error.