Offers

Version 3 of the Retailer API has been deprecated. Please migrate to the v4 API as soon as possible.

Offers API

Create new 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.

Get offer

The get offer endpoints allows retrieval of offers by their identifying offer id.

Update offer

Allows you to update delivery code, 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.

Offers export API

Offers export

The offer export file 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.

The stock of an item in the offer export file is not always the current stock. For the current stock level of an item, the ‘Retrieve an offer by its offer id’ endpoint should be used.

Retrieving offer IDs for existing offers

Version 3 of the Retailer API uses Offer IDs 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.

Retrieve offer IDs using offers export API

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 retrieve single offer request only works if you have the associated offer ID. If you already have active assortment online, you will need to gather the offer ids currently known to bol.com. The best way to do this is by requesting a Offer export (which will return all offer IDs).

Step 1

First you need a request offers export which will start the creation of the offer export file. The output format of the export is a csv file.

Step 2

In the response to the request you can find the value ‘ID’. This ID is the ID for the returned process status^.

Step 3

Use the ID of the process status in a retrieve process status^ call. The use of the process status enables asynchronous processing of the request allowing you to check later if the request was processed correctly.

If you successfully retrieve the process status, you should get a response with an entityId. The entityId will contain the ID needed to retrieve the export file.

Step 4

Once the status field for the retrieve process status contains the value SUCCESS, you can use the entityId (which is the ID for the offer export) in combination with the retrieve offer export call. The response will be the requested CSV file which will contain both EAN’s and OfferID’s which can be used to map to the offer IDs in your database.

You can use our demo-environment for an example of the CSV file.

For this request you need to use the following Accept-header: application/vnd.retailer.v3+csv

Retrieve offer IDs using offers API

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

First you need to use the create new offer call to start the process of creating a new offer.

Step 2

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 3

Use the ID of the above response in combination in a retrieve process status^ call. In the response you will both receive a status and an 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 TIMEOUT/FAILURE.

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

Bundle prices

In the new version of the retailer API, retailers can use the bundlePrices element to configure volume discounts. With volume discount you can offer the customer a lower price when buying more items. The retailer should provide at least 1 and at most 4 bundles. Every bundle is a combination of quantity and 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.

All prices are in euros.

Stock scenarios

In the Retailer API, we supply 2 stock elements in the response of a retrieve offer call.

  • Seller Stock

  • Corrected Stock

When sending 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.

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 do not adjust the stock to account for open orders. Also, customer cancellations are not taken into account and thus do not result in a higher corrected stock.

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 process a stock update using the Seller Dashboard, the managedbyretailer field is reset to false.

Below are two distinct scenarios detailing the use and effects of the managedByRetailer element.

Table 1. Offers with stock managedByRetailer=false
event seller stock corrected stock explanation

retailer updates stock (@10:00:00)

10

10

reservation (orderid=1) on webshop (@10:10:00)

10

9

corrected_stock -1

retailer updates stock (@11:00:00)

9

8

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

customer cancellation (orderid=1) (@11:15:00)

9

9

corrected_stock +1

reservation (orderid=2) on webshop (@11:20:00)

9

8

corrected_stock -1

retailer updates stock (@11:30:00)

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)

2

1

shipping an order does not change the corrected stock

retailer updates stock (@11:50:00)

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
Table 2. Offers with stock managedByRetailer=true
event seller stock corrected stock explanation

retailer updates stock (@10:00:00)

10

10

reservation (orderid=1) on webshop (@10:10:00)

10

9

corrected_stock -1

retailer updates stock (@11:00:00)

9

9

open order (id =1) not taken into account

customer cancellation (orderid=1) (@11:15:00)

9

9

customer cancellation (id = 1) not taken into account

reservation (orderid=2) on webshop (@11:20:00)

9

8

corrected_stock -1

retailer updates stock (@11:30:00)

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

Available delivery codes

You can find the available delivery codes on our ReDoc documentation page (fulfilment element) when creating or updating an offer.