Beta v3 – Offers

Please note that this documentation describes the beta version of our Retailer API version 3. This page is intended only for use by the partners participating in our beta testing program.

Endpoints can still be subject to change and support is limited in the beta phase.

 

Offers

Offers are the backbone of any partner’s ability to use the bol.com platform. Without an offer it’s impossible to sell an article, as we need to know price, stock level, delivery promise and fulfilment method.

The following endpoints are available to help synchronize your offers with bol.com:

 

Create Single Offer

Our Retailer API uses an OfferID to identify and update an offer. You can use the POST Request to create an offer, after which we will return a process-status including the corresponding OfferID we have assigned. Creating a new offer only happens once and cannot be used to update an offer.

The OfferID that you receive when posting a ‘create offer’, is needed for the get, update and delete requests.

 

Offer list

The Offer List request is currently being developed, and will be delivered before the final go live. During the beta test phase, a workaround is available. If you are participating in the beta test program, please contact your technical contact for more info.

The Offer list request can be used to retrieve the OfferID’s of all your offers.

 

Update single offer

Allows you to update deliveryCode,  publishing status, offer reference and fulfilmentMethod and referencecode.

 

Update offer stock

Solely updates the stock of the specified offer. Please see stock scenario’s below for more details.

 

Update offer price

Solely updates the price of the specified offer.

 

Delete offer

To delete an offer the Delete offer request is used. You can only use the OfferID to delete an offer.

 

The endpoint details can be found here.

 

Stock scenario’s

In our Retailer API, we recognize 2 stock elements in the Get Single Offer endpoint.

  • Seller Stock
  • Corrected Stock

When sending us a Stock value through the create or update requests you are sending us your current stock. When a customer orders 1 of your offers thereafter, we will reserve this offer to prevent it to be ordered by someone else.

When you then ship the order, the corrected stock remains the same. When you update your stock after shipping, the reservation is no longer taken into account.

The default behavior is as described in stock scenario 1. This behavior can cause double stock countdown when a retailer updates his stock (-1) before confirming the shipment.

At the request of a number of retailers, the possibility has been introduced for the retailer to override these corrections. To facilitate this, an addition has been made in the create, get, update and stock update endpoints. The boolean element ‘managedbyretailer’ has been added to the stock element.

The value is set to ‘false’  by default (as in stock scenario 1), but can be changed to ‘true’ by the retailer. When it is set to true, all stock events before the retailer’s stock update are not taken into account.

Functionally this means that when a retailer updates his stock with managedbyretailer = true, we forget about all open orders. Also, customer cancellations are not taken into account, and thus do not result in a higher corrected stock. Please see stock scenario 2 for more details.

Please note that cancellations by the retailer always result in a corrected stock being set to 0.

Please note that this functionality can only be used when exclusively using the API for stock management. If you do a stock update using the Seller Dashboard, the ‘managedbyretailer’ field is reset to false.

 

Stock scenario 1: managedByRetailer = false

event managedByRetailer seller stock corrected stock explanation
retailer updates stock (@10:00:00) false 10 10
reservation (orderid=1) on webshop (@10:10:00) false 10 9 corrected_stock -1
retailer updates stock (@11:00:00) false 9 8 open order (id = 1) taken into account (no shipment/cancellation)
customer cancellation (orderid=1) (@11:15:00) false 9 9 corrected_stock +1
reservation (orderid=2) on webshop (@11:20:00) false 9 8 corrected_stock -1
retailer updates stock (@11:30:00) false 2 1 cancelled order (id = 1) no longer taken into account

open order (id = 2) taken into account (no shipment/cancellation)

shipment (orderid = 2) (@11:40:00) false 2 1 shipping an order does not change the corrected stock
retailer updates stock (@11:50:00) false 1 1 cancelled order (id = 1) no longer taken into account

shipped order (id = 2) also no longer taken into account

shipped and cancelled orders are no longer taken into account once the retailer updates his stock

 

Stock scenario 2: managedByRetailer = true

event managedByRetailer seller stock corrected stock explanation
retailer updates stock (@10:00:00) true 10 10
reservation (orderid=1) on webshop (@10:10:00) true 10 9 corrected_stock -1
retailer updates stock (@11:00:00) true 9 9 open order (id =1) not taken into account
customer cancellation (orderid=1) (@11:15:00) true 9 9 customer cancellation (id = 1) not taken into account
reservation (orderid=2) on webshop (@11:20:00) true 9 8 corrected_stock -1
retailer updates stock (@11:30:00) true 2 2 cancelled order (id = 1) not taken into account

open order (id = 2) not taken into account

shipment (orderid = 2) (@11:40:00) true 2 2 shipping an order does not change the corrected stock
retailer updates stock (@11:50:00) true 1 1 cancelled order (id = 1) not taken into account

shipped order (id = 2) also not taken into account

 

Delivery codes

The following delivery codes can be used to indicate your delivery promise:

Deliverycode Delivery period shown on bol.com
24uurs-23 Ordered before 23:00 on working days, delivered the next working day.
24uurs-22 Ordered before 22:00 on working days, delivered the next working day.
24uurs-21 Ordered before 21:00 on working days, delivered the next working day.
24uurs-20 Ordered before 20:00 on working days, delivered the next working day.
24uurs-19 Ordered before 19:00 on working days, delivered the next working day.
24uurs-18 Ordered before 18:00 on working days, delivered the next working day.
24uurs-17 Ordered before 17:00 on working days, delivered the next working day.
24uurs-16 Ordered before 16:00 on working days, delivered the next working day.
24uurs-15 Ordered before 15:00 on working days, delivered the next working day.
24uurs-14 Ordered before 14:00 on working days, delivered the next working day.
24uurs-13 Ordered before 13:00 on working days, delivered the next working day.
24uurs-12 Ordered before 12:00 on working days, delivered the next working day.
1-2d 1-2 working days.
2-3d 2-3 working days.
3-5d 3-5 working days.
4-8d 4-8 working days.
1-8d 1-8 working days.