Zalando Cancellation

The purpose of this document is to detail the requirements and flow of cancelling an item to the Zalando platform from Hemi

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

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

Similar to the Shipping status update we can do a Cancellation status update to the same endpoint using the same JSON format with the only difference being the status value

The real difference is within Hemi and the way we handle Cancellations. For us this is a “Refund” for an item that is done prior to any shipments

Requirements:

• We have a “pending” refund that needs to be processed to the marketplace
• The item lines included in this refund must be full priced. If we have an quantity and a half we will block it with the relevant error of Cant refund less than full line refund for order item line
• The selected full price item lines should still have enough Order Item Lines on relevant status (initial, reserved) to fulfil the cancellation quantity request (meaning if someone has requested via the price 2 full items to be cancelled 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 cancellation request. Please specify only products for cancellation and split any other for "Return" if needed)
• Order status on RFS, Incomplete or Partially Shipped - the most important part for Cancellation (and Return) for Zalando is the line status as that’s where we will get the exact information for each line that is requested to be cancelled or returned. If everything is working as expected this should result in orders in the given statuses applicable for Cancellation

In general we want to employ all standard refund validations. The above requirements are with the idea to explain the main points needed for Zalando to better utilise the abstraction and pinpoint as best as possible any differences

If the selection from our refunds satisfies the above requirements we should progress and try to mark the relevant Lines as “cancelled”

Example call:

{
  "data":{
    "id":"$ORDER_LINE_ID",
    "type":"OrderLine",
    "attributes":{
      "status":"canceled"
    }
  }
}

Mapping:

In case of an issue we should put the Order Payment record on status “error” and store the relevant error in the Order Error table. If successful we should mark that correctly to our Payment record and update the relevant Lines within Hemi as “canceled” (including filling all mandatory fields like statuses on Product in Order level, refunded sum so far on Order, etc.)

Note: Generally we always want to do Cancellation first before Return if we have multiple types of lines for Zalando. This means that if we have a product with 1 line shipped and one not yet we would’ve wanted to first cancel the one not shipped and then return the other one. Because of the way we store refund row lines though from the Hemi UI (we can’t choose which lines are added) and the fact we don’t want to send both operations (Cancel & Return) within the same refund in Hemi in cases where we have combined lines on a Hemi Refund this should be blocked. For more info and examples please see the Return documentation

(v1.4) 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 Cancellation per each order item line. This means that a legitimate cancellation 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.

The solution for this should allow for future exposure of the information on line level so it can be tracked what is/has happened with this line in a case of partial successes.

In case all lines are successfully processed we need to mark the Payment Record as completed and update all additional fields as per our abstraction. In case where we have a mixture of success and error, we should update each line accordingly on the order and product, etc. (as per the abstraction 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