Subscription API (BETA)

The Subscription API is still in beta phase which means it is only accessible to a limited group of retailers.

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. Be advised that registering subscriptions is an additional way of receiving data from, and does not replace existing functionality. You can still use the regular endpoints on the Retailer API as you are used to.

Delivery methods

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.

Event types

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.

subscription api flow
Figure 1. Logical process flow

A detailed description of these steps is covered below.

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 this must be an https address.

See 4. Receive events to learn what to 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 POST to learn how to create a subscription.

You could also choose to update your current subscription. See PUT to learn 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.

4. Receive events

Once you’ve completed your endpoint and subscribed to an event you will start receiving messages. Note that currently only PROCESS_STATUS is supported.

Of course it is possible for messages to arrive in the wrong order or for a message to not be delivered due to timeouts or other issues at either side.

Subscription Service Features

At-least-once delivery

To make this as reliable as possible we’re making use of at-least-once message delivery. This means that it’s possible to 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.

Retry mechanism

If we cannot deliver a message the first time, we will retry 4 times with an increasing accumulated interval between the retries.

Table 1. Retry intervals for push messages
Retry Interval


1 min


2 min


4 min


8 min

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.

This is the timestamp of the event being handled in our landscape, not the timestamp of when we sent it.

Push message example

Below is an example of the push messages you might receive after creating a subscription. These messages will contain all the information you need to take next steps by calling a specific resource on the retailer API.

example push message
  "retailerId": 1234567,
  "timestamp": "2020-02-02T23:23:23+01:00",
  "event" : {
     "resource": "PROCESS_STATUS",
     "type": "SUCCESS",
     "resourceId": "8ac14d66-b7ee-40a6-9a42-26e815e87e4a",
     "metadata": [
         { "key" : "somekey" , "value" : "somevalue"},
         { "key" : "somekey2" , "value" : "somevalue2"}
     "links": [
           "method": "GET",
           "href": ""

Supported operations

Create subscription

To create a subscription you have to do the following call: POST /retailer/subscriptions

create subscription example
  "resources": ["PROCESS_STATUS"],
  "url": ""

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.

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.

Get subscription by id

This endpoint enables you to fetch a subscription by its subscription id and verify its details.

get subscription response example
  "id": 1234,
  "resources": ["PROCESS_STATUS"],
  "url": ""

Update subscription

This endpoint enables you to modify an existing subscription by its subscription id. For example you can use this to change the address of your endpoint or the event types that to want to subscribe to.

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 subscribe 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 subscribe to, including the one you want to add.

Remove subscription

This endpoint enables you to entirely delete an existing subscription by subscription id.

For the specific API documentation, please visit our ReDoc page.

IP Whitelisting

There are a few IP addresses from which we publish messages. You can whitelist these if needed. IPs for push messaging