Release Notes bol Retailer API Version 10

Version 10.9

Version Release Date Release Type

10.9

01-02-2024

Minor

Improvements

This release contains an update that enhances the following endpoints across all available versions – V8, V9, and V10. This update focuses on the onHoldByRetailer field in the Update an offer and Create an offer endpoints.

Changes:

  1. Optional onHoldByRetailer Field in All Versions (V8, V9, V10):

    • Previous Behavior: The onHoldByRetailer field was mandatory in both Update an Offer and Create an Offer endpoints across all versions.

    • New Behavior: The onHoldByRetailer field is now optional in versions V8, V9, and V10. This change introduces greater flexibility in managing offers, allowing API users to optionally include this field.

  2. Improved Field Description Across Versions:

    • The description of the onHoldByRetailer field has been updated to be more clear and comprehensive across all versions. This improvement is aimed at enhancing understanding and usability for our API users.

Version 10.8

Version Release Date Release Type

10.8

30-01-2024

Major

New Feature: Product Rankings and Impressions Endpoint

This release introduces a significant upgrade to our API with the new Product Rankings Endpoint, designed for a more technical and in-depth analysis of product performance metrics in webshop environments.

  • Get product rankings: Retrieves the rank and impressions of products within the webshop, utilizing advanced models to analyze their performance in both search and browse contexts, offering a comprehensive technical overview of market positioning and visibility.

Product Rankings Endpoint:

  1. Function: Retrieves and analyzes product ranking and impression data within the webshop.

  2. Query Modes:

    • Search: Targets product rankings based on explicit user search queries. Outputs include product rank per search term and impression counts.

    • Browse: Focuses on product data organized by category IDs, relevant for category-based navigation and promotional analysis.

    • Mixed Type: Aggregates data from both Search and Browse modes when the type parameter is unspecified, providing a comprehensive dataset.

Integration with other endpoints:

Enhanced compatibility with Get product list and Get product list filters endpoints for comprehensive category-level market analysis.

You can find more information on the documentation of Get product rankings and impressions page.

Version 10.7

Version Release Date Release Type

10.7

12-01-2024

Major

New features and improvements

Bulk Commission Retrieval:

Now retrieve commission rates for multiple products in one request.

Detailed Rate Structure:

Commission rates detailed by date range, product category, and price range.

Improved Calculation Formula:

Clearer commission calculations with VAT considerations.

Discount Handling:

Adjustments in commission calculations to prevent negative totals.

Operational Improvements:

Synchronous operation for immediate responses. Better feedback for failed queries (e.g., invalid EANs).

Version 10.6

Version Release Date Release Type

10.6

19-12-2023

Minor

New features and improvements

Enhanced Retailer Identification:

The endpoint now allows users to retrieve their own retailer information by using 'current' as the identifier, in addition to using a specific retailerId.

Expanded Information Set:

In addition to existing data, the response body now includes company name, the KVK number and VAT number for retailers. This is particularly beneficial for users in the Netherlands, providing essential business credentials in the response.

How to Use the New Features:

To retrieve your own retailer information, simply use current instead of a specific retailerId in the request. The response body will automatically include the KVK number and VAT number for retailers based in the Netherlands.

Version 10.5

Version Release Date Release Type

10.5

18-12-2023

Minor
New fields introduced

New features

Version 8, 9 and 10 of the API introduces the following updates:

Retailer API

The following endpoints have a new field, enabled, which indicates whether a notification subscription is enabled or not. You are able to enable or disable subscriptions yourself.

Your subscriptions might now be disabled automatically in certain scenarios. For more information on why your subscription might be disabled automatically, please see the Subscriptions documentation.

Version 10.4

Version Release Date Release Type

10.4

29-09-2023

Major
BREAKING CHANGES

New features and improvements

Version 10 of the API introduces the following updates:

Advertising API

  • The following resources of Advertising API have not been migrated to v10:

    • Ad Groups

    • Assortments

    • Campaigns

    • Keywords

    • Negative Keywords

    • Target Products

      For more information on why these resources have not been migrated, see here.

      For a comprehensive list of frequently asked questions pertaining to this transition, see here.

  • The Reporting resource remains in Beta and is migrated to v10 of the API.

Retailer API

The following resources of Retailer API offers significant improvements:

  • Insights and Products

    • The Get price star boundaries by EAN endpoint has moved out of Beta and has been relocated from the Insights resource to the Products resource in v10 of the Retailer API.

    • The Get a list of competing offers by EAN endpoint of the Products resource offers updates to the maxDeliveryDate field in the response. This field indicates the latest date by which a package can be delivered to the customer. However, when bol offered a product as a pre-order, this date was unavailable. In such cases, to ensure a comprehensive view of all competing offers, a dummy date was used as a placeholder for all bol pre-order offers that did not have a maxDeliveryDate available.

      However, starting from v10 onwards, the maxDeliveryDate field is no longer mandatory, and hence there will be no utilization of the placeholder date.

  • Orders and Shipments

    • The Ship order item endpoint has been relocated from the Orders resource and has been added as Create a shipment to the Shipments resource.

    • A new quantity field is added to the request body of the Create a shipment endpoint of the Shipments resource and it supports multiple objects in the orderItems array. Consequently, starting from version 10 onwards, it is possible to split an order item into multiple shipments and purchase multiple shipping labels for a single order item.

    • A new enum value, INBOUND_COLLECT has been added to the response body of Get a shipment by shipment id endpoint of the Shipments resource.

    • The Beta endpoints Get a list of invoice requests and Upload an invoice for shipment id have moved out of Beta and are migrated to v10 of the Retailer API.

  • Shipping Labels

For more information on the improvements, see the v9-v10 migration guides and the functional documentation.

The demo scenarios for the v10 of the API can be found here.

v7 of the Retailer API will be deprecated as per the release schedule. As a result, all requests directed to the Retailer API version 7 will be automatically redirected to version 8 of the Retailer API from November 1, 2023, until May 1, 2024.

This extension allows you to continue utilizing version 7 of the API for an extended duration until the introduction of the new API versioning strategy. Upon the implementation of the new versioning strategy, you can seamlessly transition to this base version, eliminating the need for an additional migration step. For more information, see here.

Shared API

A new event type CREATE_SHIPMENT has been added to the request body of Get the status of an asynchronous process by entity id and event type for a retailer endpoint.

Version 10.3

Version Release Date Release Type

10.3

23-08-2023

Minor

Improvements to Get a list of competing offers by EAN endpoint of the Retailer API

Get a list of competing offers:

This release contains changes to the maxDeliveryDate field of the Get a list of competing offers by EAN endpoint.

This field indicates the latest date by which a package can be delivered to the customer. However, there are instances when this date remains unavailable, particularly when bol.bom offers a product as a pre-order. From this version onwards, maxDeliveryDate is no longer a mandatory field. This allows the inclusion of pre-order offers in the complete set of competing offers.

For more information, see the functional documentation and the Redoc.

The demo scenarios for Get a list of competing offers can be found here.

Version 10.2 (BETA)

Version Release Date Release Type

10.2

04-07-2023

Minor
BREAKING CHANGES

OpenAPI Specification upgrades and Advertising API naming consistency

This release contains the following changes:

Version 10.1 (BETA)

Version Release Date Release Type

10.1

19-06-2023

Minor

New endpoints added to the Advertising API

This release contains the addition of the following new endpoints to the Reporting resource of the Advertising API:

  • Request a campaign performance report - Generates the performance data report for multiple campaigns (bulk) in a single request.

  • Retrieve campaign performance report by report id - Retrieves the performance data report for multiple campaigns.

For more information, see the functional documentation and the Redoc.

The demo scenarios for the above endpoints are provided below:

Version 10.0 (BETA)

Version Release Date Release Type

10.0

30-03-2023

Major
BREAKING CHANGES

New features and improvements

Version 10 of the Retailer API contains the following updates:

For more information on the aforementioned endpoints, see the functional documentation and the Redoc.

The demo scenarios for the above endpoints are provided below: