Chatbots
Our API allows you to retrieve the current status of an order or parcel in any kind of customer facing widget, like chatbots, with a single HTTPS call.
Request Definition
These requests allow you to get all updates with a single HTTPS request and are tailored to customer-facing widgets, like server-side chatbots (that is: access from trusted sources).
You can retrieve order information through these APIs using the order number, tracking number, and email address. Based on the request query parameters, the number of corresponding parcels included in the response can differ. Nonetheless, the response structure will always look identical. Each successful response body will have an order list (array), which always contains one or multiple orders. Each order has an order number attribute and a parcel list (array), which contains one or multiple parcel information objects.
Get Orders
Details of how the orders/bot endpoint can be used to retrieve orders in the parcelLab system are described below.
Response Definition
The response definition for the APIs is described in the following sections.
Orders
A successful response always returns a JSON object containing an order list. Each order list/order contains a list of parcels which can contain one or multiple parcels, depending on the request type (that is: order number or tracking number).
The following shows an example of the structure of a response.
{
"orders": [
{
"orderNo": "123456789",
"parcels": [{...}]
}
]
}Parcel Object
A parcel object contains information about the current status of a tracking.
The attributes for a parcel object are described in the following table.
id
String
The internal parcelLab ID of the tracking.
tracking_number
String
The tracking number of the tracking.
delay
Boolean
Whether a delay of this delivery has been detected by parcelLab.
exception
Boolean
Whether an escalated problem has been detected by parcelLab.
isReturn
Boolean
Whether the end-customer is returning the parcel.
delivery_location
String
The location of the delivery.
Note: This is set to null if the tracking did not reach Delivered status.
Action Box Object
The additional details in the action box object are type-specific (for example: if the actionBox.type === 'pickup-location', the action box will also feature a new key with the openingHours).
The variations available are described in the following sections.
Type prediction
predictionFor a prediction, a sub document is included with the scheduled delivery date. This is displayed in the format below.
"actionBox": {
"type": "prediction",
"label": "Estimated Delivery:",
"info": {
"dateOfMonth": "08",
"dayOfWeek": "Saturday",
"month": "January",
"caption": "The delivery has been planned by IKEA."
},
"servicePluginLabel": "In transit, estimated delivery at 08 January",
"color": "#fca103",
"colorPriority": 2
}Type pickup-location
pickup-locationFor a delivery to be collected, a sub document is included with the opening hours. This is displayed in the format below.
"actionBox": {
"type": "pickup-location",
"address": "Filiale Gneisenaustr. 40, 10961 Berlin",
"info": {
"openingHours": [
{
"close": {
"day": 1,
"time": "1830"
},
"open": {
"day": 1,
"time": "1000"
}
},
...
]
},
"servicePluginLabel": "Ready for pickup at location Filiale Gneisenaustr. 40, 10961 Berlin",
"color": "#16c922",
"colorPriority": 3
}Type pickup-location-unknown
pickup-location-unknownThis type is for a delivery ready for pickup but where the pickup location could not be determined by parcelLab. This is displayed in the format below.
"actionBox": {
"type": "pickup-location-unknown",
"label": "You can find details where to collect your package on DHLs website",
"servicePluginLabel": "Ready for pickup"
"color": "#16c922",
"colorPriority": 3
}Type vote-courier
vote-courierThis type is for parcels that have been delivered that show a voting option to the user. This is displayed in the format below.
"actionBox": {
"type": "vote-courier",
"label": "Were you satisfied with the performance of DHL?",
"label_communication": "Were you satisfied with the communication during the shipment?"
"servicePluginLabel": "Delivered to Doorstep"
"color": "#16c922",
"colorPriority": 3
}Type next-action
next-actionThis type is for parcels that could not be delivered where a next action can be provided based on the courier. This is displayed in the format below.
"actionBox": {
"type": "next-action",
"label": "Unfortunately, the goods could not be delivered.",
"caption": "The delivery agent will try again the next working day.",
"servicePluginLabel": "Delivery unsuccessful, next attempt tomorrow"
"color": "#fca103",
"colorPriority": 2
}Type order-processed
order-processedThis type is for orders that have been sent to parcelLab via the /order ( or /presage ) endpoint but were still not updated with tracking number or courier data. This is displayed in the format below.
"actionBox": {
"type": "order-processed",
"label": "Order is prepared for shipping and will be handed to DHL shortly.",
"servicePluginLabel": "Order prepared for shipping",
"color": "#fca103",
"colorPriority": 2
}Type returned
returnedThe following return types are for parcels that have been returned, which can vary and include a return reason:
This is displayed in the format below.
"actionBox": {
"type": "returned",
"label": "The package will be returned to the sender.",
"servicePluginLabel": "Failed delivery: Not collected",
"color": "#c91f16",
"colorPriority": 1
}Type live-tracking
live-trackingThis type is for parcels that are out for delivery and have a link to a live tracking of the courier delivery. The link can be found in the tracking URL of the courier object. This is displayed in the format below.
"actionBox": {
"type": "live-tracking",
"label": "Out for delivery",
"caption": "The goods will be delivered today.",
"info": {
"city": "München",
"destination_country_iso3": "GER"
}
"servicePluginLabel": "The goods will be delivered today.",
"color": "#fca103",
"colorPriority": 2
}Type fallback
fallbackThis type is for special cases where the actionBox can be empty. This is displayed in the format below.
"actionBox": {},Courier Object
The details of the courier object for each tracking are described in the following table.
name
String
The courier code (for example: dhl-germany).
prettyname
String
The display name of the courier to be displayed (for example: DHL).
trackingurl
String
The URL of the courier's own tracking page.
trackingurl_label
String
The localized label of thetrackingurl.
hide_trackingurl
Boolean
Whether to hide the tracking URL.
rerouteurl
String
The URL of the courier's own tracking page in case the recipient reroutes the order.
rerouteurl_label_short
String
The localized short label of the rerouteurl.
rerouteurl_label_long
String
The localized long label of the rerouteurl.
rerouteurl_label_info
String
The localized information regarding the rerouteurl.
destination_courier
Object
Information regarding the final courier handling the parcel.
branded_tracking_url
String
URL of the branded order status page on the retailers shop
Last Delivery Status Object
The details of the last delivery status object for each tracking are described in the following table.
status
String
A short description of the current status of the delivery.
status_details
String
A detailed description of the current status of the delivery.
code
String
The applicable parcelLab status code.
Reporting Object
The reporting details are specific to the last delivery status (for example: if the last_delivery_status === 'delivered', lead time details are visible, which would not be visible for other delivery status).
The details of the reporting object of the last delivery status are described in the following table.
invalid
Boolean
Whether the shipment has an invalid ID.
forgotten
Boolean
Whether it was a forgotten delivery.
delayed
Boolean
Whether the delivery was delayed.
failedAttempt
Boolean
Whether there was a failed attempt to deliver the parcel.
dispatchDelayed
Boolean
Whether the dispatch has been delayed.
leadTimeExceeded
Boolean
Whether the lead time has been exceeded.
timeWindowMissed
Boolean
Whether the announced delivery time has been missed.
escalated
Boolean
Whether there was an exception as part of the delivery (for example: a problem in scanning the delivery address on the parcel).
returned
Boolean
Whether the parcel has been returned to the customer because of a failed delivery.
customerPromiseExceeded
Boolean
Whether the customer's requested delivery date at checkout has been exceeded.
contacted
Boolean
Whether the customer was contacted.
contactedwithMessages
Array
A list of messages sent to the customer.
contactedAndBounce
Boolean
Whether any messages sent to the customer bounced.
exception_messages
Array
A list of exception messages.
lead_time
Int
The lead time.
lead_time_first_attempt
Int
The lead time at the first delivery attempt.
lead_time_door_to_door
Int
The lead time door to door.
lead_time_dispatch_delta
Int
The lead time from send date until in transit date.
lead_time_since_order
Int
The lead time since order date.
lead_time_to_inbound
Int
The lead time from pickup to in transit.
lead_time_order_till_send
Date/DateTime
The lead time from order to announced send date.
lead_time_order_till_inbound
Date/DateTime
The lead time from order to in transit.
in_transit_date
Date/DateTime
The in transit date.
courier_dropoff_date
Date/DateTime
The courier drop off date.
part_of_day
String
The part of the day of the delivery (that is: AM/PM).
pickup_date
Date/DateTime
The pickup date.
delivery_location
String
The delivery location.
Checkpoint Object
The details of the checkpoint object for each tracking are described in the following table.
shown
Boolean
Whether the checkpoint has been marked as unclear by parcelLab.
Note: Checkpoints provided by the courier which are unclear and do not help the recipient to understand the current status of the delivery are automatically filtered.
status
String
The applicable parcelLab status code.
status_text
String
A short description of the current status of the delivery.
status_details
String
A detailed description of the current status of the delivery.
full_courier_status
String
The full status code provided by the courier for reference.
Note: This is not recommended to display to the recipient.
location
String
The location of the checkpoint if available; otherwise an empty string "" is returned.
Delivery Information Object
The details of the delivery information object for each tracking are described in the following table.
street
String
The street of the parcel's destination.
zip_code
String
The zip code of the parcel's destination.
city
String
The city of the parcel's destination.
destination_country_iso3
String
The country code of the parcel's destination.
articles
Array
A list of articles contained in this parcel (if transmitted to parcelLab).
consignmentNo
String
The consignment number identifying the parcel.
Delivery Location Object
The delivery location code represents the type of delivery destination a parcel was delivered to by the courier (for example: doorstep, post box and so on).
Last updated
Was this helpful?