Orders and shipments

Version 3 of the Retailer API has been deprecated. Please migrate to the V4 API as soon as possible.

Shipments API

Based on your usage, the purchasable shipping labels endpoint might also apply to your process if you are purchasing labels from bol.com.

Logical process flow

order-flow description

Retrieve open orders

Retrieve open orders endpoint: returns a list of open orders.

This endpoint is used to retrieve all your current open orders, sorted by the creation date in descending order. The endpoint supports pagination by using the page query parameter and allows you to filter on FBB orders if you are participating in Logistics via Bol.com and FBR orders. In the response, you will find amongst other attributes the orderId and orderItems. This orderId can be used to retrieve the order details.

FBB orders – best practice

While this endpoint allows you to list both Fulfilment By Retailer (FBR) and Fulfilment By Bol.com (FBB) orders, we recommend only using it for orders that you fulfil yourself via FBR. Since FBB orders are picked, packed and sent by the bol.com warehouse, this means that open orders will be handled by bol.com. Once bol.com handles the open order, it is closed and listed as shipment. Shipments for FBB are available through the shipments endpoint.

We try to pick orders as soon as possible, and often an order is already picked before you poll the open orders endpoint. As a result you will not see the order in the open orders list anymore. To avoid missing the order entirely we recommend using the shipments endpoint for administrative purposes.

Retrieve a single order

Retrieve single order endpoint: returns a single order.

With the orderId from the get open orders endpoint, you can fetch all the order details for the specific orderId. In the response, you will find shipment details providing data that can be used for your shipment, and billing details providing data can be used to create the invoice.

Next to that, you will find all the order items that are part of the order. This can be either 1 - if the customer ordered only 1 item - or more if the customer ordered more than 1 item within the same customer order. The items within the order are known as order items, that are referred to as orderItemId. With this ID, you can either choose to ship this order item or to cancel this specific order item.

By default the single order request will return all items in the order, including both Fulfilment by bol.com (FBB) and Fulfilment by retailer (FBR) fulfilment methods. You should check the fulfilment method per orderItem when reviewing your open order.

Ship an order item

Ship order item endpoint: Ship an order item and provide shipment information.

With this endpoint, it is possible to ship an order item from a specific customer order. There are two ways to ship an order item:

  1. Shipping using your own shipping label. If you want to ship an order item using your own shipment, you need to provide transport information. For this we require a transporterCode (see table below) and a trackAndTrace. Do note that the trackAndTrace can optionally be left empty in this call. If you want to send them to bol.com later, you can use the Add transport information endpoint. However, there is no need to do so if you send all the data to us at once.

    If you ship this order item by using your own transporter, you should leave the shippingLabelCode empty. It is not possible to both submit transport information as well as a shipping label code.

  2. Shipping using a purchased shipping label from bol.com. In case you purchased a shipping label from bol.com, you need to add the shipping label code that you obtained from the get purchasable shipping labels endpoint to the response. In that case, you may not also provide transport information.

Packing slips via the API

You cannot retrieve a packing slip via the API. Also, as of January 2020, it is no longer mandatory to send a packing slip with an order, as long as the order number is already included on the shipping label. If you purchase normal bol.com shipping labels on API v4 and above, the order number is already on it and a packing slip is therefore not necessary.

In the following situations, it is still necessary to attach a packing slip:

  • When you buy normal shipping labels via v3 of the API the order number will not automatically appear on the label.

  • When you use your own shipping labels and you cannot add the order number to the shipping label.

If you do need to attach a packing slip to the order and you don’t use the bol.com packing slip from the Seller Dashboard, you can generate your own packing slip via the information available in the Get order endpoint.

Cancel order item

Cancel order item endpoint: Cancel an order item and provide a reason for the cancellation.

There are two scenarios that can occur regarding canceling an order item:

  1. The customer requested a cancellation. When retrieving a single order you will receive a cancelRequest value for every order item. Whenever this value is set to True, the customer cancelled the order item. You don’t need to ship this order item and we will refund the customers’ payment. We do require you to confirm the cancellation request through the cancellation endpoint. It is possible that a customer only cancels a single item within an order, in which case you only have to cancel this one item and can ship the other order items. Please select the reasonCode REQUESTED_BY_CUSTOMER when confirming the cancellation request. A customer cancellation will not count negatively towards your cancellations performance indicator.

    Please note that between retrieving an open order and actually shipping an order item or canceling an order item yourself, 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 the open order again just before shipping the order item to check for a possible cancellation request from the customer.

  2. You are unable to ship an order item to the customer. If this happens - for example due to missing stock - you have the option to cancel an order item from the order yourself. The customer never requested a cancellation in this scenario, and by canceling the order item you will unfortunately disappoint the customer. Canceling an order item without a cancellation request from the customer will lead to a negative score on your cancellations performance indicator. Using the reason REQUESTED_BY_CUSTOMER without a customer cancellation request will count negatively as well. You can find your scores through the performance indicators endpoint. Bol.com will manage the refund towards the customer when canceling an order item yourself.

Retrieve shipment list

Retrieve shipment list endpoint: returns a list of past shipments.

This endpoint is used to retrieve all your shipments, sorted by the shipment date in descending order. The endpoint supports pagination by using the page query parameter and allows you to filter on FBB orders if you are participating in Logistics via Bol.com and FBR orders. Moreover, you can search within all the shipments on orderId, so that you can find easily and quick a single shipment based on the orderId.

In the response, you will find – amongst other attributes – the shipmentId, shipmentItems, and the related transport information. You can use the shipmentId to fetch more shipment details using the ‘Get a shipment by shipment id’ endpoint. Moreover, the transportId is in the same response, and can be used to add transport information in case you didn’t do so while shipping the order item.

This endpoint will only return shipments that were created over the past three months.

Retrieve a single shipment

Retrieve single shipment endpoint: returns a single shipment.

To fetch the details of a shipment, you can use this endpoint to get all the shipment details based on the shipmentId. In the response, you will find the items that where shipped, the transport information, and the details of the customer. Based on the GDPR, we omit the transport information from the response when the transport is more than a year old.

With a specific shipmentId you can retrieve shipment information from up to two years ago.

Adding transport information to shipment

Add transport information endpoint: Add transport information to a shipment.

In a situation where you already want to ship an order item, but you don’t know the track and trace details, the customer will not be informed of the track and trace-related information. This is not an optimal customer experience for your customer. In this scenario, this endpoint allows you to still send us the track and trace. From that moment, the customer will also receive updates on events when this track and trace is scanned.

Customers pay attention to the track and trace, and it is therefore important that you provide this data.

You can only append data with this endpoint. It is therefore not possible to change the transporter itself, but you are allowed to add data.

Be aware that it is not needed to use this endpoint if you provide us directly with the track and trace and the transporter when shipping an order item. For that reason, this step is optional in your flow when shipping an order item.


The table below shows all available transporter codes that can be used while creating a shipment or adding a transporter code to a shipment that was created earlier. Please make sure that the transporter code is available for the version of the API that you are using at that time.

Some transporters use a DASH while others use an UNDERSCORE. Please make sure to use the correct notation.

Table 1. Transport services and corresponding transporter codes
Transporter / service API transporter code







PostNL extra@home


PostNL Briefpost


TNT Express




DPD Nederland


DPD België


Bpost België


Bpost Briefpost






FedEx Nederland


FedEx Belgie






DHL Germany


DHL Global mail


Transportservice Nederland














NedWRK (Red je pakketje)