Shipping Labels
Introduction
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:
-
Step 4. Register shipment of this order item
Please refer to Verzenden via bol for more information and the additional steps required when using this service.
Step 1. Get the list of shipping labels
This step helps you to choose your method of delivery for a set of order items. It provides you with different shipping labels, which have their own associated labelPrice, validUntilDate, and packageRestrictions.
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.
Delivery option usage
-
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 / Logistiek via bol) 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 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 if you are participating in the program, to manage the additional handoverDetails element you will find in the response.
|
|
All orders for Verzenden via bol 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 labels, bol 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 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.
Recommended shipping labels
The recommended field in deliveryOptions is a boolean that indicates which of the possible shipping labels is recommended by bol. Only one of the labels will be true, and you can choose to either ignore or use the suggestion.
The recommendation is based on the workdays and times of the partner as known by bol. The label which we suggest is only based on the specific moment it is requested, and may change during the day.
|
An item that may fit in a mailbox can still be categorized as a 'parcel' and will receive parcel shipping label as the recommended label even though it would be less expensive to send it directly to the mailbox. This could be due to incorrect or incomplete dimensions. Products that are wrongly reported as having too large dimensions or without any dimensions at all are labeled as parcels. To fix this, use a 'mailbox' shipping label that was not recommended. Sometimes, customers choose certain last mile options such as evening deliveries and pickup points, that are only applicable to parcel shipping labels. An order that has either evening or pickup points option cannot be changed to mailbox shipping label. You will therefore need to ship it as a parcel, which will increase the shipping cost. Hence, it is recommended to keep the product dimensions up-to-date on the system using the Create content for a product endpoint. For more information on this endpoint, see the functional documentation for Product Content. Alternatively, you can adjust the dimensions using the Seller Dashboard, which will allow us to recommend the correct label in the future. |
Step 2. Request a shipping label
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. 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.
Shipping label creation failure
If you receive a process status failure when creating a shipping label, you can examine the errorMessage field in the response to identify why the creation failed. If the failure was due to capacity restrictions, the errorMessage will also provide a date and time as of when you can try to create the shipping label again. For more information click here.
Step 3. Implement the get shipping label endpoint
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.
Request:
HEAD [ENVIRONMENT]/shipping-labels/50ca0ee6-3c44-4680-b97f-0f6d41cb3385Response headers:
X-Track-And-Trace-Code: 3SBLCQ438474942
X-Transporter-Code: TNTStep 4. Register shipment of this order item
| 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, 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.
Using a purchased label from bol
You can ship an order item by either:
-
Providing a set of order item IDs and a
shippingLabelId. When you provide ashippingLabelId, this means you indicate that you purchased a label at bol. 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 providedshippingLabelId. -
Or, providing the order item IDs and the
transporterCodeandtrackAndTracecodes 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. |
Using your own purchased or generated label
| This is only permitted if you are not using Verzenden via bol. |
If you are not purchasing a label at bol, you need to provide your own transport details by filling in the transporterCode and 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 transporterCode and 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 Add transport information by transport id endpoint. The customer will still not be notified of the Track & Trace code, but your performance score will not be negatively affected. |
Combining Verzenden via bol and non-Verzenden via bol items in one order
If you have a single order that contains a combination of Verzenden via bol and non-Verzenden via bol 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 items in the normal way and then using the same Track & Trace code to ship your non-Verzenden via bol order items. You cannot combine multiple customer orders into one shipment.