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: creates a new offer.
-
Retrieve offer: retrieves an offer that was created earlier.
-
Update offer: updates offer details, excluding stock and price.
-
Update offer price: updates price information for an offer.
-
Update offer stock: updates stock information for an offer.
-
Delete offer: deletes an offer.
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.
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.
Offers export API
-
Request offer export: Request an export of the complete offer catalog.
-
Retrieve offer export: Retrieve the offer export generated from the request offer export call.
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 |
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.
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 |
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.