Orders and shipments
Shipments API endpoints
Depending on your usage, the Get delivery options endpoint might also apply to your process if you are purchasing labels from bol.com.
Get open orders
Get orders: can be used to return a list of open orders.
This endpoint is used to get 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 order items.
This orderId
can be used to get the order details in the get a single order.
FBB Orders – best practice
While this endpoint allows you to list both FBR and FBB orders, FBB orders will be handled by bol.com, meaning that once bol.com handles the open order, it is closed and listed as a shipment. Shipments for FBB are also available through the shipment endpoints.
We try to pick orders as soon as possible; often an order is already picked before you poll the get orders endpoint.
As a result you will no longer see the order in the open orders list and you can use shipments to track it.
However, if you are using FBB and you wish to see the original order, you can use status=ALL
.
See below for more information.
Get orders with all statuses
In Get orders, orders can be filtered by a status
:
-
OPEN
: provides only the items within the order that still need to be fulfilled (or cancelled). -
ALL
: in addition to all open items, also provides all the items within the order that were shipped or cancelled within the last 48 hours.
This provides you with a much more detailed snapshot of your entire orders portfolio, allowing you to track the progress of orders and respond to issues in a shorter timeframe.
Shipped items
When an order moves to status Shipped, it will remain visible in status=ALL
for the next 48 hours, and at the same time it will also become visible in Get shipments and Get shipment.
Cancelled items
From the time an order is cancelled, it remains visible in status=ALL
for the next 48 hours.
The time of cancellation depends on the cancellation reason.
For example if the customer requests a delivery date of 10/01, and the partner has committed to a 24h window of delivery, the order will automatically be cancelled by bol.com on 13/01, and will remain visible in status=ALL
until 15/01.
The query parameter status=ALL can be used for both FBB and FBR (Fulfillment By Retailer); however the data is primarily intended to be used for FBB.
|
Additionally, the response for Get order includes the fields quantityCancelled
and quantityShipped
on each order line.
Because the data from a request with query parameter |
Get a single order
Get a single order: returns a single order.
With the orderId
from the Get orders endpoint, you can use this endpoint to fetch all the order details for this specific orderId
.
In the response, you will find shipment details giving data that can be used for your shipment, and billing details giving data can be used to make up an invoice.
Next to that, you will find all the order items that are part of the order.
This can either be 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, and are referred to as the orderItemId
.
With this ID, you can either choose to ship this order item or to cancel this specific order item.
The Get a single order request was also changed in v5 to filter by default on status=ALL .
Previously it only returned open items in an order, but it now returns all open items as well as all items that were shipped or cancelled within the last 48 hours.
Besides quantity ordered the response includes the fields quantityCancelled and quantityShipped . See Get orders with all statuses for more information.
|
Ship order item
Ship order item: is used to 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:
-
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 atrackAndTraceCode
. Note that thetrackAndTraceCode
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
shippingLabelId
empty. It is not possible to submit transport information and also ashippingLabelId
. -
Shipping using a purchased shipping label from bol.com. If you purchased a shipping label from bol.com, you need to add the
shippingLabelId
which you obtained from get delivery options to the response. In this case, you need to omit the transport information.
Cancel order item
Cancel order item: is used to cancel an order item and provide a reason for the cancellation.
There are two scenarios that can occur regarding cancelling an order item:
-
The customer requested a cancellation.
When retrieving a Get 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.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.
The time between retrieving an open order and actually shipping an order item or cancelling 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 get the open order again just before shipping the order item to check for a possible cancellation request from the customer. |
-
If you cannot ship an order item to the customer, for example due to missing stock, it is possible to cancel an order item from the order yourself.
The customer never requested a cancellation in this scenario, and by cancelling the order item you unfortunately disappoint the customer. Cancelling 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 also count negatively.You can find your scores through the Performance indicators endpoint. Bol.com will manage the refund towards the customer when cancelling an order item yourself.
Get shipments
Get shipments: 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.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 – 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 single shipment 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. |
Get a single shipment
Get a single shipment: 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.
With the specific |
Add transport information to a shipment
Add transport information: is used to add 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.
This endpoint only allows you to append data.It is therefore not possible to change the transporter itself, but you are allowed to add data. |
You are not required to use this endpoint if you provide us directly with the track and trace code, and the transporter information when shipping an order item. For that reason, this step is optional in your flow when shipping an order item. |
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.
Some transporters use a DASH while others use an UNDERSCORE. Please make sure to use the correct one. |
Transporter / service | API transporter code |
---|---|
Briefpost |
|
UPS |
|
PostNL |
|
PostNL extra@home |
|
PostNL Briefpost |
|
TNT Express |
|
Dynalogic |
|
DPD Nederland |
|
DPD België |
|
Bpost België |
|
Bpost Briefpost |
|
DHLFORYOU |
|
GLS |
|
FedEx Nederland |
|
FedEx Belgie |
|
Anders |
|
DHL |
|
DHL Germany |
|
DHL Global mail |
|
Transportservice Nederland |
|
Fiege |
|
TransMission |
|
Parcel.nl |
|
LogoiX |
|
Packs |
|
Bezorgafspraak |
|
NedWRK (Red je pakketje) |
|