Orders and Shipments

Depending on your usage, the Get delivery options endpoint might also apply to your process if you are purchasing labels from bol.

Get a list of orders: Retrieves a list of all open and handled orders. Handled orders will only remain visible for 48 hours after being handled.

This endpoint sorts all your currently open and handled orders by the creation date in the descending order. This means that the new orders appear at the top of the list. It supports pagination and allows you to filter your orders based on the fulfilment methods. For more information about the fulfilment methods, see Filtering order items by fulfilment method.

In the response, this endpoint returns a summary of the order consisting of the following information:

Use the order-id as an input parameter to the Get an order by order id endpoint to get all the information about a single order.

Get an order by order id: Retrieves specific details of an order using the orderId. It returns all open items in addition to the items that were shipped or cancelled within the last three months.

This endpoint gives you the following details about an order in its response body:

This endpoint 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.

By default, a single order request returns all items in the order, including the FBB and FBR fulfilment methods.

To verify this, check the fulfilment method per orderItem when reviewing your open order. The order items can also be a mixture of Verzenden via bol and non-Verzenden via bol shipping methods, which will be indicated by the distributionParty being either BOL or RETAILER.

Cancel an order item by an order item id: Cancels an order item and provides a reason for the cancellation.

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

Create a shipment: Creates a shipment and provides shipment information.

With this endpoint, it is possible to ship one or multiple order items for a specific customer order. There are two ways to do this:

Get shipment list: Returns a list of shipments.

This endpoint is used to get 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 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 – among 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.

Get a shipment by shipment id: 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. In compliance with GDPR, we omit the transport information from the response when the transport is more than a year old.

Add transport information by transport id: Adds transport information to a shipment.

It is possible that you already want to ship an order item, but you don’t know the track and trace details at that moment in time. When this occurs, 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 code. From that moment on, the customer will also receive updates on events when this track and trace code is scanned.

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

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.