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:

shipping label flow

Step 1. Implement the get delivery options endpoint

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 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.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 handoverDetails element you will find in the response.

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.

Associated with each shipping label, you will find a shipping label offer identifier. Each shipping label offer is tied to (a set of) order item(s). When requesting a shipping label, be aware that you need this shipping label offer ID. Since this number can vary over time, make sure to store it since it is needed in Step 2.

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.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.

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.

Example 1. HEAD shipping label request and response

Request:

HEAD [ENVIRONMENT]/shipping-labels/50ca0ee6-3c44-4680-b97f-0f6d41cb3385

Response headers:

X-Track-And-Trace-Code: 3SBLCQ438474942
X-Transporter-Code: TNT

Step 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.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.

Using a purchased label from bol.com

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 shippingLabelId. * Or, providing the order item IDs and the transporterCode and 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.

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.com, 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 Update transports 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.com and non-Verzenden via bol.com items in one order

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.