Offers process and considerations

Offers play a crucial role in allowing retailers to sell products on the bol platform. They can encourage a buyer to order more of a given item(s).

This section provides an explanation of the offer processes and common mistakes made while connecting to the Offers API.

For more information on the Offers API, refer to offers and the Redoc.

Offers API overview

The Offers API has been designed to support the continuous growth of the bol platform and to minimise the increasing complexity of the offer domain. The main focus is to handle all offer related processes independently, in a fast and efficient way regardless of the channel used by the partners. To achieve this, a new version of the API was designed which could optimally connect to the systems that were completely aware of the specific changes made to the assortment of a retailer.

When working with offers, you should know which offers need to be updated and which specific components have changed for those offers. Sending update requests with no actual changes as compared to the current offers, results in overloading both your and our systems leading to slow processing of the requests. Therefore, you are requested to only communicate the specific changes to avoid overloading the systems.

To ease out this process, component-specific update messages have been introduced to the offer flow that allow you to specifically update a single component of your offer. This enables you to design your own flow in such a way that you can specifically adjust certain fields without having to send the unchanged data. For example, you can send only the price field without having to send the unchanged stock, fulfillment option, and other offer-related information.

This is achieved by designing the following three distinct offer update messages that:

  • Update the price of your offer.

  • Update the stock for your offer.

  • Update the fulfilment method (FBB/FBR) and delivery promise for your offer.

The Create a new offer request combines all the aforementioned components as all the fields are needed to create a new offer. However, for Update an offer request, it is more efficient to pull the components apart as updating the price can be processed faster by our systems as compared to the updation of the delivery promise that requires more processing time.

Ensure that you don’t combine the three distinct update messages for only updating one component of the offer as it dissipates resources at both sides.

Single offer requests instead of bulk

The Offers API enables you to create, delete and update only single offers because it:

  • Allows alignment with the design of API.

  • Allows faster processing of requests.

  • Allows proper communication of the request statuses (failure/success) through the Process Status request.

  • Allows efficient use of resources.

On the contrary, bulk offer updates are heavier to process for the internal infrastructure causing the request processing times to be considerably longer.

All the existing users of old bulk offer request should send offer requests with specific relevant changes only. Using rate limits from bol allows sufficient bandwidth to process all your necessary changes.

Key considerations while using the Offers API

It is recommended to pay attention to the following while working with the Offers API:

Mapping products to their unique EAN(s)

Each product must always have its unique and non-interchangeable EAN, as each product can exist in multiple variations.

For example, the products sharing the same material, shape and series are available in variants based on their distinctive features. Therefore, every size/color for a t-shirt or shoe size for a pair of sneakers should have their corresponding unique EANs.

Creating multiple active projects

Having multiple active projects using the same EAN(s) is not recommended. Ensure that every project must always have only one corresponding EAN value mapped to it.

Updating offers instead of adopting the DELETE-CREATE flow

For every update that you want to process, choosing the DELETE-CREATE flow is not advised. The DELETE-CREATE flow means that for processing every update for your offer, you first delete the existing offer and then create a new one. Though this flow, allows you to use just one Create a new offer request instead of three separate requests to update the entire offer, it is not recommended as this process negatively affects the performance of the systems. Choosing the DELETE-CREATE flow will also result in your assortment going offline for a period of time as a result of the delete request until the Create a new offer request is processed.

Furthermore, these requests are not only costly to process but they also negatively impact the processing times for your updates.

The Create a new offer request takes the longest time to process and has a lower priority compared to the Update an offer requests.

Combining three separate update requests for every update

Combining the three update requests and sending all three requests every time for updating a component of the offer is also not recommended. The Offers API is designed for managing partial updates, hence ensure that you design your systems in such a way that allows you to update the specific components of your offer.

For more information on component specific offer update messages, refer to Offers API overview.

Linking economic operators to offers

In accordance with the Digital Services Act, bol must show consumers is are the responsible economic operator in the EU for a product before they purchase it.

Every retailer must create their own economic operators, and link the related economic operator ids to their offers.For more information please refer to Economic Operators API.
For now, this is optional. From February 1st 2025, bol will enforce on offers that do not have a valid economic operator.
Sending an empty string "" for the economicOperatorId field will break the link between the specified offer and the economic operator when using Update an offer endpoint. This behavior is specific to this endpoint and overrides our API conventions, which otherwise disallow the use of empty strings. This does not delete the economic operator itself. To delete an economic operator, use the Delete a specific economic operator associated with a retailer endpoint. This change will not affect your other offers linked to the same economic operator. To unlink the economic operator from your other offers, you need to repeat this process for each offer individually.