Retailer API Definition of Service and Usage

This document describes the definition of service and usage applicable to the bol.com Retailer API. By using the Retailer API users automatically consent to having read, understood, and agreed to the contents of this document. Users that are not using the API in accordance to this document can and will be contacted by Partner Service for a resolution.

Service Objectives

Bol.com will use commercially reasonable efforts to make the Retailer API available with the following monthly uptime percentages per category:

Technical Availability

Bol.com will use commercially reasonable efforts to make the Retailer API technically available for at least 99% of the time.

The Retailer API is considered to be technically available whenever it is…​

  • Reachable by API users and provides processable responses

  • Responding with error messages due to supporting systems (first-party or third-party) being unavailable or technically malfunctioning. The service will respond with technical errors that can be retried by end users; for example 504: gateway timeout, 500: internal service error.

  • Not timing out without providing a response on more than 5% of requests.

Functional availability

Bol.com will use commercially reasonable efforts to make the Retailer API functionally available for at least 95% of the time.

The Retailer API is considered to be functionally available whenever it is…​

  • Reachable by API users and provides processable responses

  • Is responding with functional, recoverable error messages - for example 404: not found, 400: bad request - that can be handled by API users

  • Is not timing out without providing a response on more than 5% of requests.

Scheduled maintenance

Whenever the Retailer API is fully or partially unavailable due to scheduled downtime, we will notify our end users through the public channels available to us. Please subscribe to these channels and watch them for any notifications. When announcing downtime, we will ensure to provide insights in the duration of the downtime and the affected services. The Retailer API is split into several technical components, meaning that outages can affect one area but not another. We will provide detailed information on the functionality that will and will not be disrupted. For instance, maintenance on offer processing will usually not affect content processing, allowing the Retailer API to be partially functional.

Bol.com will attempt to announce all scheduled maintenance up to 72 hours but no later than 48 hours ahead of time. Depending on the urgency and planning of the maintenance we cannot always guarantee sufficient notice.

Bol.com will use commercially reasonable efforts to make sure that scheduled maintenance does not exceed 4 hours.

More information can be found here

Unscheduled maintenance and service outages

Whenever the Retailer API is fully or partially unavailable due to unscheduled downtime or service outages, we will notify our end users through the public channels available to us. Please subscribe to these channels and watch them for any notifications. When announcing downtime, we will provide insights into the duration of the downtime and the affected services in case of partial downtime.

All unscheduled maintenance and service outages will be announced as soon as they are identified. Urgent patches such as security patches and critical bug fixes will always be deployed as soon as possible. These posts will be updated with new status information as the situation evolves.

Uptime percentage calculation

Uptime is calculated as the percentage of time per month in which the service is fully operational and available. Outages outside our influence are excluded from uptime; for example:

  • Internet connectivity outages

  • Outages (planned and unplanned) of third party systems

  • Scheduled maintenance to internal systems.

Rate limits

Every Retailer API user will receive a request budget that can be used to make requests to the API. These rate limits vary based on endpoint and method and are scaled to allow proper interaction with the platform for all API users. The budget available to users was imposed so that bol.com can continue to guarantee the stability of the API and prevent service outages due to excessive load.

All current rate limits are available in HTML or JSON format:

Rate limit adjustments

At any time if necessary bol.com can make changes to either increase or decrease rate limit amounts to guarantee stability and availability of the Retailer API. These changes will be communicated to the registered technical contact and through the public channels. Whenever these limits are unsatisfactory, please make sure to contact Partner Service for support.

Rate limit scaling

The Retailer API assigns the same rate limit volumes to all users equally. For users that have specific needs, we have processes in place that allow higher volumes of requests whenever this applies to the retailers unique position on the platform. You can contact Partner Service to discuss if you can apply for this feature. We will evaluate the specific situation and determine based on offer/order volume and historic API usage statistics if available whether or not we can grant this request.

Please note that current rate limits are scaled to allow each and every Retailer API user to do as many requests as necessary to integrate with the bol.com platform.

Retailer API endpoint lifecycle stages

In order to have maximum predictability and stability and to allow users to adjust and conform to changes in the Retailer API, the Retailer API follows a strict versioning scheme.

We identify the following stages in the Retailer API lifecycle. These stages can apply to individual endpoints but mostly apply to complete API versions:

For details on how we release new versions in these lifecycle stages, please consult the Retailer API Lifecycle documentation.

Partner Service response times

Whenever there are technical or functional issues with the API that are not resolvable without support from bol.com, please contact Partner Service for support. Please make sure to check the error messages coming back from the API to make sure the error is non-resolvable. Also verify the implementation against the functional ReDoc and technical convention documentation.

  • Issues can be logged by contacting Partner Service.

  • Partner Service endeavors to responds to all service requests within a timeframe of 2 working days.

  • Outside of business hours you only have the option to send an email, which will likely be handled the next working day.

  • Detailed information for contacting Partner Service is listed here.

Fair use of the Retailer API

We provide the tools and documentation that should enable all retailers to efficiently use the Retailer API. Whenever Retailer API users are using the API in inefficient or unintended ways, bol.com will contact the retailer technical contact to discuss the perceived violations of the terms and services and this document for improvement. If after repeated contact the violations are not discontinued we can block retailers from API access altogether as a final measure. If this happens, please make sure to contact Partner Service as soon as possible to discuss the terms for removing the block. Please read through the API conventions documentation to see how clients should implement calls to the API. Examples of violations are:

  • High volumes of bad requests without checking the returned error messages to prevent them.

  • Not checking process status entities and/or repeating operations that can’t succeed; for example confirming orders that are already confirmed, updating already deleted offers.

  • High volumes of requests with an expired token, not checking token expiry time or the error message that we return.

  • High volumes of requests when rate limiting is active, by not checking the rate limiting headers to schedule the time where requests can be made again.

  • High volumes of login requests. Tokens are valid for a longer amount of time and can be reused to do subsequent requests. Failing to do so and logging in before every request is not efficient and strongly discouraged.

The Retailer API provides detailed feedback responses for each and every user request. We urge users to properly check this information to prevent unnecessary high load on the Retailer API, so we can keep guaranteeing future performance and stability.

Terms of Service

In addition to the topics described in this definition of service and usage, we also provide a Terms of Service document, available at https://developers.bol.com/tos/.

Glossary

Scheduled maintenance

We withhold the right to do scheduled maintenance on the Retailer API whenever required to guarantee availability, performance, and stability of the Retailer API. Scenarios include patching and updating software and libraries, security fixes, and bug fixes. We generally won’t roll out new features during scheduled maintenance.

Partner Service

Partner Service is the support organization responsible for handling support requests from Retailer API users, including:

  • Functional questions regarding the API and how to use the API to do business with bol.com;

  • Technical questions regarding the API and how to develop against the API.

Detailed information on how to reach partner service is available here: https://developers.bol.com/contactformulier/

Registered technical contact

The registered technical contact is the person that is responsible for being the technical contact for the bol.com support organization on behalf of the retailer.

  • In using the Retailer API you have agreed to providing a technical contact to bol.com.

  • The registered technical contact is a required field that should be filled in the API settings tab of the Seller Dashboard.

  • The registered technical contact should always be kept up to date in case of changes in personnel.

  • Technical contacts are expected to respond to inquiries by bol.com within 2 working days.

  • If you haven’t configured the technical contact details yet, please make sure you do so. By not filling out the technical contact details, you will not be eligible for support.

Public communication channels

Publicly available channels where bol.com will share API-related information:

Technical documentation

Documentation written to help implement clients for the Retailer API is available on https://api.bol.com/retailer/public. Topics include detailed descriptions and helpful information regarding:

  • OpenAPI specification for client generation

  • Navigable API documentation using Redoc

  • Demo documentation

  • API conventions

  • Release notes

  • Postman suites for easy endpoint access

API conventions

Implementation standards, available on our conventions page, highlighting the correct way to implement clients for the Retailer API. The documentation covers many subjects, such as authentication, versioning, message formats, validations, and more.