Offer API

The ean field is used to identify the item that you want to sell on bol. The ean is required and it is also allowed to provide an ISBN (International Standard Book Number) in this field. When you provide an ISBN, the bol marketplace will link it to the actual ean of that item. In that case, the ISBN is discarded. The ean is part of the unique key of an offer within the bol marketplace and can therefore not be changed if the offer is created successfully. If you want to change the ean of an offer, you need to delete the current offer and create a new one.

In case the bol marketplace doesn’t know the provided ean for this offer, it might be difficult to find this product back in the bol systems. Therefore, you can provide an unknownProductTitle that allows you to easily find back this offer. If you want to know if the bol marketplace already knows this ean, you can use the GET product-ids endpoint for this. If this endpoint provides you a bolProductId, then the bol marketplace already knows this ean.

In accordance with the Digital Services Act, the bol marketplace must show consumers who is the responsible economic operator in the EU for a product before they purchase it. Every retailer is individually responsible for providing the required economic operator information. The economicOperatorId is the identifier of the created economic operator. If you do not have an economicOperatorId yet, then you need to create this first. You can do this by using our Economic Operator API. You can update the economic operator anytime.

The reference field can be used to define a custom reference. The bol marketplace only uses this reference to help you find data back within the bol marketplace. You can therefore use this for your own recognition. It is not mandatory to provide a reference but if you do so, then take into account that the field size is limited to 100 characters. It is always possible to update the reference afterwards.

The onHoldByRetailer field can be used to temporarily pause this offer. This only applies if your offer is online on the bol marketplace. If your offer is already marked as offline, pausing it will have no effect. If you want to pause an online offer, you can set this field to true. If you want to continue selling this offer, you can set this field back to false.

The condition object contains information regarding the condition of the product that you want to sell on the bol marketplace. Depending on the type of the condition, logic applies to what data you need to provide. The type can only be any of the following:

The pricing object refers to the base pricing that applies to this offer. This price does not include any promotions. The bol marketplace allows you to use up to four prices. It is not required to use more than 1 price, but you do need to provide at least 1. You cannot set the pricing to null (as it is mandatory to provide) nor you can send an empty array.

You can set the price using the bundlePrices object. If you plan to provide more than 1 price, you need to reward your customers with a (small) discount if they buy more than 1 unit (volume discount). The quantity therefore needs to increase per element in the array, whereas the unitPrice needs to decrease. An example of selling an item with two prices is the following:

In this example, if a customer buys the product with a quantity of 2, the customer gets both products for 8,99 euro (17,98 euro in total). You can always adjust the price in the future if necessary.

The countryAvailabilities object indicates in which country you want to sell this offer, via the countryCode field. You have four options to indicate where you want to sell this item:

It is always possible to change the country availability afterwards. If you want to change the country availability back to your default account setting, you can send null or omit it from they payload (that will default to null). Note that sending an empty array is not allowed.

The fulfilment object indicates how you want to fulfil a potential customer order. Depending on the method of the fulfilment, logic applies to what data you need to provide. The method can only be any of the following:

The stock object indicates the amount of products that you have. Whether you need to provide this object depends on the type of offer that you are creating:

You can update the stock levels anytime in the future.

In case of a successful request to the bol marketplace, you will receive a response code with code 201. In the response you will also find the assigned offerId to this offer. Save this offerId as it is the unique key tied to this offer. All subsequent requests to bol require this offerId.

The offerId is the unique bol identifier that is assigned to this offer. It is not possible to change the offerId.

The lastModifiedDateTime is the timestamp in which this offer was updated last according to the bol marketplace. Be aware that the bol marketplace will update this timestamp if any change has impacted this offer. For instance, an offer is marked as offline initially, but right after that it becomes online again. It would mean like the offer itself hasn’t changed but this change can cause the lastModifiedDateTime to be updated.

The datetime is according to the ISO-8601 standard and includes an offset from UTC time.

Within the stock object you will find the correctedStock field. The field applies to both an FBB and FBR offer. The value of this field will always be calculated, unless the stock.managedByRetailer flag is set to true for fulfilment.method = FBR offers. As the correctedStock field is calculated by the bol marketplace, it is not possible to update this field yourself. If you make a change to your stock level (stock.aoumt), the bol marketplace will recalculate the correctedStock. This might take some time.

In order to understand how the correctedStock is calculated, take a look at the examples below.

Table 1: FBR offer stock management where managedByRetailer = false

Table 2: FBR offer stock management where managedByRetailer = true

Within the countryAvailabilities object you will find the forSale field. The forSale field will indicate if this offer is for sale in the corresponding country, based on the countryCode. The forSale flag is only present for the countries this offer is listed in. It is also not possible to update this field yourself.

Note that changes in the bol marketplace might cause your offer to be reevaluated at certain times. If you want to know when a change has taken place you can use our Subscription API and subscribe to our FOR_SALE and NOT_FOR_SALE events.

Within the product object, you will find the bolProductId field. This field refers to the product id of the bol marketplace. It cannot be changed and is the uniquely assigned identifier for each product at bol.

Within the page object, you will find two fields:

The offerId is the bol identifier that is uniquely assigned to this offer. You cannot change the offerId.

With the countries object, you will find the countryCode field and the corresponding reasons for for this country. The countryCode field refers to the country in which you want to sell this offer (NL for the Netherlands and BE for Belgium). You provided this when creating an offer, or it is taken from you Retailer account setting.

Not-for-sale (offline) reasons apply per country. This means that, when you create an offer for both NL and BE, your offer can be offline within Belgium (forSale = false), but online within the Netherlands (forSale = true). In this endpoint, you will only see reasons if there is at least one offer offline in any of the two countries. In this case, you will therefore only find reasons for countryCode with NL.

In case your offer is online completely, you will not receive any content in this endpoint. Also it is not possible to update or change the data in this endpoint.

The reasons object contains a code field, and a description field. The code field is a unique number assigned to this reason. Based on this code, you can define a solution that could automatically resolve this reason. The code is explained functionally by the description field, which can be used to understand why this offer is offline. If all the reasons are resolved, your offer should normally go online.

When it comes to offline reasons, it is good to take note of the following:

If you want to update a field with a new value, like the reference field, you can send this new value to the PATCH endpoint. For instance, if the value for the reference field is currently This is my first reference and you want to update it to This is my second reference, you can send the following payload to this PATCH endpoint:

If you want to delete the value for the reference field, you can send the following payload:

If you want to remain the value of the reference field you omit this field from your payload. If the field is defined as an enumeration, you cannot set this field to null or "".

If you want to update a boolean field like the onHoldByRetailer, you send a new value. For instance, if you want to set the onHoldByRetailer flag to true, you send the following payload:

If you want to remain the value of the onHoldByRetailer field you omit this field from your payload. You cannot set this field to null or "".

If you want to update an array, like the countryAvailabilities, you are required to send the whole array. This array will replace the previous array. For instance, you want to sell this offer in both the Netherlands (countryCode = NL) and Belgium (countryCode = BE). Currently, this offer is only available in Belgium (countryCode = BE). To achieve this, you need to send the following payload:

It is not possible to send null or "" to bundlePrices (a price is always required), but for countryAvailabilities object this is allowed.

If you want to update an object, you can send the fields within that object that you want to update. Whether a field is within an object or not, does not affect the way they are processed. If a field (or nested object) is required within the object you want to update, you are required to send it as well.

For instance, you want to update the fulfilment schedule. Within this schedule, the method field is required. Therefore, you need to send the method field as well:

If you want to update your stock level as well as your selling price, you can provide both objects in one single request. For instance, you want to set the price per piece to 9.99 euro and your amount of stock needs to be adjusted to 46. The quantity and unitPrice fields are mandatory, so they need to be present in the payload.

To achieve this, you can send the following payload to the bol marketplace: