Best practices - order process

This topic provides some recommendations for using the Orders API.

Access the order list often to stay up-to-date

The Orders API provides an order list that provides you information about:

Orders that are open and waiting to be handled.
Orders that are handled (shipped or cancelled) within the last 48 hours.

This endpoint is designed to provide you an overview of your current orders without the need to import large amounts of data.

The most efficient way to access new and changed orders within a given timeframe is by using the change-interval-minute parameter in the Get a list of orders endpoint. This parameter establishes a more efficient way of working by reducing redundancy. It provides you with only those new or existing orders that have changed since the last time the Get a list of orders endpoint was polled.

To optimise the usage of this endpoint, it is recommended that you poll the order list every 5-15 minutes to check if a new order has been placed by a customer.

For more information about the change-interval-minute parameter, see Retrieving new or changed orders only.

API endpoint: https://api.bol.com/retailer/orders

Key consideration for FBB orders

While the Get a list of orders endpoint allows you to list both FBR and FBB orders, note that all the FBB orders will be handled by bol. This means that once bol handles an open order, it is closed and listed as a shipment. Shipments for FBB orders are also managed through the Shipments endpoints.

The orders are picked up by bol as soon as possible. Sometimes, an order is already picked before you poll the Get a list of orders endpoint.

As a result you will no longer see the order in the open orders list because the order was already handled.

In case you are using FBB as your fulfilment method, assign any one of the following values to the status parameter in the request body to view your handled FBB orders:

ALL
SHIPPED

Use the order details only once to ship

Once you are ready to pick, pack and ship the product, use the orderId to fetch the order details using the Get an order by order id endpoint.

It will provide you all the customer details you need to ship the physical product. This endpoint is not optimized to be polled often as reflected in the Rate limits. It is recommended that you use this endpoint only once for retrieving the order details.

Establish a process for handling cancellation requests by customers

Since bol offers customers the ability to cancel order items after placing an order, partners are requested to establish processes that can handle the cancellation requests. Cancellation requests for order items can be found in:

For more information about these endpoints, see Get a list of orders and Get an order by order id respectively.

Unhandled cancellation requests will result in unhappy customers and unnecessary shipments and returns.

Ship all order-items

An order can consist of one or more order-items. All mutations in the API are always based on the order-item. This means you ship or cancel every order-item separately using its orderItemId. Of course, you can physically ship them in one box if possible, but the API needs a separate confirmation/cancellation. The order will remain open as long as not all order-items are handled but will also appear in the shipment list for the parts that you have already sent.

Always check if your shipment was successful

When using https://api.bol.com/retailer/orders/<order-item-id>/shipment to send us the confirmation of your shipment, make sure to always check if it was processed successfully. If it was not processed successfully you will need to fix the issue and send us a new shipment. If we do not receive a successful shipment, the order will expire and be cancelled and you will not receive payment for the order, regardless of whether you physically shipped it.

The worst-case scenario here is that your customer receives the product, but you will not be paid because we did not receive a successful confirmation of your shipment. You can prevent this by always checking the process status of your shipment request using the Process status endpoint.

Use the Transport endpoint if you need to ship before you have a Track & Trace code

You are required to supply a Track & Trace code for every shipment. However we understand that sometimes you have no access to your carrier’s information until the end of the day, while you already processed the products for shipment and need to confirm this with us.

It is possible to first confirm the handling of your shipment and add your Track & Trace information later on the same day:

Use the Shipment endpoint https://api.bol.com/retailer/orders/<order-item-id>/shipment to confirm your shipment.

Make sure to remove the entire Transport part from the request:
```
{

  "shipmentReference": "B321SR",

  "transport": {

    "transporterCode": "TNT",

    "trackAndTrace": "3SBOL0987654321"
  }

}
```

When you do receive the transport information from your carrier on the same day, use the Transport endpoint https://api.bol.com/retailer/transports/<transport-id> to add this information to your existing shipment.

You can only add transport information once. This endpoint only adds information, it does not do any updates. You can either supply the code in the original shipment request, or add it later through the Transport endpoint.

We do not recommend using the Transport endpoint due to the fact that it results in a worse customer experience. The shipment request with a Track & Trace code will trigger an email to the customer. If this does not have the code, they will not receive the mail, and adding it later through Transport will also not trigger an email. The Transport endpoint should only be used as a last resort.

Do not use bol as an archive

Both the order and shipment lists in the API are optimized to provide you with fast and reliable information to quickly handle your sales process.

Due to legal, privacy and load-managing reasons orders and shipments are not stored indefinitely. Due to privacy reasons, the customer information from the API is also removed after a period of time.

It is recommended that you import the data you need from our API into your own systems and handle them according to local law and privacy guidelines. Do not rely on the bol API as your archive and to provide you with historical data on shipments or orders.

For your reference, an overview of the timelines is provided below:

All open order items remain visible indefinitely in the Get a list of orders and Get an order by order id endpoints.
After an order item is shipped or canceled it remains visible in the Get a list of orders endpoint for 48 hours and in the Get an order by order id endpoint for three months.
In case of incident management, for example when orders were missed for a period of time because of an outage, use the latest-change-date parameter from the Get a list of orders endpoint to access the shipped and cancelled order items that were last changed on a given date for up to three months in the past.