Best Practices – Order process

Access the list often to stay up to date

The API provides an order list that gives you very fast but limited information on the orders that are still open and waiting to be handled. It shows the OrderID and the OrderItemIds in the order. This endpoint was designed to give you a fast and clean view on your current orders that you can check often without the need to import large amounts of data.

API Endpoint: https://api.bol.com/retailer/orders

We recommend polling this list every 5-15 minutes to determine if a new order has been placed by a customer. This endpoint is optimized to be polled often.

Use the details (once) only to ship

Once you are ready to pick, pack and ship the product, then use the orderId to fetch the order-details using the ‘Get an open order by order id’ endpoint.

https://api.bol.com/retailer/orders/{order-id}

This will give you the customer details you need to ship the physical product. This endpoint is not optimized to be polled often which is reflected in the limited Ratelimits. We recommend to only use this endpoint once for getting the order-details and do not poll it more often. The order-details are static.

Ship all order-items

An order can consist of one or more order-items. All mutations in the API are always based on the order-item. This means you ship or cancel every order-item separately using its orderItemId. Of course, you can physically ship them in one box if possible, but the API needs a separate confirmation/cancellation. As long as not all order-items are handled the order will remain open but will also appear in the shipment list for the parts that you have already sent.

 

Always check if your shipment was successful!

When using https://api.bol.com/retailer/orders/{order-item-id}/shipment to send us the confirmation of your shipment, make sure to always check if it was processed successfully. If it was not processed successfully you will need to fix the issue and send us a new shipment. If we do not receive a successful shipment, the order will expire and be cancelled and you will not receive payment for the order, regardless of whether you physically shipped it or not.

Worst case scenario: Your customer has your product, but you will not be paid because we did not receive a successful confirmation of your shipment.

You can prevent this by always checking the process-status of your shipment request using the process-status endpoint.

https://api.bol.com/retailer/public/redoc/v3#tag/Process-Status

 

Use the Transport endpoint if you need to ship before you have a Track&trace code

It is required that you supply a Track&Trace code for every shipment. However we understand that sometimes you have no access to your carriers information until the end of the day, while you did already pick, pack and process the products for shipment and need to confirm this with us.

It is possible to first confirm the handling of your shipment and add your Track&trace information later on the same day.

Use the https://api.bol.com/retailer/orders/{order-item-id}/shipment to confirm your shipment.

Make sure to remove the Transport part from the request.

{

  "shipmentReference": "B321SR",

  "shippingLabelCode": "PLR00000002",

  "transport": {

    "transporterCode": "TNT",

    "trackAndTrace": "3SBOL0987654321"
  }

}

When you do receive the transport information from your carrier (on the same day!) use the Transport endpoint to ADD this information to your existing shipment.

https://api.bol.com/retailer/transports/{transport-id}

Note that you need the transportId to connect carrier information to your existing shipment. You can retrieve the transportId from the shipment list or shipment details.

https://api.bol.com/retailer/shipments

Also note that you can only add transport information once. This endpoint ADDs information, it does not update your shipment. So you either supply it in the original shipment request, or you add it later through the transport endpoint

We do NOT recommend using the transport endpoint option due to the bad customer experience. Using the shipment request will trigger an e-mail to the consumer. If this does not have the Track&trace, he/she will not receive this. Adding it later through Transport will not trigger a new e-mail.

Use the Transport option only as a last resort.

 

Bol.com is not your archive

Both the order and shipment lists in the API are optimized to provide you fast and reliable information to quickly handle your sales process.

Due to legal, privacy and load-managing reasons we do not store orders and shipments indefinitely. We also remove customer information from the API after a period of time due to privacy concerns.

We recommend you import the data you need from our API into your own systems and handle them according to local law and privacy guidelines. Do not rely on the bol.com API as your archive and to provide you historic data on shipments or orders.