Shipments v2.1

What’s new in version 2.1

  • We have introduced pagination for this endpoint for performance reasons.
  • We had to change the OrderId and OrderItemId fields from a Long to a String in order to comply with changes in our landscape.
  • You are now able to filter on order-id. This filter will return all previously made shipments based on the given OrderId.
  • 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 isn’t the case.

Looking for Shipments 2.0 documentation?

Get shipments 2.1

With this endpoint you are able to retrieve your shipments. The shipments will be sorted by date in descending order.

GET /services/rest/shipments/v2
 

Parameters

Name Type Description
page integer default value = 1
fulfilment-method 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 (FBR and FBB)
order-id string  ID for the order. This can be retrieved from the open order response (v2.0 or v2.1).

Accept-header

In order to use this endpoint, you need to add a specific Accept-header to your request (below).

application/vnd.shipments-v2.1+xml

Example Request and Response

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

GET /services/rest/shipments/v2?page=1&fulfilment-method=FBR
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>
    <ShipmentItems>
    <ShipmentItem>
      <OrderItem>
        <OrderItemId> </OrderItemId>
        <OrderId> </OrderId>
        <OrderDate> </OrderDate>
        <LatestDeliveryDate> </LatestDeliveryDate>
        <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>

What’s new in version 2.1 continued

  • We have removed the field ExpectedDeliveryDate due to the feedback we have received over the time.
  • The field DateTime has also been removed. The value given for this field was used as the created_at time for the shipment, it’s however easier to drop the field entirely and use the time of the request as the created_at time.]
  • The payload of the body has been modified to reflect the changes above. Another change is that the payload directs towards a new version of the XSD; <ShipmentRequest xmlns="https://plazaapi.bol.com/services/xsd/v2.1/plazaapi.xsd">

Create a shipment 2.1

You need to create a shipment for each OrderItem you wish to ship. This is also the case when you wish to ship multiple OrderItems within one order.

Warning: You cannot update a created shipment; new inserts/updates for the same OrderItem will be ignored!

Note: It is possible to insert the transporter and/or track & trace code at a later instance 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.

Note: 100 character maximum

TransporterCode string Specifies transporter used to handle this shipment. Can also be added later through the transporter endpoint

note: child element of <Transport>

List of available Transporter codes

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

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

note: child element of <Transport>

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

Accept-header

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

application/vnd.shipments-v2.1+xml

Example request

<ShipmentRequest xmlns="https://plazaapi.bol.com/services/xsd/v2.1/plazaapi.xsd">
 <OrderItemId>1234567890</OrderItemId>
 <ShipmentReference>A321SR</ShipmentReference>
 <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 untill processed.

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 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

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 retreived through the order request.
ShipmentReference string Used for administration purposes.

Note: 100 character maximum

ShippingLabelCode string Specifies shipping-label to be used for this shipment. Can be retrieved through the shipping-label endpoint.

Example request

<ShipmentRequest xmlns="https://plazaapi.bol.com/services/xsd/v2.1/plazaapi.xsd">
 <OrderItemId>1234567891</OrderItemId>
 <ShipmentReference>B321SR</ShipmentReference>
 <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>

Endpoint XSD

Download XSD for the shipments-v2 endpoint below.

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