bol API Conventions

The Retailer API is secured with OAuth2. For all secured endpoints, users need to log into the SSO server at https://login.bol.com and retrieve a token. This token can then be used to authorize users for secured endpoints. The authentication process is described in detail here.

More information on the headers to set is available in the headers section.

The Retailer API enforces strict limits when calling the API to prevent overloading of the Retailer API and/or backend services. Endpoints are throttled based on a set of properties, similar to the list below:

There are three time units available:

The list above is an example of how throttling limits are configured in our landscape and is not representative of current production settings.The most specific rule will have the highest precedence:

The retailer API is able to support all available HTTP methods, although some may not be supported for all resources.

Whenever a specific method is not supported by the retailer API, an error will be returned. For HEAD and OPTIONS requests, the body will be omitted, even in case of errors. The status codes will be returned as per usual.

The Retailer API provides HTTP response codes for each request that correspond with the body and action the user has attempted. Here are the most common response codes used by the Retailer API:

The Retailer API employs a standardized way to relay problems that occur, and follows the Problem RFC 7807 as a guide. The RFC defines a common model for displaying errors is defined, which gives all the information needed to resolve common errors while interacting with the API. User errors can be recoverable (4xx range) or technical (5xx range). The type of error should also define whether or not a call to technical support is warranted.

The Retailer API supports various message formats for sending requests and receiving responses. JSON is the supported request format for all the versions. For the responses, we support additional formats such as CSV, PDF and Excel (openxmlformat).

The properties and entities in the responses returned from the Retailer API are in lowerCamelCase. This means that the first character is lowercase, and each following word starts with an uppercase character. For example:

This applies only to JSON properties. XML supports the usage of attributes within XML tags (tagValue). Since, this is not compatible with the JSON model, this functionality is not supported. Additionally, since our JSON is not namespaced, no namespace information is applied.

The Retailer API currently supports the following HTTP methods. Other methods are available, but not actively supported by the API.

When interacting with the API, the meta-data for your requests can be added by using headers. There are a few headers that are of particular importance:

There are several ways to request a specific version of an API, among which are the following approaches:

For the Retailer API we have chosen Header Versioning. There are a few reasons for choosing this approach.

As we are specifically versioning the model going in and out of the API - rather than the endpoints themselves - we can use the Content-Type and Accept header for this. As described earlier, we use vendor-specific media types which allow us to express version and format in a single parameter, and we can use separate headers to define the version and types of the models going in and out.

The Retailer API is a fully synchronous service when it comes to GET requests; users can wait for an answer to arrive. For POST/PUT/DELETE operations we follow a different strategy, where we handle these requests asynchronously. For these operations we return an instance of type ProcessStatus, which will contain the processing status of the original request.

For a description of the fields, please refer to the relevant API reference documentation. The most important fields to look at in this response are the ID and status fields. At present, the process in the example is listed as PENDING, which means a background process is still busy processing the request. In time, the process should reach an end state, which is one of the following: SUCCESS, FAILURE, TIMEOUT. In case of a success, no further action is required. In case of FAILURE or TIMEOUT the user can attempt to execute the action again, unless the error message clearly specifies that this will not succeed.

In the example shown above, the executed action is the shipment confirmation of an order, so the entity-id (order id in this case) is known. Some actions such as creating an inbound shipment for FBB will return an ID upon completion of the process. For these actions, the entityId field will be null while in PENDING state, and only after the process transitions to SUCCESS will the field be populated by the resulting value. For all other processes (UPDATE/DELETE type operations) the action can’t be initiated without the ID of the entity to update/delete.

Users should poll the process status returned to them using the relevant endpoint specified in the API documentation. Initially, the process status instance will start their lifecycle with the status PENDING, and will change to an end state at an unspecified time after being submitted.

To protect the services in our landscape from overloading, we throttle these actions, which means we cannot guarantee immediate execution. Generally speaking, most process status entities will change state within half a minute of submission. The number of times a user can poll the process status is limited by throttling.

The limit is quite high so it should not interfere, but to be safe allow some time between individual polls to make sure these limits are not hit.

For testing during development without having to create test data or test with production data users can use the demo environment. The same authentication validations apply as the actual API so you need to use the token as you would accessing the Retailer API.

Demo resource paths follow our path naming conventions with the prefix /retailer-demo/.

Documentation on the demo environment can be found here, grouped by version. This page documents how to use the demo environment endpoints with the predefined requests and expected responses for all calls. The documentation is generated and tested and kept up to date after each deployment.

If the request does not match exactly with the documented requests a problem with status 400: bad request is returned to inform you the requested resource is not available.

The resources in the Retailer API were designed to be used differently when calling lists versus single items. Specifically, list calls such as Get a list of orders intentionally retrieve much less information per order than single calls such as Get an order by order id. This is because detailed calls are frequently accessing multiple backend systems, and providing the bulk of information in a list at high frequencies will slow down our services.

We ask that you use the API calls in the way they were designed to minimize the impact on the Retailer API. List calls should be used to provide the information on the next steps to take, and the single calls allow you to process each case.

Whenever the API isn’t responding the way you would expect it to or is returning errors, you can get in touch with Partner Service for assistance.

We’ve added headers to each request that can be provided in your query with Partner Service to make it easier to find all trace information for your request. This will help in determining the root cause of any issues.

The header to uniquely identify your request is named X-Request-ID header; make sure you log this together with any errors that might have occurred processing your requests so you can add it to your support queries with bol.