Zalando Returns (post fulfilment Refund)

The purpose of this document is to describe the process of triggering, mapping and sending a refund to Zalando after shipment has already been done

API Docs: https://developers.merchants.zalando.com/docs/orders-returns.html

API Call: PATCH /merchants/{merchant_ID}/orders/{order_ID}/items/{order_item_ID}/lines/{order_line_ID}

Again in a similar to the Shipment and Cancellation status updates, to trigger a return (refund) we are working simply with a status update with the difference to Zalando this time being also the addition of a reason. The general expectation is that we will be marking products as “returned” only once they’ve hit a warehouse but in reality this allows for a seller to return the money of a client based on their own decision no matter if a product is driving to a warehouse or not

Requirements for Return:

• We have a “pending” refund that needs to be processed to the marketplace
• The items included in this refund must be full priced. If we have an item and a half we will block it with the relevant error of “Price mismatch between whole item and provided value to determine how much quantity we should mark as returned”
• The selected full price items should still have enough Order Item Lines on relevant status (shipped) to fulfil the return quantity request (meaning if someone has requested via the price 2 full items to be returned but we have only one line on the “correct” status we will block it with the error of “Not enough available products to fulfil the return request. Please make sure you have enough lines available for return)

IMPORTANT: As the flows for Cancellation and Return follow the same steps it is crucial to make a decision what to do. In cases when we have the option to potentially try for both scenarios Cancellation request should ALWAYS take priority. To further explain this let’s take the following example - we have an order with one item with 3 quantity - 2 on initial status and one shipped status:

• If we have a refund request with 1 or 2 full items we are supposed to take it as cancellation request and process it correctly
• If we have a refund request with 3 full items we are supposed to take it as cancellation request and block it with the relevant error

Basically we are not allowing Return requests prior to everything being either on Cancelled or Shipped statuses. Everything prior to that for an item we treat as Cancellation request. This is a per item check though. This means if we have 2 items in an order, one with lines still on “initial” status, the other fully shipped and we have a refund request for the second one we should allow the return request to be processed. If someone requests a refund for both items though we should threat it as Cancellation request and as per its documentation block it with the relevant status

All of this also leads that point 3 from the requirements above can happen only in the case where all lines for the SKUs in the request are on Shipped or Cancelled statuses

Example request:

{
  "data":{
    "id":"$ORDER_LINE_ID",
    "type":"OrderLine",
    "attributes":{
      "status":"returned",
      "reason": "$INTEGER_CODE"
    }
  }
}

Mapping:

We have to map to our Reasons and the way we are displaying them based on the order Marketplace the following reasons for Zalando:

The Hemi Users have to see the Description option where we need to be sending the corresponding Code within the above mapped call

If a send Return request is unsuccessful we should put the Order Payment record on status “error” and store the relevant error in the Order Error table. If it is successful though we have to mark the payment record in Hemisphere and update the relevant Order Item Line > Status fields as “returned” (including filling all mandatory fields like statuses on Product in Order level, refunded sum so far on Order, etc.)

(v1.1) The transaction ID we generate should be in the format of Orders > Marketplace Order ID followed by the next available 2 digit numeric value from the available refunds (end result should be like this hduw68a6d87wta8d7686_01, fgfggg172639739172gg31hxx_02 and so on.

Everything else added or generated should be as per our standard Refunds abstraction

Last but not least stands the problem with multiple calls for the same Payment record. We have semi handled this while doing Walmart but only to Refund Row level, where for Zalando we need to be able to handle it on Refund Row Line level. This issue is coming from the way we communicate with Zalando - we can only send Return per each order item line. This means that a legitimate return request might contain 2-3-7-etc. order item lines at which point if any of those is wrong where the others have been successful we need to store this correctly in Hemi and handle it for any further updates.

To do this we need to introduce a status field on refund row line level as well which will basically hold the information if an order item line communication was completed or not (error). In case all lines are successfully processed we need to mark all refund row lines accordingly and set the Payment Record as completed. In case where we have a mixture of success and error, we should update each refund row line accordingly and set the status of the payment record to “Partially Completed” and store the error in the Order Error section.

Please note: an error on a line should not stop us from going forward. Meaning if we have 3 lines to refund, the first one is successful, the second one is error we still want to try and send the third one too as it is a separate call and it might be success. Also please have in mind “Partially Completed” status is to be treated as a final status! Anything that needs resubmitting should be done so in a new Payment Record. Still a validation would be good where in case there is already values on the rows of any such payment record (in other words someone has changed the status and trying to resubmit) we should automatically block this and set an error on the whole piece with an error in “Order Error” section