The shipping label flow within the API will support you in purchasing shipping labels for either regular shipping labels or Verzenden via bol. Below you will find a short summary of the steps required to implement the new shipping label flow:
Please refer to Verzenden via bol.com for more information and the additional steps required when using this service.
This step helps you to determine your delivery options for a set of order items. It provides you with different shipping labels, which have their own associated
The available shipping labels returned are differentiated based on the order and/or offer criteria. For example a condition of NEW or SECOND_HAND on the offer will only show a shipping label that corresponds to this condition. A similar logic applies for the type of labels you receive; for example for an address in Belgium you will only get back labels that are suitable for a shipment to Belgium.
Each label has its own package restrictions and you are responsible for using the right label for the right shipment. In case you fail to meet those restrictions or ignore them, a financial penalty will apply that will be deducted from your monthly invoice.
If an order contains only 1 order item, you can find the applicable labels for that order item, taking into account the variables of the order; for example its delivery date or type of item.
If an order contains more than 1 order item, you can provide all the order items in the delivery options endpoint. You will get back the applicable labels for this combination of order items.
If you provide an order item that applies to a FbB (Fulfilment by Bol.com / Logistiek via Bol.com) order, you will not receive any delivery options.
If the provided order items belong to a different order, you will not receive any delivery options.
If the delivery options do not yield a shipping label, this might be because the combined set of order items is not permitted to be shipped using the same label. Try using a different set of order items or splitting the items over different shipping labels.
|Bol.com automatically filters out non-applicable labels for cross-border shipments. When you are located in the Netherlands and your customer is located in Belgium you will only receive labels that allow for shipment from the Netherlands to Belgium.|
Please refer to Verzenden via bol.com if you are participating in the program, to manage the additional
All orders for Verzenden via bol.com have a specific delivery date. Select carefully which label you want to use to prevent negative consequences on your performance score.
For non-Verzenden via bol.com labels, bol.com differentiates the shipping label price based on the condition of the item, for example SECOND_HAND or NEW. You will only receive labels that apply to the condition of the item. If multiple order items have different conditions and end up in the same shipment, you are allowed to use the cheapest shipping label for that shipment when the delivery promise to the customer is still met. This does not apply to Verzenden via bol.com labels.
With each shipping label you will find a shipping label offer identifier. Each shipping label offer is tied to a set of order items. When requesting a shipping label, be aware that you need this shipping label offer ID. Note that this number can vary over time; therefore always make sure to store it since you will need this number in Step 2.
When you request your shipping label, you need to provide (a set of) order item(s) in conjunction with the shipping label offer ID you received from Step 1. Both fields are required and will make sure the shipping label, based on the shipping label offer identifier, is tied to (a set of) order item(s).
This step enables you to request a shipping label from bol.com. With this request, you need to provide a set of order items in conjunction with the
shippingLabelOfferId you received from Step 1. Both fields are required and will make sure that the shipping label - based on the shipping label offer identifier - is tied to a set of order items.
|It is not possible to purchase more than 1 shipping label for 1 order item. You can only purchase 1 shipping label per order item. If there are 2 order items within 1 order, for example, you can purchase 2 shipping labels.|
With the shipping label identifier, you can request the actual shipping label in Step 3.
The process of receiving the shipping label ID follows our regular asynchronous processing flow. For more information, see process status flow. When the process successfully completes, you will receive a shipping label identifier, with which you can request the actual shipping label through Step 3.
When you have received the shipping label identifier, you can request the actual shipping label in Step 3.
The get shipping label endpoint will return back your shipping label file, based on your shipping label identifier. This will be a PDF file that contains the shipping label itself. You can directly send this file to your printer and put it on the parcel. Be advised that you use this shipping label for the same set of items that you requested the label for.
If you only want to get the Track and Trace code and Transporter code we advise you to use a HTTP HEAD request, which is processed as if it were an HTTP GET request except instead of writing the body it only returns the headers from which you can extract the information, making it much faster.
If you do want to obtain the PDF file containing the label you can do a GET request which also allows you to extract the Track and Trace code and Transporter code for the headers.
X-Track-And-Trace-Code: 3SBLCQ438474942 X-Transporter-Code: TNT
|At this moment the collection of order item IDs is temporarily limited to only 1 order item. In the near future, we plan on removing this validation so that you create 1 shipment for more than 1 order item.|
To register shipments at bol.com, you can provide a (set of) order item(s) in this endpoint along with an optional reference field. There are multiple ways to register a shipment, depending on your own process for sending parcels to your customers.
You can ship an order item by either:
* Providing a set of order item IDs and a
shippingLabelId. When you provide a
shippingLabelId, this means you indicate that you purchased a label at bol.com. In that case, you are not permitted to provide transport details under the transport element. We will fill in these details for you based on the provided
* Or, providing the order item IDs and the
trackAndTrace codes which you received upon requesting a shipping label in Step 3.
|Payment for a shipping label will only happen when you submit the Order and include the shippingLabelId.|
|This is only permitted if you are not using Verzenden via bol.|
If you are not purchasing a label at bol.com, you need to provide your own transport details by filling in the
trackAndTrace fields. If you fill in the transporter element, you are indicating that you use your own purchased / generated label. In that case, you are not allowed to provide a
shippingLabelId at the same time. You are allowed to leave the transport element empty and send us a shipment without a
trackAndTrace. If you plan on leaving them empty, the customer will receive a shipment confirmation without a track and trace code, which makes it difficult to predict when the package is arriving. Therefore we monitor the track and trace fill rate and whether your shipment has arrived on time at the customer. Leaving these fields empty can therefore count negatively on your performance score.
|You can update the transporter later via the Update transports endpoint. The customer will still not be notified of the Track & Trace code, but your performance score will not be negatively affected.|
If you have a single order that contains a combination of Verzenden via bol.com and non-Verzenden via bol.com order items and can fit into one box, you can send them with one shipping label to the customer. You can do this by shipping the Verzenden via bol.com items in the normal way and then using the same Track & Trace code to ship your non-Verzenden via bol.com order items. You cannot combine multiple customer orders into one shipment.