Shipments v2

Get shipments

Retrieve sent shipments. Shipments are sorted by date, descending.

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:

  • FBR
  • FBB
  • ALL

by default only FBR shipments are shown.

Example Request and Response #1 – default

Default shows only your own shipments.

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 showing all fulfilment by bol.com shipments.

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 each OrderItem you wish to ship. This is also the case when you wish to ship multiple orderitems within one single “package”. In that case you can use the same Transporter details for each shipment.

Note: You can not update a created shipment, new inserts/updates for the same OrderItem will be ignored.

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

note: child element of <Transport>

List of available Transportercodes

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

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>

All shipments are registered and will receive PENDING status untill processed.

Verify shipment Succes/Failure

All OrderAPI requests are put on our queue and will be handled as soon as possible. Because of this you will not receive immediate feedback on it’s Succes or Failure. It’s is therefore critical 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 above)

Warning: Failed shipments will not be processed and are auto-cancelled after 8 days. Possible resulting in lost profit.

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

  • PENDING
  • FAILURE
  • TIMEOUT
  • SUCCESS

More information on the process-status endpoint.

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

More information on the process-status endpoint.

Endpoint XSD

Download XSD for shipments-v2 endpoint.