API v3 – Process status

Any data manipulation request (i.e. POST, PUT or DELETE) that will be send to our retailer API will be handled a-synchronously. When receiving your request, we store it internally into a queue. The retailer API is continuously working from the queue to handle all requests. All requests are stored in a specific sequence. Based on the amount of requests in the queue, it may vary how long it will take to execute your request. Once your request is lined up first, we will forward it to another internal service within our landscape. This works as follows:

  • When we receive your request, we assign a process status id with it. With this id, you can request the status later in time. The status of the message is at this moment in time PENDING.
  • Consequently, we forward it to a downstream service. This results in an update of the process status to SUCCESS (in case of a successful response) or FAILURE (in case of a failure).
  • In case a downstream service is on temporarily unavailable or unable to process your request, we put it back to our internal queue for retry. The status remains in that case at PENDING.
  • In case of an unexpected response, we retry your request 5 times every 5 minutes. In case it fails 5 times in a row, the status will transform to FAILURE.
  • When the process status is SUCCESS, only then you will receive the entityId. Before that, the action was not yet executed (or continuously unsuccessful) and therefore, no entityId exists (in case of POST requests).
  • In case of a FAILURE, you can find the reason for failure by looking at the errorMessage field.

Be aware: in case a request remains at pending state for a longer period of time, we put it to TIMEOUT. This means the downstream service was unable to process all the requests in a specified time frame and therefore we time out your request.

Process overview



Process-statuses are stored for a maximum of 2 days. You cannot request the process-status for a process initiated longer than 2 days ago.



You can fetch the process status events in three ways:

  1. By using the process status id that you got from the initial request.
  2. By using a list of process status id’s at once (maximum of 1000 process status id’s in 1 request).
  3. By using the entity id and event type of the original request.

For more details, verify our documentation on https://api.bol.com/retailer/public/redoc/v3#tag/Process-Status