Promotions (BETA)

The Promotions API allows customers to track both bol.com promotions that belong to a marketing campaign, and seller-specific promotions that apply to their product portfolio, enabling sellers to evaluate whether they should adjust the pricing of any of their products to qualify for promotion visibility. The API shows currently-running and upcoming promotions that could be applicable to the retailer’s product portfolio, allowing them to position their products in the shop with visibility features that help them stand out in the search results block.

Promotions BETA timeline

The Promotions API is part of the bol.com Beta program, and as such is planned to be previewed and released with the following schedule:

  • Start date: 1 June 2021

  • End date: 1 September / V6 release

If you wish to participate in the Promotions Beta, please contact us via email at retailerapi-beta@bol.com.

Retailer promotions and promotional campaigns

The Promotions API will return all promotions that apply to the partner, including those that belong to a campaign and those that were created specifically by the partner. The retailerSpecificPromotion field indicates whether the promotion belongs to a bol.com campaign or specifically applies to the seller ID.

For more information about participating in promotional campaigns, refer to Promotions in bol.com campaigns (Dutch).

For more information about setting up your own promotions, refer to Set up your own campaigns (Dutch).

Seller-specific promotions should be created or removed in your Seller Dashboard. The Promotions API is primarily intended to allow you to automate your bol.com campaign promotion tracking to enable you to prepare your product pricing.'

Promotion types supported by the API

Currently the Promotions API is limited to particularly Price Off and partly Price Awareness type promotions. These are described below. In future we plan to expand the promotion types available in the API, and we will keep you informed.

Awareness

This applies when a product is not discounted, but already has a low price relative to other products in its classification type. The product will be highlighted on bol.com like this:

Awareness
Figure 1. Awareness

Price off

This applies when a discount is active on a product. The product will be highlighted on bol.com like this:

Price off
Figure 2. Price off

How to use the Promotions API

The API consists of two endpoints:

  1. GET Promotions - returns the basic information for all current and future promotions that apply to the retailer ID, up to 3 months in the future. The GET Promotions response includes:

    1. The start and end dates

    2. The countries that apply to the promotion

    3. The promotion type

    4. The list of retailer EANs that are potentially applicable to the promotion category

    5. Whether the promotion belongs to a bol.com campaign.

  2. GET Promotion - returns detailed information for a promotion, allowing retailers to adjust their pricing to enable their products to qualify. The GET Promotion-specific response includes:

    1. Relevance scores for your products

    2. The maximum price of the product to qualify for the promotion

    3. The best selling offers for the product category, by country.

Relevance scores

The relevance score tells you how relevant bol.com has determined the product to be to the promotion. The score has a range of 1-100 and is based on the following data:

  • How often the article has been viewed

  • How often the article has been placed on a wishlist

  • How often the article has been sold

  • The review scores of the article

  • The return percentage of an article.

The higher the score, the more relevant the product is in the promotion. Scores for a product can differ per country for a retailer.

Maximum price

The maximum price reflects the upper limit of pricing that your product must meet to qualify for the promotion. You can decide for yourself at what price you want to put the item for sale. Since promotion visibility depends largely on relative pricing, you should use this guide to set your pricing equal to or below this if you want your goods to be highlighted with a promotional label.

Best selling offers

The best selling offer is the offer for that EAN at the moment of requesting that will be highlighted in the web shop. Price is one of the most important considerations for promotional highlighting, and if your pricing is not competitive enough relative to the current best selling offer, it will not be highlighted. Other factors that we use to determine the best selling offer include the delivery time and service.