API v3 – 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 the price, stock level, delivery promise and fulfillment method.

Available Offer endpoints
Options to retrieve your Offer ID’s
Price scenario’s
Stock scenario’s
Available delivery codes

 

Available Offer endpoints

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 ID. This Process status ID can be used to retrieve the OfferID. Creating a new offer only happens once and cannot be used to update an offer.

The OfferID that you receive when retrieving the Process Status of a ‘create offer’ request is needed for the get, update and delete requests.

 

Offer list

The Offer list requests can be used to retrieve a csv file with the OfferID’s and principal information of all your offers. It consists of a post request that will trigger the preparation of the csv, and a get request to retrieve it.

 

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.

Options to retrieve your Offer ID’s

Version 3 of the Retailer API uses Offer ID’s which are required to update or delete your offer. There are two flows with which you can retrieve your offer ID’s, one is suited more for a initial load when you start with the V3 and the other can be best used when you create new offers;

Option 1 (with the use of a bulk export)

When you start with the V3 you might already have offers tied to your seller account (either because you used a different version of the API or used other options such as the seller dashboard or our FTPS). These offers already have Offer ID’s in our system which you need to know if you want to update or delete them in the future.

The GET single offer request only works if you have the Offer ID so you need to do a initial load to gather the Offer ID’s of your active assortment. The best way to do this is by requesting a Offer export (which will return all Offer ID’s).

Step 1

a. First you need a POST request which will start the creation of the offer export file. The required format of this is a csv file.

b. In the response to the POST request you can find the value ‘ID’. This ID is not the Offer-Export-ID but relates to a process status.

Step 2

Use the ID of the above response in a GET process status request. The use of the Process Status is because of the asynchronous processing of the request which means you always have to check later if the request was handled correctly.

If you correctly perform the GET process status request then you should get a response with a ID (which is the Process Status again) and a entityId. The entityId returns the id which is needed to retrieve the export file.

Step 3

Once the process status is set to ‘succes’ you can use the Entity ID (Offer-Export-ID) in combination with the GET Retrieve an offer export file request. The response will be the requested CSV file which will contain both EAN’s and OfferID’s which can be used to correctly map the Offer ID’s in your database. You can use our demo-environment for a example of the CSV file.

Option 2 (with the use of the create offer flow)

The above option is suited for a initial load. After that you of course will still be adding new offers for which you need offer ID’s if you want to update or delete them in the future. The best way to retrieve these Offer ID’s is by correctly implementing the Create Offer flow. This will involve the process status flow because of the asynchronous nature of the process.

Step 1

a. First you need a POST create offer request to start the process of creating a new offer.

b. In the response to this request you will receive a ID. This ID is the process status ID and can be used to retrieve the status of the process and the Offer ID.

Step 2

Use the ID of the above response in combination with a GET Process Status request. In the response you will both receive a status and a entityId. The entityId will only be filled if the Status is SUCCESS as in other cases the Offer has not been created. If the Status is “pending’ you need to keep polling the process status until you either get a SUCCESS or a Time-out/Failure.

If the status is ‘SUCCESS’ then the entityId will be filled with the Offer ID of the newly created offer.

Bundle price scenario’s

In the new version of the API, retailers can use “bundlePrices” to offer volume discounts. With volume discount you can offer the customer a lower price when buying more items. The retailer can provide a maximum of 4 bundles, one of which has to be quantity ‘1’. The maximum is 4 bundles, but it is not mandatory. You can also choose to have 2 or 3 bundles in total. Every bundle is a combination of quantity and unit price, where the quantity acts as a minimum order quantity for the specified price. Be aware that your first ‘bundle’ is the mandatory single unit offer (quantity=’1’).

For example, if a retailer supplies the following bundle prices for an offer:

{
    "pricing": {
        "bundlePrices": [
            {
                "quantity": 1,
                "price": 9.99
            },
            {
                "quantity": 5,
                "price": 8.99
            },
            {
                "quantity": 10,
                "price": 7.99
            },
            {
                "quantity": 15,
                "price": 6.99
            }
        ]
    }
}

This offer will be priced 9.99 for an order of 1-4 items, 8.99 for an order of 5-9 items and 7.99 for an order of 10-14 items and 6.99 for 15 items or more. To remove the bundle discount, update your “bundlePrices” offer using only the single unit bundle (quantity = ‘1’).

Find more information on volume discounts on our partner platform: https://partnerplatform.bol.com/verkopen/tips-voor-je-winkel/volumekorting-2.

 

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

 

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

 

bol.com Development Center