Shipping labels

Introduction

In the Retailer API version 4 we introduced a new way of requesting shipping labels at bol.com. This new 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.

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 have a specific delivery date. Select carefully which label you want to use to prevent negative consequences on your performance score.

Were no labels provided in the delivery options?

If the delivery options do not yield a shipping label, this might be due to one of the following reasons:

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

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.

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 will get back 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 for which you requested the label.

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 providing a set of order item IDs and a shippingLabelId, which you received upon requesting a shipping label in Step 3. 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.

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

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.