New shipping label flow, including Verzenden via Bol.com (VvB)

If you are here because you are interested in participating in the Verzenden via Bol.com (VvB) service, be advised that you need to register yourself first. You can find more info on this process at our partner platform.

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 VvB or using regular shipping labels. In order to make the new flow work for you, some steps are required first, depending on whether you are participating in VvB or not. Below you will find a short summary of the required changes.

If you are interested in the new shipping label flow but not participating in VvB, the following changes are required:

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.

Are you participating in Verzenden via Bol.com?

If you are participating in VvB, you will also find the handoverDetails element in the response. The fields within this element provide you with information regarding how and when you need to deliver your item at the transporter.

  • ultimateHandoverDateTime indicates the final date and time at which the item must be handed over to the transporter. Failing to meet this date and time will result in a penalty (strike), as the promised delivery date towards the customer will no longer be be met, resulting in an unsatisfied customer. In that case, you are still able to purchase the label but it will be delivered later. The time linked to a delivery option differs per region.

    • Note: Always verify the opening hours of your drop-off point, as your drop-off point might close earlier.

  • collectionMethod indicates whether you need to drop off this item at the transporter (DROP_OFF), or whether the items are picked up at your address (PICK_UP).

If you provide two or more order items that have a different ultimateHandoverDateTime, the ultimateHandoverDateTime will be empty in the result set. You are still able to purchase the label for these order items, but one or more items will not be delivered at the time explicitly requested by the customer. This will count negatively on your performance score.

It is possible for a customer to order an item and explicitly request it to be delivered on a date, for example Monday; however on that Monday no mailbox items are scheduled to be delivered. If the ordered item fits within an envelope you might consider using an envelope for this shipment. As a result, your envelope will be delivered on a Tuesday, failing to meet the agreed delivery date with the customer. Be advised to use a correct label in this scenario.

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.

  • The combined set of order items cannot be shipped using the same box/label, as one of the order items will consequently be delivered too early or late.

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.

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

Step 2. Implement the create a shipping label endpoint

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.

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

The process of receiving the shipping label ID follows our regular asynchronous processing flow. For more information, see this page: 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.

Step 3. Implement the get a shipping label endpoint

This step will return back your shipping label file, based on your shippingLabelId. You will receive 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. Update or implement the ship order item endpoint

Be advised that 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 can create 1 shipment for more than 1 order item. The same logic will apply for the cancel order item endpoint. You should begin preparing for this change.

This step allows you to register your shipment at bol.com. You can provide a set of order items 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 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, it is not allowed to provide transport details under the transport element. We will fill in these details for you based on the provided shippingLabelId.

Using your own purchased or generated label

This is only permitted if you are not using VvB.

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.

Step 5. Update your offer details

Be advised that all the following steps are only required when you are participating in VvB.

Each offer that you want to mark for sale through VvB requires that you add an indication to it. You can do this by setting the deliveryCode of the offer to VVB. Be advised that this delivery code is only allowed in combination when the method under the fulfilment element is set to FBR.

Setting the method to VVB applies to the create offer and update offer endpoints. You will also return the VVB code under the get offer endpoint and in our offer export file. You can find more details and code examples on our technical documentation page.

Step 6. Update your order details

When receiving your order details, a new field has been introduced that indicates whether this item requires shipment through bol.com or by yourself. The distributionParty field under the orderItems.fulfilment element has two possible values:

  • RETAILER indicates that this order requires shipment by you as the retailer

  • BOL indicates that this order must be shipped through bol.com in VvB.

Step 7. Update your shipment details

When receiving your shipment details, the same new field has been introduced to indicate whether this item was shipped through bol.com or by yourself. The distributionParty field under the shipmentItems.fulfilment element has the same two possible values as you will find in the order details:

  • RETAILER indicates that this order requires shipment by you as the retailer

  • BOL indicates that this order must be shipped through bol.com in VvB.