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.
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 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, meaning that once bol 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.
Because the data from a request with query parameter status=ALL
represents a snapshot from a point in an order lifecycle, it is possible that you will see some anomalies on very rare occasions ( under 0.0001%) that appear to be incorrect, but are actually a result of status changes that create an error when compared with older snapshots.
You should generally treat the latest snapshot as the more accurate data set.
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 on 13/01, and will remain visible in status=ALL
until 15/01.
Get an order by order id
Get an order by order id: Allows you to retrieve all the specific details of an order using the orderId
.
This endpoint gives you the following details about an order in its response body:
-
Order identifier - The items within the order are known as order items, and the `orderItemId`corresponds to each order item in a particular order . You can use this Id to perform specific tasks such as shipping or cancelling an order item within an order.
-
Order items in 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 order. The total price of an order item is calculated by multiplying the
unitPrice
withquantity
.It includes details of the amount of products ordered, shipped products and cancelled products for a particular order item Id. Additionally, it offers the details related to products, fulfilment, offers and commisions. For more information on
orderItems
, see Orders Redoc. -
Pick up point details (if applicable for an order).
-
Date and time of placing the order.
-
Billing and shipping details.
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
.
The retailer must erase all the customer data from their own database if the customer chooses to conceal their information. The`Salutation` field returns the value UNKNOWN when the customer has not provided information about their gender. The email field returns no value after 61 days of placing the order. The billing information is not exposed to the retailer if the order has been created one month ago.
|
By default, a single order request returns all items in the order, including the following fulfilment methods:
-
Fulfilment by bol (FBB)
-
Fulfilment by retailer (FBR)
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
.
The Get an order by order id request filters by default on status=ALL
. It returns all open items as well as all items that were shipped or cancelled within the last 48 hours.
For more information, see Get orders with all statuses .
Shipment time frame
The timeFrameType
field in Get order indicates which delivery time option was selected by the customer during the checkout. The possible values are:
Value | Delivery type | Remarks |
---|---|---|
|
All delivery types |
This is the default value for FBR orders being delivered during the daytime. |
|
All delivery types |
This is the default value for FBR orders being delivered during the evening. |
|
Logistics via bol. Currently not available for FBR orders. |
Delivery option for oversized or overweighted orders for which the standard delivery option is not possible. This requires the customer to agree on a timeslot for the appointment. |
|
Logistics via bol |
Delivery option for orders to be delivered on the same day as the order is placed. |
|
Logistics via bol |
Delivery option for orders to be delivered on Sunday during the daytime. |
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 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. If you purchased a shipping label from bol, you can either:
-
Add the
shippingLabelId
which you obtained from get delivery options to the response. In this case, you need to omit the transport information. -
Or, use the fields in the response from Get shipping label in the
transport
object.
-
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 shipping labels on API v4 or above, or Verzenden via bol shipping labels, 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 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: 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 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 |
Monitoring a shipment
The transport.transportEvents
element in Get single shipment allows you to track the shipment events when they are updated in the system. Transport events will show the entire history of the shipment with timestamps. You can use Subscriptions to receive updates whenever a new transport event is added to a shipment.
For a multi-line order which is shipped with one Track and Trace code, you will see transport events for only one of the orderlines in the order, even though they apply to the whole order. This will be improved in the future. |
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 add the tracking information only when the trackAndTrace code is missing. It is recommended to not use this endpoint to update the transporterCode
or to update the current trackAndTrace code of a shipment.
|
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 notation. This list applies to the current version of the Retailer API and could change between versions. |
Transporter / service | API transporter code | URL template | URL language | Receiver country |
---|---|---|---|---|
Briefpost |
|
N/A |
N/A |
N/A |
UPS |
|
https://wwwapps.ups.com/tracking/tracking.cgi?tracknum={trackTraceCode} |
EN |
NL and BE |
PostNL |
|
https://postnl.nl/tracktrace/?B={trackTraceCode}&P={zipCode}&D=NL&T=C&L=NL |
NL |
NL |
PostNL |
|
https://postnl.nl/tracktrace/?B={trackTraceCode}&P={zipCode}&D=BE&T=C&L=NL |
NL |
BE |
PostNL |
|
https://postnl.nl/tracktrace/?B={trackTraceCode}&P={zipCode}&D=BE&T=C&L=FR |
FR |
BE |
PostNL extra@home |
|
https://postnl.nl/tracktrace/?B={trackTraceCode}&P={zipCode}&D=NL&T=C&L=NL |
NL |
NL |
PostNL extra@home |
|
https://postnl.nl/tracktrace/?B={trackTraceCode}&P={zipCode}&D=BE&T=C&L=NL |
NL |
BE |
PostNL Briefpost Netherlands |
|
https://postnl.nl/tracktrace/?B={trackTraceCode}&P={zipCode}&D=NL&T=C&L=NL |
NL |
NL |
PostNL Briefpost Belgium |
|
https://postnl.nl/tracktrace/?B={trackTraceCode}&P={zipCode}&D=BE&T=C&L=NL |
NL |
BE |
TNT Express |
|
https://www.tnt.com/webtracker/tracking.do?navigation=1&searchType=CON&respLang=en&respCountry=GENERIC&genericSiteIdent=.&cons={trackTraceCode} |
EN |
NL and BE |
Dynalogic |
|
https://trackentrace.dynalogic.eu/?ordernumber={trackTraceCode}&zipcode={zipCode} |
EN |
NL and BE |
DPD Nederland |
|
https://tracking.dpd.de/parcelstatus?query={trackTraceCode}&locale=nl_BE |
NL |
BE |
DPD België |
|
https://tracking.dpd.de/parcelstatus?query={trackTraceCode}&locale=nl_BE |
NL |
NL and BE |
Bpost België Dutch Netherlands and Belgium |
|
https://track.bpost.cloud/btr/web/#/search?itemCode={trackTraceCode}&postalCode={zipCode}&lang=NL |
NL |
NL and BE |
Bpost België |
|
https://track.bpost.cloud/btr/web/#/search?itemCode={trackTraceCode}&postalCode={zipCode}&lang=FR |
FR |
BE |
Bpost Briefpost |
|
https://track.bpost.cloud/btr/web/#/search?itemCode={trackTraceCode}&postalCode={zipCode}&lang=NL |
NL |
NL and BE |
DHLFORYOU |
|
https://dhlparcel.nl/nl/particulier/ontvangen/volg-uw-zending?tt={trackTraceCode}&pc={zipCode} |
NL |
NL and BE |
GLS |
|
https://gls-group.eu/BE/vl/pakket-volgen?match={trackTraceCode} |
NL |
BE |
GLS |
|
https://www.gls-info.nl/Tracking?parcelno={trackTraceCode}&zipcode={zipCode} |
NL |
NL |
FedEx Nederland |
|
https://www.fedex.com/apps/fedextrack/?tracknumbers={trackTraceCode}&cntry_code=NL |
NL |
NL |
FedEx Belgie |
|
https://www.fedex.com/apps/fedextrack/?tracknumbers={trackTraceCode}&cntry_code=BE |
EN |
BE |
Anders |
|
N/A |
N/A |
N/A |
DHL |
|
https://dhlparcel.nl/nl/particulier/ontvangen/volg-uw-zending?tt={trackTraceCode}&pc={zipCode} |
NL |
NL and BE |
DHL Germany |
|
N/A |
N/A |
N/A |
DHL Global mail |
|
https://webtrack.dhlglobalmail.com/?trackingnumber={trackTraceCode} |
EN |
NL and BE |
DHL Global mail |
|
https://webtrack.dhlglobalmail.com/?trackingnumber={trackTraceCode}&locale=nl |
NL |
NL and BE |
Transportservice Nederlands |
|
N/A |
N/A |
N/A |
Fiege |
|
https://nolp.dhl.de/nextt-online-public/set_identcodes.do?lang=nl&idc={trackTraceCode} |
NL |
NL and BE |
TransMission |
|
https://www.mijnzending.nl/portal/index.php?view=tt/vAnoniem&zendingnummer={trackTraceCode}&postcode={zipCode}` |
NL |
NL and BE |
Parcel.nl |
|
https://www.dpost.be/Parceltracking/tracking/trackingnumber/{trackTraceCode} |
NL |
NL and BE |
LogoiX |
|
N/A |
N/A |
N/A |
Packs |
|
https://www.packs.nl/tracktrace/?zendingnr={trackTraceCode}&pc6hnr={zipCode} |
NL |
NL and BE |
Bezorgafspraak |
|
N/A |
N/A |
N/A |
Parts Express |
|
https://tnt.partsexpress.nl/#/orderdetail/{trackTraceCode}/{zipCode} |
NL |
NL |
Amperé and BUDBEE |
|
https://tracking.budbee.com/{UniqueHashId}auth={UniqueHash} |
NL |
NL |
Trunkrs |
|
https://parcel.trunkrs.nl/{trackTraceCode}/{zipcode} |
EN |
NL and BE |
Cycloon |
|
https://www.cycloon.eu/trackandtrace/{trackTraceCode} |
NL |
NL |