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
OrderItemIdfields from a
Stringin 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.
|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).
Status: 200 OK <?xml version="1.0" encoding="UTF-8"?> <Orders xmlns="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd"> <Order> <OrderId>4123456789</OrderId> <DateTimeCustomer>2017-02-09T12:39:48.000+01:00</DateTimeCustomer> <DateTimeDropShipper>2017-02-09T12:39:48.000+01:00</DateTimeDropShipper> <CustomerDetails> <ShipmentDetails> <SalutationCode>02</SalutationCode> <Firstname>Billie</Firstname> <Surname>Van der Bol.com</Surname> <Streetname>Dorpstraat</Streetname> <Housenumber>1</Housenumber> <HousenumberExtended>B</HousenumberExtended> <ZipCode>1111 ZZ</ZipCode> <City>Utrecht</City> <CountryCode>NL</CountryCode> <Email>firstname.lastname@example.org</Email> <Company>bol.com</Company> </ShipmentDetails> <BillingDetails> <SalutationCode>02</SalutationCode> <Firstname>Billie</Firstname> <Surname>van der Bol.com</Surname> <Streetname>Dorpstraat</Streetname> <Housenumber>1</Housenumber> <HousenumberExtended>B</HousenumberExtended> <ZipCode>1111 ZZ</ZipCode> <City>Utrecht</City> <CountryCode>NL</CountryCode> <Email>email@example.com</Email> <Company>bol.com</Company> </BillingDetails> </CustomerDetails> <OrderItems> <OrderItem> <OrderItemId>2012345678</OrderItemId> <EAN>5412810182312</EAN> <OfferReference>BOLCOM00123</OfferReference> <Title>Basicxl - Rijdende Wekker - Kunststof - 16x11cm - Zwart</Title> <Quantity>1</Quantity> <OfferPrice>27.95</OfferPrice> <TransactionFee>5.18</TransactionFee> <LatestDeliveryDate>2017-02-10+01:00</LatestDeliveryDate> <OfferCondition>NEW</OfferCondition> <CancelRequest>false</CancelRequest> <FulfilmentMethod>FBR</FulfilmentMethod> </OrderItem> </OrderItems> </Order> </Orders>
OrderItem request values explained
||ID for the product (1 order can have multiple OrderItems).|
||EAN of the product.|
||Value provided by seller through Offer API as ‘ReferenceCode’.|
||Title of the product as shown on the webshop.|
||Amount of the product being ordered.|
||Price for the entire product amount. This means the Item Price multiplied by the Quantity.|
||Result of the date the order was placed combined with the delivery promise made by the seller. This field has been renamed from “PromisedDeliveryDate”.|
||Condition of the offer.|
||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.
Download XSD for the orders-v2 endpoint below.