Bol Get 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 get orders on Bol.

The get order flow consist of 2 steps first we get the orders general information and then we call each order individually to get the rest of the details. The best case for us is to get all order ids in an array and then start calling each order separately and store it in Hemi. This way we will be storing the order directly on the relevant status and we wont need to hold them on “Pending“ status.

Get All Orders

The first run of get orders will check for new orders and we do not want to specify the change-interval-minute parameter if there are no records in last_date_run table. Else we want to get the date from the last_date_run table and overlap with 1 hour. Please note the most minutes we can overlap is 60mins and the parameter is: change-interval-minute=60

We would like to be able to filter the orders based on the fulfilment-method which will be set in Account Bol > Fulfilment Method and will have to specify it as parameter: fulfilment-method: Fulfilled by the retailer (FBR) or fulfilled by (FBB).

Please note if we do not select Account Bol > Fulfilment Method we want to use fulfilment-method=FBR as default.

Also we would like to get all orders despite of their status so we have to specify parameter status= ALL

API Call: GET https://api.bol.com/retailer/orders?change-interval-minute=60&status=ALL&fulfilment-method=ALLQuery Parameters:

Default: 1 The requested page number with a page size of 50 items. | | fulfilment-method | string Default: "FBR" Enum: "FBR" "FBB" "ALL" Fulfilled by the retailer (FBR) or fulfilled by (FBB). In order to retrieve both FBR and FBB orders, ALL can be used as a parameter. | | status | string Default: "OPEN" Enum: "OPEN" "SHIPPED" "ALL" To filter on order status. You can filter on either all orders independent from their status, open orders (excluding shipped and cancelled orders), and shipped orders. | | change-interval-minute | integer <= 60 To filter on the period in minutes during which the latest change was performed on an order item. To avoid missing any orders, the value assigned to this parameter should be equal to or larger than the time elapsed between polling the API. For example, if you poll every 10 minutes, then assign a value of 12 minutes to the change-interval-minute parameter. As a result, you get a list of order items each having latestChangedDateTime field. You can use this field as a version identifier to check if version of the order item has changed compared to the most recent version in your system. |

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

Sample Response:

{
    "orders": [
        {
            "orderId": "1043946570",
            "orderPlacedDateTime": "2019-04-29T18:18:21+02:00",
            "orderItems": [
                {
                    "orderItemId": "6042823871",
                    "ean": "8717418510749",
                    "fulfilmentMethod": "FBR",
                    "fulfilmentStatus": "OPEN",
                    "quantity": 3,
                    "quantityShipped": 3,
                    "quantityCancelled": 0,
                    "cancellationRequest": false,
                    "latestChangedDateTime": "2019-04-29T18:18:21+02:00"
                }
            ]
        },
        {
            "orderId": "1042831430",
            "orderPlacedDateTime": "2019-04-20T12:58:39+02:00",
            "orderItems": [
                {
                    "orderItemId": "6107331382",
                    "ean": "8712626055143",
                    "fulfilmentMethod": "FBR",
                    "fulfilmentStatus": "OPEN",
                    "quantity": 1,
                    "quantityShipped": 1,
                    "quantityCancelled": 0,
                    "cancellationRequest": false,
                    "latestChangedDateTime": "2019-04-20T12:58:39+02:00"
                },
                {
                    "orderItemId": "6107331383",
                    "ean": "8804269223123",
                    "fulfilmentMethod": "FBR",
                    "fulfilmentStatus": "OPEN",
                    "quantity": 1,
                    "quantityShipped": 1,
                    "quantityCancelled": 0,
                    "cancellationRequest": false,
                    "latestChangedDateTime": "2019-04-20T12:58:39+02:00"
                }
            ]
        },
        {
            "orderId": "A4K8290LP0",
            "orderPlacedDateTime": "2019-12-06T13:04:34+01:00",
            "orderItems": [
                {
                    "orderItemId": "2070906705",
                    "ean": "8718846038683",
                    "fulfilmentMethod": "FBR",
                    "fulfilmentStatus": "OPEN",
                    "quantity": 1,
                    "quantityShipped": 1,
                    "quantityCancelled": 0,
                    "cancellationRequest": false,
                    "latestChangedDateTime": "2019-12-06T13:04:34+01:00"
                }
            ]
        },
        {
            "orderId": "B3K8290LP0",
            "orderPlacedDateTime": "2020-01-01T13:04:34+01:00",
            "orderItems": [
                {
                    "orderItemId": "2070906706",
                    "ean": "8718846038683",
                    "fulfilmentMethod": "FBR",
                    "fulfilmentStatus": "OPEN",
                    "quantity": 1,
                    "quantityShipped": 1,
                    "quantityCancelled": 0,
                    "cancellationRequest": false,
                    "latestChangedDateTime": "2020-01-01T13:04:34+01:00"
                }
            ]
        }
    ]
}

Mapping: From the response the only thing we want to use is the orderId which we will use in the next call - Get Single Order By Order Id in order to get all order details.

Get Single Order By Order Id

In order to get the complete order details we will have to make additional request. API Call: GET https://api.bol.com/retailer/orders/{{orderId}}

Docs: https://api.bol.com/retailer/public/redoc/v9/retailer.html#operation/get-orderSample Request: GET https://api.bol.com/retailer/orders/123141231

Sample Response:

{
    "orderId": "A4K8290LP0",
    "pickupPoint": false,
    "orderPlacedDateTime": "2019-12-06T13:04:34+01:00",
    "shipmentDetails": {
        "salutation": "FEMALE",
        "firstName": "Hans",
        "surname": "de Grote",
        "streetName": "Skywalkerstraat",
        "houseNumber": "199",
        "zipCode": "1234AB",
        "city": "PLATOONDORP",
        "countryCode": "NL",
        "email": "2mqmu3hefoawq3mqgzxh4hbpkyh2rs@verkopen.test2.bol.com",
        "language": "nl"
    },
    "billingDetails": {
        "salutation": "MALE",
        "firstName": "Pieter",
        "surname": "Post",
        "streetName": "Skywalkerstraat",
        "houseNumber": "21",
        "houseNumberExtension": "X",
        "extraAddressInformation": "Extra informatie",
        "zipCode": "1234AB",
        "city": "PLATOONDORP",
        "countryCode": "NL",
        "email": "2yldzdi2wjcf5ir4sycq7lufqpytxy@verkopen.test2.bol.com",
        "company": "Pieter Post",
        "vatNumber": "NL123456789B01",
        "kvkNumber": "99887766",
        "orderReference": "Mijn order ref"
    },
    "orderItems": [
        {
            "orderItemId": "2070906705",
            "cancellationRequest": false,
            "fulfilment": {
                "method": "FBR",
                "distributionParty": "RETAILER",
                "latestDeliveryDate": "2019-12-15",
                "expiryDate": "2019-12-18",
                "timeFrameType": "REGULAR"
            },
            "offer": {
                "offerId": "8f6283e3-de98-c92f-e053-3598790a63b5",
                "reference": "MijnOffer0021"
            },
            "product": {
                "ean": "8718846038683",
                "title": "adidas Originals Booklet case Bohemian color for iPhone 7/8 colourful"
            },
            "quantity": 1,
            "quantityShipped": 1,
            "quantityCancelled": 0,
            "unitPrice": 34.99,
            "commission": 2.22,
            "latestChangedDateTime": "2019-12-06T13:04:34+01:00"
        }
    ]
}

Mapping:

Order Claim > Marketplace Date = Orders > Order Created Time Order Claim > Marketplace ID = Product In Order > Item Order Line ID Order Claim > Marketplace Reason = “Cancelation Request“ Order Claim > Type = “Cancel“ Order Claim > Claim Status = “Created“ Order Claim > Initiated By = “Buyer“ Order Claim > Action = (based on Account Bol > Cancel Action Default field) Order Claim > Status = (based on Account Bol > Cancel Action Default field) With the relevant Order Claim Row information

Please note if the claim is already added we do not want to make duplicates.

If we have selected default ACCEPT action for the cancel claim we want to set: Order Claim > Action = Accept Order Claim > Status = Pending Order Claim > Claim Status = “Created“

If we have selected default REJECT action for the cancel claim we want to set: Order Claim > Action = Reject Order Claim > Status = Completed Order Claim > Claim Status = “Rejected“

If there is no default actions set we store the claim with empty Order Claim > Action and Order Claim > Status and Order Claim > Claim Status = “Created“ | | | fulfilment | | | | | | | method | Orders > Marketplace Fulfillment Channel | Please note for all order items in the order we will have the same method. | | | | distributionParty | N/A | | | | | latestDeliveryDate | N/A | | | | | expiryDate | N/A | | | | | timeFrameType | N/A | | | | offer | | | | | | | offerId | Product In Order > Channel Item ID | | | | | reference | N/A | | | | product | | | | | | | ean | Product Account > Marketplace EAN OR Product > EAN | Based on the EAN we want to map the Product and get the Product In Order >SKU The mapping will have to check first Product Account > Marketplace EAN and then Product > EAN If for some reason we have duplicate EANs in Hemi we want to pick the first one. | | | | title | Product In Order > Item Title | | | | quantity | | Product In Order > Quantity | | | | quantityShipped | | | Based on this we will know if the order is fully shipped or partially by comparing all order items quantity and quantityShipped. We want to create a shipment for all shipped products and mark them as completed. Also we want to update the order status, order item status and order item line status as expected.

Since this field is on product in order level if we have partial shipments we can track the Product In Order > Item Order Line ID then to get all Order Item Line > Id and match them against Order Shipment Row > Order Item ID | | | quantityCancelled | | | Based on this we will know if the order is fully cancelled or partially by comparing all order itemsquantity and quantityCancelled. We want to create a refund row with all cancelled products and mark it as completed. Also we want to update the order status, order item status and order item line status as expected. | | | unitPrice | | Product In Order > Price | | | | commission | | Orders > Marketplace Fee | We want to calculate all order items commission and store them as Orders > Marketplace Fee | | | latestChangedDateTime | | N/A | |

Order status Mapping:

Once we get all the order information we want all enrichments (Enrichments includes but is not limited to: Debundler, Split Shipping Cost, Vat calculation, Subtotal, Acknowledged, etc.) to take place as per our standard abstraction. All validations which are not specifically mentioned are as per abstraction.

Additional Details

To check and to ask. This endpoints gives you insights on the shipment and billing details that can be used for your shipments and to make invoices. Since billing and shipping details include sensitive customer information such as address, vatNumber and kvkNumber, the customer can choose to conceal all their personal information. If this option is enabled by the customer, the Get an order by order id endpoint returns the value ANONYMISED for all the fields in the shipmentDetails and billingDetails element except the Salutation field, which returns the value UNKNOWN.

The retailer must erase all the customer data from their own database if the customer chooses to conceal their information. TheSalutation field returns the value UNKNOWN when the customer has not provided information about their gender. The email field returns no value after 61 days of placing the order. The billing information is not exposed to the retailer if the order has been created one month ago.