Marketplaces / Shein / Shein Order Management / Shein Return Order

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:

  1. Get all returns (provided with very little information)

  2. Get the detail for each return with a separate call to ensure we have all the info for each return request

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

Is this article helpful?
0 0 0