Release Notes bol Retailer API Version 10

Version 10.20

Version Release Date Release Type

10.20

11-07-2025

Minor

A new optional query parameter, vvb-only, has been added to the Get a list of orders endpoint.

  • When vvb-only=true, the response includes only new or changed VVB orders. If combined with fulfilment-method=FBB, the response will be empty, as FBB orders are excluded by design.

  • When vvb-only=false or the parameter is not set, the API returns all orders, for either FBR, VVB, FBB, or all, as per the standard behavior.

Why have we added this

This enhancement provides more efficient filtering for integrators focused solely on relevant FBR order updates, reducing unnecessary data processing.

There are no breaking changes for the improvements mentioned above. The existing behavior is kept aiming at enhancing understanding and usability for our API users.

Version 10.19

Version Release Date Release Type

10.19

14-04-2025

Minor

We have moved the subscription endpoints out of beta and is now part of the main release cycle.

Version 10.18

Version Release Date Release Type

10.18

20-01-2025

Minor

We have introduced a new field, economicOperatorId, to the Retrieve an offer export file by report id endpoint. This field identifies the Economic Operator entity (e.g., manufacturer, authorized party, importer, distributor, or other entities responsible for the product in accordance with applicable EU laws) relating to your offer.

Why is this important?

Starting February 1, 2025, all offers must include a valid economicOperatorId. Offers without a valid Economic Operator ID will be set offline and will no longer appear on the webshop.

Key Details

  • The economicOperatorId field has been added to the Offer export.

  • This change is not a breaking change, as previously communicated in our best practices. Retailers are expected to parse CSV reports dynamically to handle such updates.

For more information on retrieving an offer export file, refer to the functional documentation. We recommend updating your systems to include the new field in your offer management workflows to ensure compliance with this requirement.

Version 10.17

Version Release Date Release Type

10.17

13-12-2024

Minor

Reverting Changes to Economic Operator Links

In this release, we are reverting the changes introduced in Version 10.15 to the Update an Offer endpoint regarding the handling of the economicOperatorId field.

New Behavior (Version 10.17)

  • Omitting economicOperatorId: The link between an offer and its economic operator will no longer be removed when this field is omitted from the request payload.

  • Sending null: Sending null for the economicOperatorId field will also not break the link.

  • Exception for Empty Strings: Sending an empty string "" for the economicOperatorId field will break the link between the specified offer and the economic operator. This behavior is specific to this endpoint and overrides our API conventions, which otherwise disallow the use of empty strings.

Key Notes

Reverting Version 10.15 Changes

The behavior introduced in Version 10.15, where omitting economicOperatorId would unlink an offer from an economic operator, has been reverted in this release (Version 10.17).

Temporary Adjustment

These changes are temporary and will be reviewed in the next major version (v11).

As previously announced, starting February 2025, the economicOperatorId field will become mandatory for all offers. Offers without a valid economicOperatorId will be marked offline on the webshop. We encourage developers to stay updated on upcoming changes via Developers Portal to ensure a smooth transition.

Version 10.16

Version Release Date Release Type

10.16

11-12-2024

Major

As previously announced, the transition period for Retailer API v8 and v9 ended on December 1, 2024, and these versions have now been fully removed from our platform.

What does this mean?

Impact

After the extended transition period, Retailer API v8 and v9 are no longer accessible as of today. All endpoints and functionalities related to these versions have been permanently disabled.

Action Required

If you have not yet upgraded, you must transition to Retailer API v10 to restore and maintain your integration.

Why this change?

The removal of these older versions ensures that all users are aligned with our latest, most secure, and efficient API framework. Retailer API v10 offers significant improvements, including enhanced performance, improved reliability, and access to new features that are not supported in older versions.

Additionally, with the introduction of Retailer API v10, the requirement to upgrade the entire API every 6 months has been removed. as previously announced, starting from May 2024, upgrades will only be necessary when breaking changes are introduced. Furthermore, individual release schedules per resource will be implemented, offering more flexibility and ensuring that updates are tailored to specific functionalities.

For detailed information, please refer to:

Version 10.15

Version Release Date Release Type

10.15

09-12-2024

Minor
These changes were reverted on 13-12-2024 due to user impact, please see Version 10.17 Release Notes for more details.

Clearing Economic Operator Links

We have updated the Update an offer endpoint to allow unlinking an offer from an economic operator.

New Behavior

If the economicOperatorId field is omitted in the request payload, the link between the specified offer and the economic operator will be removed.

Important Notes

  • This change only removes the link for the specified offer and does not delete the economic operator itself.

  • To delete an economic operator, use the Delete a specific economic operator associated with a retailer.

  • This change will not affect your other offers linked to the same economic operator. To unlink other offers, you must repeat this process for each one individually.

This update simplifies the process of managing offer-economic operator relationships while maintaining the integrity of other linked offers.

As per our API conventions, we do not accept empty strings ("") for the economicOperatorId field. To remove the link between an offer and an economic operator, omit the field entirely in your request payload. Sending empty string will result in validation errors.

Version 10.14

Version Release Date Release Type

10.14

28-11-2024

Major

The following deprecated versions of the Advertising API have been fully removed:

  • v10 Advertising API

  • v9 Advertising API

From now on, only v11 Advertising API will be available and supported. We encourage all users to migrate to v11 to continue leveraging our services with enhanced functionality, improved performance, and the latest features.

For migration details and updated documentation, please visit the functional documentation.

Version 10.13

Version Release Date Release Type

10.13

01-10-2024

Minor

Improvements

We have introduced a new optional field, economicOperatorId, in the Offers API. This field has been added to facilitate the linking of offers to the responsible economic operator, in compliance with the European Union’s Digital Services Act (DSA).

Changes

Endpoint Field Change location Previous behaviour New behaviour

Create a new offer (all versions are impacted)

economicOperatorId

Request body

NA

economicOperatorId is introduced as an optional field.

Update an offer (all versions are impacted)

economicOperatorId

Request body

NA

economicOperatorId is introduced as an optional field.

Retrieve an offer by its offer id (all versions are impacted)

economicOperatorId

Response body

NA

economicOperatorId is being returned if the offer has one.

For more information on how to link economic operators to your offers, refer to this page.

As of 1 February 2025, bol will enforce that all offers listed on the platform must be linked to a VALID economic operator. Retailers are required to ensure that their offers comply with this regulation, as any offers linked to an INVALID or deleted operator may be unpublished.

Version 10.12

Version Release Date Release Type

10.12

17-07-2024

Minor

Improvements

Enhanced the reference field across multiple endpoints to support a maximum of 100 characters, improving flexibility and usability for user-defined identifiers.

Changes

Endpoint Field Change location Previous behaviour New behaviour

Create a new offer (all versions are impacted)

reference

Request body

reference field supported up to 20 characters

reference field supported up to 100 characters

Update an offer (all versions are impacted)

reference

Request body

reference field supported up to 20 characters

reference field supported up to 100 characters

Unpublished offers report

The maximum size of the referenceCode field in the offers export will also be increased to 100 characters.

For best practices on handling these changes, please refer to our best practices.

Version 10.11

Version Release Date Release Type

10.11

05-07-2024

Major

New Feature: Product Categories

We have introduced a new endpoint to retrieve the full product category tree of the bol web shop. This enhancement allows you to:

  • Access the complete product category structure, including all subcategories.

  • Optimize your product listings by utilizing detailed category information.

  • Match category IDs from performance reports to their corresponding names for improved reporting.

The category tree data is cached and refreshed hourly to ensure you have the most up-to-date information.

For more details on using this new endpoint, refer to functional documentation and the Redoc.

Version 10.10

Version Release Date Release Type

10.10

21-06-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 status, fulfilment-method, fulfilmentStatus and fulfilmentMethod fields in the Get a list of orders endpoints.

Changes:

Change location Previous Behaviour New Behaviour

status field in query parameters

The status field didn’t indicate the default value even though it had one as OPEN all versions.

The status field now has default value clearly defined and visible on redoc.

fulfilment-method field in query parameters

The fulfilment-method field didn’t indicate the default value even though it had one as FBR all versions.

The fulfilment-method field now has default value clearly defined and visible on redoc.

fulfilmentStatus field in response body

The fulfilmentStatus field didn’t have enum values defined on redoc.

The fulfilmentStatus field now has enum values clearly defined and visible and states as OPEN and HANDLED.

fulfilmentMethod field in response body

The fulfilmentMethod field didn’t have enum values defined on redoc.

The fulfilmentMethod field now has enum values clearly defined and visible and states as FBR and FBB.

Field descriptions on redoc

NA

The description of the status and fulfilmentStatus fields have been updated to be more clear and comprehensive across all versions.
There are no breaking changes for the improvements mentioned above. The existing behavior is kept aiming at enhancing understanding and usability for our API users.

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.

  • 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

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: