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, divided into the following categories.

Technical Availability

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

The retailer API is considered to be technically available whenever:

  • the retailer API is reachable by API users and provides processable responses;

  • the retailer API is 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 (i.e. 504 gateway timeout, 500 internal service error).

  • the retailer API is 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.0% of the time.

The retailer API is considered to be functionally available whenever:

  • the retailer API is reachable by API users and provides processable responses;

  • the retailer API is responding with functional, recoverable error messages (i.e. 404 - not found, 400 - bad request) that can be handled by API users;

  • the retailer API 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 is be disrupted and what isn’t. For instance, maintenance on offer processing will usually not affect content processing, allowing this retailer API to be partially functional.

Bol.com will attempt to accounce 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 scheduled maintenance does not exceed 4 hours.

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 ensure to provide insights in 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 (security patches, 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 counted 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 on 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 is imposed so 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 in order 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 partnerservice 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 partnerservice 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, 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.

Partnerservice response times

Whenever there are issues with the API, be it technical or functional that are not resolvable without support from bol.com, please contact partnerservice for support. Please make sure to check the error messages coming back from the API to make sure the error is non-resolvable. Also check if the implementation is correct according to the documentation, both functional (redoc) and technical (conventions).

  • Issues can be logged by contacting partnerservice (details on how to reach partnerservice here);

  • Partnerservice endeavours to responds to any and 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 on contacting partnerservice is listed here: https://developers.bol.com/contactformulier/

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 partnerservice 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 this);

  • Not checking process status entities and/or repeating operations that can’t succeed (i.e. confirming orders that are already confirmed, updating already deleted offers, etc.);

  • 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 re-used 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 expose 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 bugfixes. We generally won’t roll out new features during scheduled maintenance.

Partnerservice

The support organisation 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 organisation 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 in a timely fashion, 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, validation and much more.