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

Retrieves offers by their identifying offerID.

Update offer

Updates the delivery code, publishing status, offer reference, and fulfilmentMethod and referencecode.

Update offer stock

Updates the stock of the specified offer. Refer to Stock scenarios below for more details.

Update offer price

Updates the price of the specified offer.

Delete offer

Deletes an offer. 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 offer IDs 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 IDs: one is more suited for a initial load when you start with the V3 API, and the other is besgt used for creating new offers.

Retrieve offer IDs using the offers export API

When you start with the V3 API 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 IDs 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 offerID. 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 an 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 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 EANs and offerIDs 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 option above 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 offerID 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
            }
        ]
    }
}

The offer in this example will be priced €9.99 for an order of 1-4 items, €8.99 for an order of 5-9 items, €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 site.

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.

Cancellations by the retailer always result in a corrected stock being set to 0.
This functionality can only be used when you are 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.