All documentation below refers to the Offer-API-Version-1. in February 2017, Offer-API-Version-2 will be released.
The offer management features allow a seller to manage “warehouse information” regarding the products he sells on the bol.com platform.
These features have been added to provide a next generation alternative to the more tardy offer FTP as it aims to be much faster and allows a seller to update a single offer rather than having to upload all offers, even if only one of them has changed.
The offer FTP and the Plaza API’s offer features cannot be used simultaneously as the Plaza API requires an “offer ID” to be present which neither the FTP nor the manual solutions support.
Before starting with the EOF one should delete all offers from the bol.com database by uploading an offer sheet with only 1 article in it through the seller dashboard or FTP. This should cause all the other offers to be deleted.
Then also manually delete that last offer.
After that, start uploading the offers again through the API.
The definition of an offer
An offer is the combination of:
- a product (EAN)
- a condition (new, 2nd hand, etc.)
- a unit price
- a delivery promise (I.e.: “Ordered before 17:00, delivered the next day”)
- a quantity of items in stock
- a description in case of a not new article.
On top of that the API requires that you assign an “offer ID” that identifies each offer that is unique within the seller’s offers.
Also, an offer consisting of a new product can only exist once per seller. In other words: One EAN code can only appear once as a new article in the seller’s offers.
2nd hand products however can exist more than once as each 2nd hand product can have its own distinct features and therefor every 2nd hand products may need its own description.
When communicating with the Offer API, an “Offer ID” must be used that identifies each offer that is unique within the seller’s offers. Essentially this is a string consisting of at most 64 UTF-8 characters.
This offer ID is NOT the same thing as the ReferenceCode used in the Offer FTP which is non-unique, free text limited to 20 ascii characters.
This offer ID cannot be changed anymore at a later stage, unless the associated offer is deleted first and then created again, but with a different offer ID.
Note that the Offer ID is currently not made available in the Open Orders API call. So, although an offer is uniquely identified by its offer ID, one may still need to (ab)use the “ReferenceCode” field to host the offer ID as this field does appear within each open order.
The offer features consist the following API calls.
- Create Offer
Allows for the addition of a new offer
- Update Offer
Modify an existing offer, except for the number of items in stock
- Update Offer Stock
Update the stock of a particular offer.
- Delete offer
- Get All Offers
Get a CSV file of all offers including whether they are for sale on bol.com or not.
With the exception of “Get All Offers”, all these API calls aim to be processed and updated on the website in a matter of minutes.
“Get All Offers” is an asynchronous process that can take up to 15 minutes to complete.
Intended usage in a nutshell
The following describes the intended usage of the Offer API.
- Make sure to delete all current offers (if any) by uploading an nearly empty xlsx file through the back office or FTP.
- Upload your offers one by one through the offer API using the Create call.
- Once finished, download your offers using the Get All Offers call
Maintaining your stock
Maintain your stock by pushing stock updates as they occur. So an event driven approach in your ERP system would be best. Alternatively log stock changes and push them by periodically firing a batch process.
Verify that bol.com is up to date
Download all your offers. (At least daily). Iterate over each offer and compare it to your own database. When a discrepancy is found, send an offer update to bol.com.