Bol Order Return

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)

<v1.1>Bol do not have the concept of “Refund” (money transaction) that we can use. Everything is handled by a “return” functionality working on a quantity by quantity basis. As for the cancellation we might have a return request initiated by the buyer OR even without any such a return request created by the seller. The below explains how to track and handle the case when a buyer has initiated a return

This flow is to be treated as Hemi Post Shipment Refund flow</v1.1>

The purpose of this document is to describe how we handle returns on Bol marketplace. The returns on Bol are straightforward and we can either Accept or Reject a return. We should be checking if there are new returns (claims) with handled = “false“ only and please note we are storing only handled = “false“ returns and we do not want to download any rejected or accepted returns. If we get the return we need to store it as a claim in Order Claims table in Hemi. Then we have to decide if we want to reject or accept the return request. We can process a return manually or we should have default actions in Account Bol for the Accept and Reject claims which are optional. If we reject the claim there are no any other steps we need to do just update the status of the claim on Bol.

Get Returns

We will be downloading only returns with status handled = “false“ and for the relevant fulfilment-method which is set in Account Bol <v1.5>Please note we will be receiving claims with more than one product and more than one quantity however we want to split the return into different claims based on the products (rmaId). For example if we have a return with two products we want to store two claims in Hemi with one claim row. This way we can refund both products using our refund UI because our relation between refunds and claims is 1-to-1. </v1.5>

API Call: GET https://api.bol.com/retailer/returns

API Docs: https://api.bol.com/retailer/public/redoc/v9/retailer.html#operation/get-returns

Query parameters:

Default: "FBR" Enum: "FBR" "FBB" The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by http://bol.com (FBB). | Account Bol > Fulfilment Method |

Sample Request: https://api.bol.com/retailer/returns?handled=false&fulfilment-method=FBR

Sample Response:

{
  "returns": [
    {
      "returnId": "1",
      "registrationDateTime": "2016-11-14T11:06:48.423+01:00",
      "fulfilmentMethod": "FBR",
      "returnItems": [
        {
          "rmaId": "31234567",
          "orderId": "4012345678",
          "ean": "9789076174082",
          "expectedQuantity": 1,
          "returnReason": {
            "mainReason": "Niet naar verwachting",
            "detailedReason": "Niet naar verwachting",
            "customerComments": "Lorem Ipsum"
          },
          "handled": false,

          ]
        }
      ]
    }
  ]
}

Mapping:

We have to map the Product in Order > EAN and get the Order Item Line > ID

<v1.4> Since in Hemi we can make offline refunds we do not want to make any additional validation for storing the Order Claim Rows but we just need to make sure the total returned quantity match the our Order Item Lines. If for some reason there is a discrepancy we want to store an error in Order error table and set Order Claim > Status = **Error <v1.4><v1.3> If the EAN is missing and we ae not able to get the Order Item Line > ID we want to store an error in Order error table and set Order Claim > Status = **Error <v1.3> | | | | expectedQuantity | | N/A | The quantity which need to be returned. Based on this we will know how many Order Item Line Ids to add in Order Claim Row if quantity is > 1 | | | | returnReason | | | | | | | | mainReason | Order Claim > Marketplace Reason | | | | | | detailedReason | N/A | | | | | | customerComments | N/A | | | | | handled | | N/A | Always “false“ |

When we are downloading returns we need to be checking if the default actions are set or we store it with empty Order Claim > Action and Order Claim > Status
Also we want to set the Order Claim > Claim Status = “Created“

Accept Returns

The accepting is simply handling the status of the return. There is couple of ways of accepting a claim it can be set as default or triggered manually.

1 When Default Action is Not selected:

If we would like to manually accept a return we just need to set it as Order Claim > Action = Accept and Order Claim > Status = Pending which will trigger the status update of the claim 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**

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 status update of the claim. 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**

API Call: PUT https://api.bol.com/retailer/returns/{rma-id}API Docs: https://api.bol.com/retailer/public/redoc/v9/retailer.html#operation/handle-returnPath parameters

Request Body

Mapping:

*Sample Request:<v1.5>API Call: PUT https://api.bol.com/retailer/returns/{{Order Claim > Marketplace Id}}*</v1.5>

Body Request:

{
  "handlingResult": "RETURN_RECEIVED",
  "quantityReturned": 1
}

Sample Response:

{
  "processStatusId": "1234567",
  "entityId": "987654321",
  "eventType": "HANDLE_RETURN_ITEM",
  "description": "Example process status description for processing 987654321.",
  "status": "SUCCESS",
  "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"
    }
  ]
}

The acceptance is asynchronous and we will have to create a new feed in Marketplace Feeds table. After each successfully send feed for order return 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 afterwards we need to mark the order as “Cancelled“ or leave it with the current status if not fully cancelled. If any errors are returned we want to store them in Order Errors table after the Bol Order Response Reader

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

As previously mentioned all validations, triggers and updates are as per the validation based on the type of claim we can do here

Reject Returns

The rejecting is simply handling the status of the return.

1 When Default Action is Not selected:

If we would like to manually trigger a refund we just need to set it as Order Claim > Action = Reject and Order Claim > Status = Pending which will trigger the status update of the claim After success we want to mark the Order Claim > Status = Completed and Order Claim > Claim Status = “Rejected“

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**

2 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 = Pending which will trigger the status update of the claim. After success we want to mark the Order Claim > Status = Completed and Order Claim > Claim Status = “Rejected“

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**

API Call: PUT https://api.bol.com/retailer/returns/{rma-id}API Docs: https://api.bol.com/retailer/public/redoc/v9/retailer.html#operation/handle-return

Path parameters

Request Body

Mapping:

*Sample Request:<v1.5>API Call: PUT https://api.bol.com/retailer/returns/{{Order Claim > Marketplace Id}}*</v1.5>

Body Request:

{
  "handlingResult": "RETURN_DOES_NOT_MEET_CONDITIONS",
  "quantityReturned": 1
}

Sample Response:

{
  "processStatusId": "1234567",
  "entityId": "987654321",
  "eventType": "CREATE_RETURN_ITEM",
  "description": "Example process status description for processing 987654321.",
  "status": "SUCCESS",
  "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"
    }
  ]
}

The rejection is asynchronous and we will have to create a new feed in Marketplace Feeds table. After each successfully send feed for order ship 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.

If any errors are returned we want to store them in Order Errors table after the Bol Order Response Reader

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

As previously mentioned all validations, triggers and updates are as per the validation based on the type of claim we can do here