Orders v2.1

What’s new in version 2.1

  • We have introduced pagination for this endpoint for performance reasons. The size of the list is set on 25 items. If the response is an empty list it means there are no open orders at that time or at the specified page.
  • We had to change the OrderId and OrderItemId fields from a Long to a String in order to comply with future changes in our landscape.
  • The field “FulfilmentMethod” has been added to the OrderItem.
  • New filtering options are added to retrieve FBB and FBR orders.
  • We have renamed the field “PromisedDeliveryDate” to “LatestDeliveryDate” in order to give the field a proper meaning. The word “Promised” made it feel like it was a promise between the customer and the retailer which is not the case.

Looking for Orders 2.0 documentation?

Get a paginated list of orders

This endpoint retrieves a paginated list open orders. Orders are sorted by date in descending. Orders are made up out of one or more OrderItems and every OrderItem has it’s own unique OrderItemID.

GET /services/rest/orders/v2


Name Type Values Description
page integer If no value is given it will default to 1
fulfilment-method string FBR, FBB This indicates which type of orders you want to retrieve. If no value is given it will default to FBR


In order to use this endpoint you need to add a specific Acceptheader to your request (listed below).


Example request

GET /services/rest/orders/v2?page=1&fulfilment-method=FBR

Example response

Status: 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<Orders xmlns="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
     <Surname>Van der Bol.com</Surname>
     <ZipCode>1111 ZZ</ZipCode>
     <Surname>van der Bol.com</Surname>
     <ZipCode>1111 ZZ</ZipCode>
     <Title>Basicxl - Rijdende Wekker - Kunststof - 16x11cm - Zwart</Title>

OrderItem request values explained

Name Type Description
OrderItemId string ID for the product (1 order can have multiple OrderItems).
EAN string EAN of the product.
OfferReference string Value provided by seller through Offer API as ‘ReferenceCode’.
Title string Title of the product as shown on the webshop.
Quantity integer Amount of the product being ordered.
OfferPrice decimal Price for the entire product amount. This means the Item Price multiplied by the Quantity.
LatestDeliveryDate decimal Result of the date the order was placed combined with the delivery promise made by the seller. This field has been renamed from “PromisedDeliveryDate”.
OfferCondition string Condition of the offer.
CancelRequest boolean True or False. True only if the consumer has cancelled the order before the seller has shipped it.

The Cancellations process

Within each order you receive, you will always have the value <CancelRequest>. This can either be True or False and will most often be False.

The value <CancelRequest> explained

A bol.com customer has the option to cancel his order. He can do this as long as the order is still open, this is anytime between placing the original order and the time at which you ship and confirm the order.

This means that at any time the value <CancelRequest> in the open order list could change, due to a request by the customer. Please always check this value before shipping, this to prevent accidentally shipping a customer cancelled order.

How to handle a customer cancelled order

When a customer decides to cancel his order and the value <CancelRequest> has been set to True, you have 2 ways of handling this request.

  • You can choose to ship the order anyway. This means the customer will receive an item he may not want. He can initiate the return process to send the item back.
  • You can choose to confirm his cancellation and not send any product at all. We will refund the payment to the customer.

One of either has to be chosen, a cancelled order requires a handle request from you as the seller.

Should you choose to ship it, this can be handled just like any other order. Please refer to the shipment request documentation.

If you choose to confirm the cancellation, please use the cancellation request.

Endpoint XSD

Download XSD for the orders-v2 endpoint below.

orders-v2.1 https://plazaapi.bol.com/services/xsd/orders-v2.1.xsd
cancel-order-v2 https://plazaapi.bol.com/services/xsd/cancel-order-v2.xsd