Shipments v2

Get shipments

Retrieve sent shipments. Shipments are sorted by date in descending order.

GET /services/rest/shipments/v2
 

Parameters

Name Type Description
page integer Default value = 1 (every page lists 10 shipments).
fulfilmentmethod string Specifies whether this shipment has been fulfilled by the seller (FBR) or by bol.com (FBB).

Possible values (by default only FBR shipments are shown):

  • FBR
  • FBB
  • ALL

Example Request and Response #1 – default (FBR)

Default shows only your own shipments, i.e. shipments fulfilled by the seller.

GET /services/rest/shipments/v2?page=1
Status: 200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Shipments xmlns="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
 <Shipment>
 <ShipmentId> </ShipmentId>
 <ShipmentDate> </ShipmentDate>
 <ExpectedDeliveryDate> </ExpectedDeliveryDate>
 <ShipmentItems>
 <ShipmentItem>
 <OrderItem>
 <OrderItemId> </OrderItemId>
 <OrderId> </OrderId>
 <OrderItemSequenceNumber> </OrderItemSequenceNumber>
 <OrderDate> </OrderDate>
 <PromisedDeliveryDate> </PromisedDeliveryDate>
 <EAN> </EAN>
 <Title> </Title>
 <Quantity> </Quantity>
 <OfferPrice> </OfferPrice>
 <OfferCondition> </OfferCondition>
 <OfferReference> </OfferReference>
 <FulfilmentMethod> </FulfilmentMethod>
 </OrderItem>
 </ShipmentItem>
 </ShipmentItems>
 <Transport>
 <TransportId> </TransportId>
 <TransporterCode> </TransporterCode>
 </Transport>
 <CustomerDetails>
 <SalutationCode> </SalutationCode>
 <FirstName> </FirstName>
 <Surname> </Surname>
 <Streetname> </Streetname>
 <Housenumber> </Housenumber>
 <ZipCode> </ZipCode>
 <City> </City>
 <CountryCode> </CountryCode>
 <Email> </Email>
 </CustomerDetails>
 </Shipment>
</Shipments>

Example Request and Response #2 – FBB

Shows the usage of the fulfilment parameter. In this case it shows all shipments concerning fulfilment by bol.com.

GET /services/rest/shipments/v2?page=1&fulfilmentmethod=fbb
Status: 200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Shipments xmlns="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
 <Shipment>
 <ShipmentId>906230168</ShipmentId>
 <ShipmentDate>2016-11-16T21:23:46.000+01:00</ShipmentDate>
 <ExpectedDeliveryDate>2016-11-18+01:00</ExpectedDeliveryDate>
 <ShipmentReference>0001234567</ShipmentReference>
 <ShipmentItems>
 <ShipmentItem>
 <OrderItem>
 <OrderItemId>201612345</OrderItemId>
 <OrderId>4041234567</OrderId>
 <OrderItemSequenceNumber>1</OrderItemSequenceNumber>
 <OrderDate>2016-11-16T19:50:11.000+01:00</OrderDate>
 <PromisedDeliveryDate>2016-11-17+01:00</PromisedDeliveryDate>
 <EAN>9781408845646</EAN>
 <Title>Harry Potter and the Philosopher's Stone Illustrated Edition</Title>
 <Quantity>1</Quantity>
 <OfferPrice>25.95</OfferPrice>
 <OfferCondition>NEW</OfferCondition>
 <FulfilmentMethod>FBB</FulfilmentMethod>
 </OrderItem>
 </ShipmentItem>
 </ShipmentItems>
 <Transport>
 <TransportId>13234567</TransportId>
 <TransporterCode>TNT</TransporterCode>
 <TrackAndTrace>3SBOLD1234567</TrackAndTrace>
 </Transport>
 <CustomerDetails>
 <SalutationCode>03</SalutationCode>
 <FirstName>Bolina</FirstName>
 <Surname>Jansen</Surname>
 <Streetname>bol.comweg</Streetname>
 <Housenumber>51</Housenumber>
 <ZipCode>1234 AB</ZipCode>
 <City>Utrecht</City>
 <CountryCode>NL</CountryCode>
 <Email>nepemail@verkopen.bol.com</Email>
 </CustomerDetails>
 </Shipment>

Create a shipment

You need to create a shipment for every single OrderItem you wish to ship. This is also the case when you wish to ship multiple OrderItems within one order. In that case you can use the same Transporter details for each shipment.

Note: You cannot update a created shipment; new inserts/updates for the same OrderItem will be ignored. However, it is possible to insert the transporter and/or track & trace code after the initial shipment through the transports endpoint but this can also NOT be updated. Once inserted, this value will be final.

POST /services/rest/shipments/v2
 

Input

Name Type Description
OrderItemId string Required. Item being sent. OrderItemID can be retreived through the order request.
ShipmentReference string Used for administration purposes. This value corresponds with the reference in the payments request.

Note: 100 character maximum

DateTime dateTime ISO 8601 Required. Specifies when the article was sent. Format: YYYY-MM-DDThh:mm:ss.sTZD
ExpectedDeliveryDate dateTime ISO 8601 Required. Used to manage expectations towards customer. Format: YYYY-MM-DDThh:mm:ss.sTZD
TransporterCode string Specifies transporter used to handle this shipment. Can also be added later through the transporter endpoint.

Attention: Please leave this entire field out if you plan on entering this information later through the transport endpoint. Once added, it cannot be changed.

Note: child element of <Transport>

TrackAndTrace string Specifies track & trace code connected to this shipment. Can also be added later through the transporter endpoint.

Warning: This field is checked for a valid track&trace code. If you do not have the code, please omit this attribute entirely!

Attention: Please leave this entire field out if you plan on entering this information later through the transport endpoint. Once added, it cannot be changed.

Note: child element of <Transport>

Example request

<ShipmentRequest xmlns="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
 <OrderItemId>1234567890</OrderItemId>
 <ShipmentReference>A321SR</ShipmentReference>
 <DateTime>2016-02-17T17:30:00+01:00</DateTime>
 <ExpectedDeliveryDate>2016-02-18T15:00:00+01:00</ExpectedDeliveryDate>
 <Transport>
   <TransporterCode>TNT</TransporterCode>
   <TrackAndTrace>3SBOL0987654321</TrackAndTrace>
 </Transport>
</ShipmentRequest>

Example response

Status: 201 created

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:ProcessStatus xmlns:ns1="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
 <ns1:id>1</ns1:id>
 <ns1:sellerId>1084486</ns1:sellerId>
 <ns1:entityId>1234567890</ns1:entityId>
 <ns1:eventType>CONFIRM_SHIPMENT</ns1:eventType>
 <ns1:description>Confirm shipment for order item 1234567890.</ns1:description>
 <ns1:status>PENDING</ns1:status>
 <ns1:createTimestamp>2016-02-17T17:30:00.142+01:00</ns1:createTimestamp>
 <ns1:Links>
   <ns1:link ns1:method="GET" ns1:href="https://plazaapi.bol.com/services/rest/process-status/v2/1234567" ns1:rel="self"/>
 </ns1:Links>
</ns1:ProcessStatus>

Note: All shipments are registered and will receive PENDING status until processed.

Create a shipment with a shipping-label

Creates a shipment with a shipping-label as created through the shipping-label endpoint. Please note that if you wish to use a shipping-label for your shipment, you need to add this when creating a new shipment because this cannot be added later.

POST /services/rest/shipments/v2

Input

Naam Type Omschrijving
OrderItemId string Required. Item being sent. OrderItemId can be retrieved through an order request.
ShipmentReference string Used for administration purposes. This value corresponds with the reference in the payments request.

Note: 100 character maximum

DateTime dateTime ISO 8601 Required. Specifies when the article was sent. Format: YYYY-MM-DDThh:mm:ss.sTZD
ExpectedDeliveryDate dateTime ISO 8601 Required. Used to manage expectations towards customer. Format: YYYY-MM-DDThh:mm:ss.sTZD
ShippingLabelCode string Specifies shipping-label to be used for this shipment. This can be retrieved through the shipping-label endpoint.

Example request

<ShipmentRequest xmlns="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
 <OrderItemId>1234567891</OrderItemId>
 <ShipmentReference>B321SR</ShipmentReference>
 <DateTime>2016-02-17T17:30:00+01:00</DateTime>
 <ExpectedDeliveryDate>2016-02-18T15:00:00+01:00</ExpectedDeliveryDate>
 <ShippingLabelCode>PLR00000002</ShippingLabelCode>
</ShipmentRequest>

Example response

Status: 201 created

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:ProcessStatus xmlns:ns1="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
 <ns1:id>2</ns1:id>
 <ns1:sellerId>1084486</ns1:sellerId>
 <ns1:entityId>1234567891</ns1:entityId>
 <ns1:eventType>CONFIRM_SHIPMENT</ns1:eventType>
 <ns1:description>Confirm shipment for order item 1234567891.</ns1:description>
 <ns1:status>PENDING</ns1:status>
 <ns1:createTimestamp>2016-02-17T17:30:00.142+01:00</ns1:createTimestamp>
 <ns1:Links>
   <ns1:link ns1:method="GET" ns1:href="https://plazaapi.bol.com/services/rest/process-status/v2/2" ns1:rel="self"/>
 </ns1:Links>
</ns1:ProcessStatus>

Note: More information on the process-status endpoint.

Verify shipment Succes/Failure

All Order API requests enter our queue and will be handled as soon as possible. As it takes time for the shipment to be processed, you will not receive immediate feedback on it’s Succes or Failure. Therefore, it is is essential that you check the status of your shipment after sending your shipment request. This status can be checked using the process-status endpoint. Information to check the required endpoint is supplied in the Response for the shipment (see ‘example response’ above)

Warning: Failed shipments will not be processed and are auto-cancelled after 8 days!

GET /services/rest/process-status/v2/1234567

Example response

Status: 200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:ProcessStatus xmlns:ns1="https://plazaapi.bol.com/services/xsd/v2/plazaapi.xsd">
 <ns1:id>1234567</ns1:id>
 <ns1:sellerId>1234567</ns1:sellerId>
 <ns1:entityId>987654321</ns1:entityId>
 <ns1:eventType>CONFIRM_SHIPMENT</ns1:eventType>
 <ns1:description>Confirm shipment for order item 987654321.</ns1:description>
 <ns1:status>FAILURE</ns1:status>
 <ns1:errorMessage>The item is already shipped or cancelled.</ns1:errorMessage>
 <ns1:createTimestamp>2016-11-14T09:34:41.000+01:00</ns1:createTimestamp>
 <ns1:Links>
 <ns1:link ns1:method="GET" ns1:href="https://plazaapi.bol.com/services/rest/process-status/v2/1234567" ns1:rel="self"/>
 </ns1:Links>
</ns1:ProcessStatus>

Possible Statuses are listed below. Check the process-status endpoint page for more information.

  • PENDING
  • FAILURE
  • TIMEOUT
  • SUCCESS

Endpoint XSD

Download XSD for the shipments-v2 endpoint below.

shipments-v2 https://plazaapi.bol.com/services/xsd/shipments-v2.xsd