API v3 – Orders and shipments

Orders and shipments are one of the most commonly used parts of the bol.com API. The ability to process orders through your own running software or e-commerce platform offers many benefits. This page covers the following scenarios:

  • Retrieving orders
  • Shipping order items
  • Cancelling order items
  • Retrieving shipments
  • Updating a transport of a shipment

On this page, the flow for retrieving orders, handling orders and updating a transport is described.

 

Endpoint overview

The following endpoints are all considered part of the order flow.

 

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

Logical process flow

1. Get 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 (in case you are participating in Logistics via bol.com) and FBR orders. In the response, you will find – amongst other attributes – the orderId and order items. This orderId can be used to retrieve the order details.

 

2. Get an order by order id

With the orderId from the ‘get open orders’ endpoint, you can here fetch all the order details for this specific orderId. In the response, you will find shipment details (that give data that can be used for your shipment), billing details (that gives you data can be used to make up the invoice).

Next to that, you will find all the order items that are part of the order. This can be only 1 (in case the customer orders only 1 item), or more in case the customer orders 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.

 

2a. Ship order item

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. By using your own shipping label
  2. By purchasing a shipping label from bol.com using the ‘get purchasable shipping labels’ endpoint.

1. Using your own shipping label

In case 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 need to leave the shippingLabelCode empty. It is not possible to either submit transport information as well as a shipping label code.

2. 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’) to the response. In that case, it is not allowed to provide also transport information.

 

2b. Cancel an order item

In case you cannot fulfill an order item to the customer, you have the possibility to cancel this order item from the order. There are two scenarios that can occur when cancelling an order item:

  1. The customer already requested a cancellation. You can find this by looking at the cancelRequest field from the order details. If this is set to true, the customer initiated the cancellation. In that case, this endpoint confirms the cancellation (you can use the reasonCode REQUESTED_BY_CUSTOMER for this) and you will not receive a negative score on your performance. Also, there is no need to ship this orderItem and bol.com will refund the customers automatically.
  2. The customer never requested a cancellation. In that case, you are cancelling an order item that was unexpected from the customer side. You are thereby disappointing the customer and this will lead to a negative score on your CANCELLATIONS performance indicator. Also, using the reason REQUESTED_BY_CUSTOMER without a customer cancellation request will count negatively as well. You can find your scores through the ‘Get performance indicators’ endpoint. Bol.com will manage the refund towards the customer.

 

3. Get shipment list

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 (in case 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, that can be used to add transport information in case you didn’t do so while shipping the order item.

 

Notes:

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

 

3a. Get a single shipment by shipment id

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.

 

Notes:

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

 

3b. Add transport information by transport id

Sometimes it can happen that you already want to ship an order item, but you don’t know the track and trace 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. From that moment onward, 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. Do note that with this endpoint, you can only append data. 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 optionally in your flow when shipping an order item.

 

Appendix A – Transporters

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.

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

Transporter / service API transporter code
Briefpost BRIEFPOST
UPS UPS
PostNL TNT
PostNL extra@home TNT-EXTRA
PostNL Briefpost TNT_BRIEF
TNT Express TNT-EXPRESS
Dynalogic DYL
DPD Nederland DPD-NL
DPD België DPD-BE
Bpost België BPOST_BE
Bpost Briefpost BPOST_BRIEF
DHLFORYOU DHLFORYOU
GLS GLS
FedEx Nederland FEDEX_NL
FedEx Belgie FEDEX_BE
Anders OTHER
DHL DHL
DHL Germany DHL_DE
DHL Global mail DHL-GLOBAL-MAIL
Transportservice Nederland TSN
Fiege FIEGE
TransMission TRANSMISSION
Parcel.nl PARCEL-NL
LogoiX LOGOIX
Packs PACKS
Bezorgafspraak COURIER
NedWRK (Red je pakketje) RJP

 

 

 

 

bol.com Development Center