Supported event types

Event types are the different categories or classifications of events that you can subscribe to receive notifications about. When subscribing you can customize the types of updates and notifications you wish to receive as per your requirements.

Different delivery methods support different types of events. The table below displays all the supported delivery methods for each event type.

Table 1. Event types and supported delivery methods
Subscription event type	Supported delivery method
Process Status	Webhooks GCP Pub/Sub AWS SQS
Shipment	Webhooks GCP Pub/Sub AWS SQS
Order	Webhooks GCP Pub/Sub AWS SQS
Price star boundary	GCP Pub/Sub AWS SQS
Competing offer	GCP Pub/Sub AWS SQS
Offers for sale	GCP Pub/Sub AWS SQS
Offers not for sale	GCP Pub/Sub AWS SQS

Process status subscription

The PROCESS_STATUS subscription event provides information about the status of an asynchronous request towards Retailer API and offers the following types.

Table 2. Process status events
Event name	Description
`SUCCESS`	The request was successfully completed.
`FAILURE`	The request failed. Examine the process status error message for more information.
`TIMEOUT`	The request timed out. This means the downstream service was unable to process all the requests in a specified timeframe, and therefore we timed out your request.

An example of a push message after creating a process status subscription is provided below.

Process status push message example

{
   "retailerId":1234567,
   "timestamp":"2020-02-02T23:23:23+01:00",
   "event":{
      "resource":"PROCESS_STATUS",
      "type":"SUCCESS",
      "resourceId":"1234567"
   }
}

The event.resourceId in this message is the processStatusId from the call.

Shipment subscription

The SHIPMENT subscription event allows you to monitor shipment status of the order, and has the following types.

Table 3. Shipment status event
Event name	Description
`UPDATE_TRANSPORT_EVENT`	A shipment has changed its shipment status.

The resourceId in the message body is the shipmentId which you can use with the Get a shipment by shipment id endpoint to see in detail what changed in the transport.transportEvents element.

An example of a push message after creating an update transport event subscription is provided below.

Update transport event push message example

{
   "retailerId":1234567,
   "timestamp":"2020-02-02T23:23:23+01:00",
   "event":{
      "resource":"SHIPMENT",
      "type":"UPDATE_TRANSPORT_EVENT",
      "resourceId":"0837872b-f805-45f3-8f60-3233ea933ed7"
   }
}

Order subscription

The ORDER subscription event allows you to receive notifications about new orders and order item cancellation requests. It has the following types:

Table 4. ORDER events
Event type	Description
`ORDER_CREATED`	An new order has been created
`ORDER_ITEM_CANCELLATION_REQUEST`	A cancellation was requested for one or more order items

The resourceId in the message body contains the orderId which you can use with the Get Order By Id endpoint to retrieve the full order details.

An example of a push message that is sent after a new order is created is shown below.

Order created push message example

{
   "retailerId":1234567,
   "timestamp":"2020-02-02T23:23:23+01:00",
   "event":{
      "resource":"ORDER",
      "type":"ORDER_CREATED",
      "resourceId":"A123456789"
   }
}

Price star boundary subscription

The PRICE_STAR_BOUNDARY event type sends a message whenever a retailer has a sellable offer for a product with updated price star boundaries.

In the notification, you receive the EAN of the product that has undergone changes in its price star boundaries. Use this EAN to retrieve the updated boundaries by using the Get price star boundaries by EAN endpoint.

For more information on price star boundaries, see the functional documentation.

This subscription event has the following types:

Table 5. Price star boundary events
Event type	Description
`CHANGE`	Indicates that a change in price star boundaries has occurred for a product you are offering.

An example of a push message after the price star boundary of a product has changed is given below:

Price star boundary change push message

{
   "retailerId": 1234567,
   "timestamp": "2020-02-02T23:23:23+01:00",
   "event": {
        "resource": "PRICE_STAR_BOUNDARY",
        "type": "CHANGE",
        "resourceId": "0045496429577"
   },
    "metadata": {
        "BPID": "9300000079089746",
        "country": "NL",
        "ean": "0045496429577"
    },
    "links": [
        {
        "url": "https://api.bol.com/retailer/products/0045496429577/price-star-boundaries",
        "method": "GET"
        }
    ]
}

The event.resourceId within the message corresponds to the EAN of the product for which the boundary has been updated. The metadata.BPID in the message corresponds to the bol product ID for this product.

Competing offer subscription

The COMPETING_OFFER event type sends a message whenever a retailer has a sellable offer for a product, and any of the competing offers have undergone changes.

Every notification will include the corresponding EAN linked to the updated competing offers. Use this EAN to fetch the most recent competing offers using the Get a list of competing offers by EAN endpoint.

For more information on competing offers, see the functional documentation.

The following fields are subject to potential changes:

offerId
retailerId
countryCode
bestOffer
price
fulfilmentMethod
condition
ultimateOrderTime
minDeliveryDate
maxDeliveryDate

This subscription event has the following types:

Table 6. Competing offer update events
Event type	Description
`CHANGE`	Indicates that a change in competing offers has occurred for a product you are offering.

An example of a push message after the competing offers of a product have changed is given below:

Competing offer change push message

{
    "retailerId": 1234567,
    "timestamp": "2020-02-02T23:23:23+01:00",
    "event": {
        "resource": "COMPETING_OFFER",
        "type": "CHANGE",
        "resourceId": "0045496429577"
    },
    "metadata": {
        "BPID": "9300000079089746",
        "country": "NL",
        "ean": "0045496429577"
    },
    "links": [
        {
            "url": "https://api.bol.com/retailer/products/0045496429577/offers",
            "method": "GET"
        }
    ]
}

The event.resourceId within the message corresponds to the EAN of the product for which the competing offers have been updated. The metadata.BPID in the message corresponds to the bol product ID for this product.

If your offer becomes unsellable, you still receive one final notification about the competing offers that have undergone changes.

Offers subscriptions

The Offers subscriptions events has the following types:

Event type Description

FOR_SALE

The FOR_SALE event indicates that your offer went for sale on the bol marketplace. There are specific reasons why an offer can go online on the bol marketplace.

Some examples are:

You created an entirely new offer on the bol marketplace. This offer will be validated against different platform policies. When this process is completed, and the offer is approved, this event will be sent.
Another partner on the bol marketplace made a change to their own offer. As a consequence of this change, your offer will also be published on the bol marketplace.
Your offer went earlier offline because there was no stock left for this offer. When the stock levels on this offer are updated, this offer can go online again on the bol marketplace.

You can use this event (in combination with the NOT_FOR_SALE event) to know when the processing of your newly created offer is finished at the bol marketplace.

NOT_FOR_SALE

The NOT_FOR_SALE event indicates that your offer went offline on the bol marketplace. There are specific reasons why an offer can go offline on the bol marketplace.

For instance:

The stock level associated with your offer reached 0. A possible future customer order cannot be fulfilled anymore without any stock. Therefore, your offer was automatically taken offline.
You (temporarily) closed your own shop. If you close your shop, that means you are unable to fulfill any potential FBR offers. If you close your shop, your offers are also automatically taken offline.
A policy of the bol marketplace was violated. As a consequence of this violation, your offer is taken offline.

You can use this event (in combination with the FOR_SALE event) to know when the processing of your newly created offer is finished at the bol marketplace.

An example of the structure of the event is as follows:

Offer change push message

{
    "retailerId": "1234567", (1)
    "timestamp": "2020-02-02T23:23:23+01:00", (2)
    "event": {
        "resource": "OFFER_FOR_SALE", (3)
        "type": "FOR_SALE", (4)
        "resourceId": "c6b3b17d-8db1-4d03-8784-d993de083a7b", (5)
        "metadata": {
          "countryCode": "NL" (6)
        },
        "links": []
    }
}

1	`retailerId` references the Id of the retailer which information belongs to. This is a numeric value passed as a String.
2	`timestamp` refers to the time of creation of the event.
3	`event.resource` Refers to the resource the event came from. For this event, this is `OFFER_FOR_SALE` or `OFFER_NOT_FOR_SALE`.
4	`event.type` Refers to the event type that happened. For this event, this would be either `FOR_SALE` or `NOT_FOR_SALE`.
5	`event.resourceId` Identifies the resource where this event happened. For this event, the `resourceId` is the `offerId`.
6	`metadata.countryCode` Refers to the country in which this offer went online. This can either be `NL` or `BE`.