Best practices - order process
This topic provides some recommendations for using the Orders API.
The API provides an order list that gives you very fast but limited information on the orders that are still open and waiting to be handled. It shows the
OrderID and the
OrderItemIds in the order. This endpoint was designed to give you a fast and clean view on your current orders that you can check often without the need to import large amounts of data.
We recommend polling this list every 5-15 minutes to determine if a new order has been placed by a customer. This endpoint is optimized to be polled often.
Once you are ready to pick, pack and ship the product, then use the orderId to fetch the order-details using the Get an open order by order ID endpoint.
This will give you the customer details you need to ship the physical product. This endpoint is not optimized to be polled often which is reflected in the limited Rate limits. We recommend to only use this endpoint once for getting the order details and do not poll it more often. The order details are static.
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.
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.|
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
transportpart from the request.
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.
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 we do not store orders and shipments indefinitely. We also remove customer information from the API after a period of time due to privacy concerns.
We recommend 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.com API as your archive and to provide you with historical data on shipments or orders.