Bol Cancel Orders

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

The purpose of this document is to describe how we cancel orders on Bol.

There are two scenarios that can occur regarding cancelling an order item. When the buyer requests a cancellation and when the seller wants to cancel on his own. Below you can find the business information followed by the actions scope

Business information from Bol:

Cancellation by the customer

When retrieving a single order or a list of orders, we receive a cancellationRequest value for every order item. If this value is set to True, this implies that the order item is requested to be cancelled by the customer. In such cases, we should confirm the cancellation request through the Cancel an order item by an order item id endpoint and not ship this order item.

It is possible that a customer only cancels a single item within an order. In such cases, we only have to cancel this one item and can ship the other order items.

To confirm the cancellation of an order item within an order, we should assign the value REQUESTED_BY_CUSTOMER to the reasonCode parameter.

During the time between retrieving an open order and actually shipping an order item or cancelling an order item, a customer can still request a cancellation. If there is a lot of time between retrieving an open order and shipping the order item, it is advisable to retrieve all the open orders again just before shipping the order item to check for a possible cancellation request from the customer.

Cancellation by the retailer

If we cannot ship an order item to the customer, for example due to missing stock, it is possible to cancel an order item from the order ourselves.

If we use the reason REQUESTED_BY_CUSTOMER without a customer cancellation request this will impact the seller performance scores negatively. Which means we need to make sure we are sending it only when it is associated with a claim (as explained below). The metrics are on the marketplace itself so nothing for us to check

All Cancellation by the customer will be downloaded and stored as claims in Hemi. However Cancellation by the retailer is just a cancellation request which we will trigger from the refund rows.

All cancellation flows below are to be treated as Hemi Pre Shipment Cancellation flow

Cancel an Order Item by the retailer

Bol allows only full product quantity cancellation. This means a full SKU with all its quantity together. We can NOT cancel a single quantity from a Product in Order. The cancellations are per order and all order Item Ids must be from the same order. The cancellation work for all type of Pre Shipment Cancellations. We want all triggers, status, error handling, etc. to be as per the Refunds send general logic

For each cancellation we must specify the reason. Here is a list of reasons which we want to store in Hemi and display in the refund UI. Please note we want to send the Code and display the Name.

<v1.2>If no reasons is added in Order Payment > Reason field we want to use OTHER</v1.2>

API Call: PUT https://api.bol.com/retailer/orders/cancellation

API Doc: https://api.bol.com/retailer/public/redoc/v9/retailer.html#operation/cancel-order-item

Sample Request Body:

{
  "orderItems": [
    {
      "orderItemId": "2012345678",
      "reasonCode": "BAD_CONDITION"
    },{
      "orderItemId": "2012345679",
      "reasonCode": "ORDERED_TWICE"
    }
  ]
}

Please note the orderItems is an array and we can specify more than one orderItemIdMapping:

Sample Response:

{
  "processStatusId": "1234567",
  "entityId": "987654321",
  "eventType": "CANCEL_ORDER",
  "description": "Example process status description for processing 987654321.",
  "status": "PENDING",
  "errorMessage": "Example process status error message.",
  "createTimestamp": "2018-11-14T09:34:41+01:00",
  "links": [
    {
      "rel": "self",
      "href": "https://api.bol.com/shared/process-status/1234567",
      "method": "GET"
    }
  ]
}

After each successfully send feed for order cancel we will receive the entityId from the response and need to store it in Marketplace Feeds table with the rest of the details as follows. Based on the response reader Bol Order Response Reader afterwards we want to update all relevant fields and statusesIf any errors are returned we want to store them in Order Errors table. However this will be after the response reader check the feed status.

Please note we will also add the feed objects which after processing need to be removed.

Cancel an Order Item by the customer

When we have cancellation request from the customer we will be storing this as a claim. There will be two ways of handling the cancel claim Accept or Reject.

1 When Default Action is Not selected:

If we would like to manually accept cancel claim we just need to set it as Order Claim > Action = Accept and Order Claim > Status = Pending which will trigger the cancellation request. After success we want to mark the Order Claim > Status = Completed and Order Claim > Claim Status = “Accepted & Refunded” and store the refund row with all the required details. If we receive an error we want to store it in Order Errors table with the relevant error message **and set Order Claim > Status = Error**

If we would like to manually reject cancel claim we just need to set it as Order Claim > Action = Reject and Order Claim > Status = Pending which actually will do nothing because if we would like to reject the cancellation claim we do not refund the buyer but to keep the same flow and UX we want to just mark the cancellation claim as completed. The cron just need to update the status as Order Claim > Status = Completed and Order Claim > Claim Status = “Rejected“

2 When default action Is selected as “Accept“:

If we have default action set as Accept with the actual download of the claim we need to set it as Order Claim > Action = Accept and Order Claim > Status = Pending which will trigger the cancellation request. After success we want to mark the Order Claim > Status = Completed and Order Claim > Claim Status = “Accepted & Refunded” and store the refund row with all the required details. If we receive an error we want to store it in Order Errors table with the relevant error message **and set Order Claim > Status = Error**

3 When default action Is selected as “Reject“:

If we have default action set as Reject with the actual download of the claim we need to set it as Order Claim > Action = Reject and Order Claim > Status = Completed and Order Claim > Claim Status = “Rejected“

Bol allows only full product quantity cancellation. This means a full SKU with all its quantity together. We can NOT cancel a single quantity from a Product in Order. The cancellations are per order and all order Item Ids must be from the same order. The cancellation work for all type of Pre Shipment Cancellations. We want all triggers, status, error handling, etc. to be as per the Claims general management

For each cancellation we must specify the reason. For all cancellations requested by the customer we want to use reason “REQUESTED_BY_CUSTOMER“

API Call: PUT https://api.bol.com/retailer/orders/cancellation

API Doc: https://api.bol.com/retailer/public/redoc/v9/retailer.html#operation/cancel-order-item

Sample Request Body:

{
  "orderItems": [
    {
      "orderItemId": "2012345678",
      "reasonCode": "REQUESTED_BY_CUSTOMER"
    },{
      "orderItemId": "2012345679",
      "reasonCode": "REQUESTED_BY_CUSTOMER"
    }
  ]
}

Please note the orderItems is an array and we can specify more than one orderItemIdMapping:

Sample Response:

{
  "processStatusId": "1234567",
  "entityId": "987654321",
  "eventType": "CANCEL_ORDER",
  "description": "Example process status description for processing 987654321.",
  "status": "PENDING",
  "errorMessage": "Example process status error message.",
  "createTimestamp": "2018-11-14T09:34:41+01:00",
  "links": [
    {
      "rel": "self",
      "href": "https://api.bol.com/shared/process-status/1234567",
      "method": "GET"
    }
  ]
}

After each successfully send feed for order cancel we will receive the entityId from the response and need to store it in Marketplace Feeds table with the rest of the details as follows. Based on the response reader Bol Order Response Reader afterwards we want to update all relevant fields and statuses If any errors are returned we want to store them in Order Errors table. However this will be after the response reader check the feed status.

Please note we will also add the feed objects which after processing need to be removed.