Central model of the interfaces described here is a tracking. A tracking is one single delivery to a customer, identified by its courier and tracking_number.

Tracking

Required Keys

All required keys must be supplied with every request.

Key Type Description Used for
courier Courier code short code of the courier (e.g. dhl-germany) identifier
tracking_number String tracking number of the delivery identifier
zip_code String postal code search and portal
destination_country_iso3 ISO 3166-1 alpha-3 ISO3 of destination country (e.g. DEU for Germany) search and portal

Key required for multiple shops

If several shops (e.g. shops with multiple domains, dedicated shops for specific countries, or otherwise individual CI) are used within one account, trackings are assigned to a shop using the key client.

Key Type Description Used for
client String client (Mandant in German) of the tracking, which can be used if notifications should be sent out in the name of different shops reports and customer notification

Keys required for notifications

To be able to send out sensible notifications to customers, following keys are required/ strongly recommended.

Key Type Description Used for
recipient_notification String name of the recipient used in notifications customer notification
email String email of recipient customer notification
street String street address of delivery search and portal
city String city of delivery search and portal
phone String phone number of recipient customer notification
language_iso3 ISO 639-1 ISO code of language used by recipient (e.g. de for German) customer notification

Special Keys

These special keys alter how the system handles the trackings.

Key Type Description Used for
return Boolean if true delivery will be handled as a return, i.e. by default no communication is sent to the set recipient, dispatch delays will not be monitored, and the tracking will not be considered for general reporting return labels which are provided to end customers
cancelled Boolean if true delivery is cancelled, i.e. no communication is sent to the set recipient, all monitoring and reporting is disabled cancelled shipments, i.e. “Stornos”

Optional keys

Further keys can be used to further individualize notifications.

Key Type Description Used for
recipient String name of the recipient shown in portal search and portal
deliveryNo String internal delivery number search and portal
customerNo String internal customer number search and portal
orderNo String internal order number search and portal
order_date YYYY-MM-DD or YYYY-MM-DD HH:mm:ss date of ordering by customer reports
send_date YYYY-MM-DD or YYYY-MM-DD HH:mm:ss announced dispatch/ send date automatic monitoring of dispatch in time (ticket)
weight String weight of the package reports
courierServiceLevel String product or service level from courier reports
warehouse String warehouse from where delivery was shipped reports
articles Object [{}] complex list of articles as an array of objects (see below) customer notification
market String marketplace used for sale reports and customer notification
complete Boolean whether the shipment is complete customer notification
upgrade Boolean whether the shipment has an upgrade or individualisation customer notification
cashOnDelivery Number the C.O.D. (Nachnahme) amoount customer notification
statuslink String alternative status link (not versand-status.de) customer notification

Object «list of articles»:

A list of articles allows to specifiy the detailed contents of a delivery by defining for each item in the list the quantity, article number, and article name. A list of articles looks like this:

[
  {
    articleNo:        'article number (String)',            // required
    articleName:      'article name (String)',              // required
    articleCategory:  'article category (String)',          // optional
    articleUrl:       'url to the product page (String)',   // optional
    articleImageUrl:  'full url to image (String)',         // optional
    quantity: Integer,                                      // optional
  },
  ...
]

Supported Couriers

A large number of couriers is supported with parcelLab. The most used are:

Courier Courier code
DHL dhl-germany
Hermes hermes-de
DPD dpd-de
UPS ups
GLS gls

For further courier codes, please contact the parcelLab Team.

Tracking Status Model

A tracking can be in different status, e.g. when retrieved from the API to display within the shop system. The status are:

Status code Description
OrderProcessed The submitted order_date if available, else the import to parcelLab
PickUpScheduled Tracking number has been registered with the courier
InboundScan First scan in sorting facility of courier, i.e. delivery process started
InTransit Delivery arrived at an intermediary hub
ExportHub Delivery is being prepared for export
ImportHub Import of delivery is being processed
DestinationDeliveryCenter Larger delivery center close to delivery location, sometimes followed by a delivery depot
DestinationDeliveryDepot Smaller delivery center close to delivery location
Scheduled A delivery announcement has been made by the courier
OutForDelivery Loaded onto delivery truck (last mile)
Rerouted Parcel has been rerouted due to logistical reasons or recipients’ request
FailedAttemptFirst First attempt of delivery failed because recipient was not met
FailedAttemptSecond Second attempt of delivery failed because recipient was not met
FailedAttemptFinal Third and last attempt of delivery failed because recipient was not met
PickupReadyToday Parcel is ready for pickup at parcel locker or parcel shop as of now
PickupReadyNextDay Parcel is ready for pickup at parcel locker or parcel shop at the next working day if not specified otherwise in notification card
Delivered Delivery successful, no further scan will follow (could be also ready for pickup at neighbor or home deposit)
Exception A problem occurred during delivery
Stored Parcel is temporarily stored by courier due to logistical reasons or recipients’ request
Return Parcel is being returned due to an exception or because it could not be delivered