New shipping label flow

Introduction

With the API version 4 we introduce a new way of requesting shipping labels at bol.com. This new flow within the API will support you in purchasing shipping labels for the following flows:

Way of working

The new shipping label flow will consist out of 4 steps:

  1. Request your delivery options for this (set of) order item(s)
  2. Request a shipping label for this (set of) order item(s)
  3. Request the shipping label file (currently only available in PDF format)
  4. Register the shipment of this order item at bol.com

High-level overview shipping label flow

Step 1: Request your delivery options


Step 1 helps you in determining your delivery options for this (set of) order item(s). It provides you with different shipping labels, which have their own associated price and package restrictions. Be aware that not every shipping label can be used for each order item. This is dependent on the data related to the order / offer. An example can be found for the condition of the order item. When creating the offer, you can set the condition to NEW or SECOND_HAND. In that case SECOND_HAND order items can only be shipped with a shipping label linked to this condition. Also take notice of the package restrictions linked to each label. You are responsible for using the right label for the right packages. In case you fail to meet those restrictions or ignore them, a (financial) penalty will apply.

Usage

  • In case an order contains only 1 order item, you can find the applicable labels for that order item
  • In case 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
  • In case 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

No labels provided in the delivery options?
In case the delivery-options do not yield a shipping label, this might have one of the following reasons:

  • The combination of set of order items is not allowed to be shipped using the same label. Try a different set of order items or split the items over different shipping labels.

Other applicable rules

  • bol.com automatically filters out non applicable labels in case of cross border shipments. When you are located in the Netherlands and your customer is located in Belgium you will only receive labels that allows for shipment from the Netherlands to Belgium.
  • bol.com differentiate the shipping label price based on the condition of the item (i.e. SECOND_HAND or NEW). You will only receive labels that apply to the condition of the item. In case 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.
  • Only business sellers can use this functionality.

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. As this number can vary over time, make sure you store it at your side as you need this number in step 2.

Step 2: Request a shipping label

Step 2 is available to request a shipping label from bol.com. With this request, 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).

When requesting a shipping label, we will validate whether this shipping label offer that you provide is allowed with the (set of) order item(s) you provide. In case the provided combination of order item(s) and shipping label offer are valid, you will receive back a shipping label identifier. Be aware that you need to store this shipping label identifier because you need it later (e.g. when registering your shipment to us or when you want to retrieve your shipping label file). In case the provided combination is not valid, you will get back an error.

With the received shipping label identifier, you can request the actual shipping label through step 3.

Step 3: Request a shipping label file

Step 3 will return back your shipping label file, based on your shipping label identifier. At this moment, 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 that you requested the label for.

Step 4: Register shipment of this order item

Note: be advised that at this moment the collection of order item id’s 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.

Step 4 allows you to register your shipment 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 to send parcels towards the customer.

  • Using a purchased label from bol.com

You can ship an order item by providing a (set of) order item id(s) and a shippingLabelId, which you received upon requesting a shipping label. When you provide a shippingLabelId, this means you indicate you purchased a label at bol.com (through steps 1, 2 and 3). In that case, there is no need to provide additional transport details under the transport element. Instead we will do it for you.

  • Using your own (purchased / generated) label

In case 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 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. Be aware that this is not the optimal flow and we will monitor your track and track filtrate and whether your shipment has arrived on time at the customer. Leaving these fields empty can therefore count negatively on your performance score.