Please note: The Subscription API is still in Beta phase which means it is only accessible to a limited group of retailers.
The Subscription API will be live for all sellers on October 1st 2020.
What is the Subscription API?
Currently our API only supports polling of our process status events, by sending requests to the Retailer API.
With the Subscription API we allow consumers to subscribe to relevant events via notification when they happen, without the need to poll.
The idea is that you as a partner (or 3rd party) can register webhooks and subscribe to events that you would like to receive.
This way you may not have to poll as often as you need to right now and gives us the opportunity to introduce events for which we currently don’t have API calls (yet).
Be advised that registering subscriptions is an additional way of receiving data from bol.com, and does not replace existing functionality. You can still use the regular endpoints on the Retailer API as you are used to.
For now we only support delivering messages to webhooks. A webhook is an endpoint on your side where we can deliver a message when an event you are subscribed to takes place.
During the beta phase we will send out process-status events.
Process statuses that will be pushed are SUCCESS, FAILURE and TIMEOUT.
Because of security reasons we only accept webhooks that are registered on an https domain. Registering a webhook without using SSL is therefore not possible and will result in an error when attempting to subscribe.
How does it work?
There are a few steps in the process in connecting to the Subscription API.
Logical process flow
See the steps below for a more detailed description on the process.
1. Create your webhook
First of all you have to build a webhook on your side where we can send the events that you want to subscribe to. As stated before this must be an https address.
See the step 4. Receive events part below to read about what you can expect so you can build your endpoint accordingly.
2. Subscribe to event(s)
After you implemented your webhook successfully it’s time to subscribe your endpoint to the Subscription API.
See the POST example on how to create a subscription.
You could also choose to update your current subscription. See PUT on how to do this.
3. Get process status
Because the POST call in the previous step is asynchronous we return a process status object. From it you can retrieve its process status id and request the status of the process.
Once it is done the response will have an entity id which represents your subscription id.
Once you’ve completed your endpoint and subscribed to an event (currently only PROCESS_STATUS is supported) you will start receiving messages.
Of course it can happen that messages arrive in the wrong order or that a message cannot be delivered due to time-outs or any other issue at your side or ours.
To make this as reliable as possible we’re making use of at-least-once delivery. This means that it’s possible that you receive the same message multiple times.
Please make sure that your system can handle this, for example by registering which messages you’ve already processed on your side.
If it happens that we cannot deliver a message the first time, we will retry 4 times with an increasing interval between the retries.
After these retries we will not try again and the message will be dropped.
As a fallback scenario you can always use the respective GET endpoints on the Retailer API.
Possible race conditions
We cannot guarantee messages will always arrive in the correct order.
For example: Message A and B for the same process have failed, where the retries of message A have failed 2 times and the retry of message B failed once.
Let’s say your system comes up in the meantime and message B is retried after 2 minutes while message A will be sent after 4.
To enable you to check if this is the case we added a timestamp to the message.
NOTE: This is the timestamp of the event being handled in our landscape, not the timestamp of when we sent it.
Below is an example of what the message looks like.
To create a subscription you have to do the following call: POST /retailer/subscriptions
Your body should look like:
This will return a response with a process status, as you are used to from our other API calls. Once it’s successfully processed you can get the subscription id (entityId in the process status response) with which you can do the following operations.
NOTE: a URL can only have 1 subscription. If you want to subscribe to multiple resources for 1 URL you have to manage this with 1 subscription. You can’t have more than 1 subscription for the same URL.
This endpoint enables you to fetch a subscription by its subscription id and verify its details.
This endpoint enables you to modify an existing subscription by its subscription id. You can use this to change the address of your endpoint or the event types that to want to subscribe to, for example.
The body looks the same as the POST call except you have to include the id.
When you want to remove a resource from the subscription you have to submit the resources you want to be subscribed to, excluding the one you want to remove.
When you want to add a resource you have to submit all the resources you want to be subscribed to, including the one you want to add.
This endpoint enables you to entirely delete an existing subscription by subscription id.
For the specific API documentation, please visit our ReDoc page: https://api.bol.com/retailer/public/redoc/v4#tag/Subscriptions
There are a few IP addresses from which we publish messages. You can whitelist these if needed.