Order/Warehouse Events

Our API provides you with great flexibility and scope to retrieve and send data as you need. In this case, sending a custom event/checkpoint to be displayed in the order status history for a tracking.

Send Custom Events

Details of how the shop-event endpoint can be used to send custom events in the parcelLab system are described below.

POST Send Custom Events

You can send custom events (that is: about the order, consignment, payment and so on) in the parcelLab system using the shop-event endpoint.

To use this API, you need your parcelLab user_id and API token for authentication.

The details of the Send Custom Events API are described in the following section.

API Details

POST https://api.parcellab.com/shop-event

Header

Name	Type	Description
user	number	parcelLab user ID
token	string	parcelLab API token
content-type	string	'application/json'

Request Body

Name	Type	Description
courier	string	parcelLab courier code (for example: ups or dhl).
tracking_number	string	Tracking number
location	string	The location of the event.
event	string	Any custom event message describing a status (for example: the status codes as specified in the parcelLab tracking status model).
timestamp	string	The date/time of the event in ISO 8601 format: YYYY-MM-DD[T]HH:mm:ss.SSSZ.

Responses

• 200 - accepted

Allowed API Payload Structures

This API accepts request bodies (payloads) to update via multiple reference numbers. The provided payload always must contain:

• The timestamp of the event in ISO 8601 format YYYY-MM-DD[T]HH:mm:ss.SSSZ.

• The event can be any internal code describing a status that will be mapped by the parcelLab team.

• Optional location of the event as any clear text string.

Via Courier and Tracking Number

To update a specific tracking via providing the original courier code and tracking number, your payload must include the following:

• The courier in the parcelLab format.

• The tracking_number as listed in the parcelLab system.

Courier and Tracking Number Example

In this example, you would send a webhook similar to the below.

{
    "courier": "dhl-germany",
    "tracking_number": "00340001612264742802",
    "timestamp": "2021-04-09T16:12:00.000Z",
    "location": "Munich, Germany",
    "event": "internalEvent-Dispatched"
}

Via Courier and Transport Number

If the provided event should be applied to multiple trackings on a single transport, the payload can be changed to include the following:

• The courier in the parcelLab format.

• The transportNo as listed in the parcelLab system for one or multiple trackings.

Courier and Transport Number Example

In this example, you would send a webhook similar to the below.

{
    "courier": "dhl-germany",
    "transportNo": "T000001",
    "timestamp": "2021-04-09T16:12:00.000Z",
    "location": "Munich, Germany",
    "event": "internalEvent-Dispatched"
}

Via Order Number

Events can also be attached to any order. For this, the identification key is orderNo, which can be included in your payload as listed in the parcelLab system.

Order Number Example

In this example, you would send a webhook similar to the below.

{
    "courier": "dhl-germany",
    "orderNo": "0012345",
    "timestamp": "2021-04-09T16:12:00.000Z",
    "location": "Munich, Germany",
    "event": "internalEvent-Dispatched"
}

Send Status Updates for Custom Couriers

Details of how the hook-custom-courier endpoint can be used to send status updates for custom couriers in the parcelLab system are described below.

POST Checkpoint for a Custom Courier

You can push a status update (that is: checkpoint) for a custom courier, which has been created implicitly by specifying its code at the track endpoint with the hook-custom-courier endpoint.

To use the API, the following keys are required:

• The custom courier needs to be identified with the same code as used for the track endpoint.

• The tracking_number as specified for a custom courier tracking.

• The event can be any internal code describing a status that will be mapped by the parcelLab team.

• The timestamp of the event in ISO 8601 format: YYYY-MM-DD[T]HH:mm:ss.SSSZ.

Note: The location key is optional and can be any string (for example: Munich, DE).

The details of the Update Checkpoint for a Custom Courier API are described in the following section.

API Details

POST https://api.parcellab.com/hook-custom-courier

Header

Name	Type	Description
content-type	string	'application/json'

Request Body

Name	Type	Description
courier*	string	parcelLab courier code (for example: ups or dhl), which needs to be the same code as used for the track endpoint.
tracking_number*	string	The tracking number as specified for the custom courier tracking.
location	string	The location of the event.
timestamp*	string	The date/time in ISO 8601 format: YYYY-MM-DD[T]HH:mm:ss.SSSZ.
event*	string	Any custom event message describing a status (for example: the status codes as specified in the parcelLab tracking status model).

Responses

• 200 - accepted

An example request is displayed below to show the format for updating a checkpoint for a custom courier.

curl --location 'https://api.parcellab.com/hook-custom-courier’ \
  --header content-type: application/json' \
  --data ‘{
       "courier": "ehlert",
       "tracking_number": "AB123",
       "event": "Delivered Doorstep",
       "timestamp": "2016-01-01T22:22:22:000Z",
       "location": "Berlin, DE"
}’

POST Checkpoint for a Custom Courier via Order Number

You can push a status update (that is: checkpoint) for a custom courier with the hook-custom-courier endpoint, identifying the corresponding tracking number through the combination of the user_id and orderNo.

To use the API, the following keys are required:

• The user_id of the account owning the tracking either in numerical or hashed format.

• The orderNo of the tracking specified when creating.

• The event can be any internal code describing a status that will be mapped by the parcelLab team.

• The timestamp of the event in ISO 8601 format: YYYY-MM-DD[T]HH:mm:ss.SSSZ.

Note: The location key is optional and can be any string (for example: Munich, DE).

The details of the Update Checkpoint for a Custom Courier via Order Number API are described in the following section.

API Details

POST https://api.parcellab.com/hook-custom-courier

Header

Name	Type	Description
content-type	string	'application/json'

Request Body

Name	Type	Description
user_id*	string	The user ID of the account associated with the corresponding tracking either in numerical or hashed format.
orderNo*	string	The order number of the corresponding tracking as specified when creating.
location	string	The location of the event.
timestamp*	string	The date/time in ISO 8601 format: YYYY-MM-DD[T]HH:mm:ss.SSSZ.
event*	string	Any custom event message describing a status (for example: the status codes as specified in the parcelLab tracking status model).

Responses

• 200 - accepted

An example request is displayed below to show the format for updating a checkpoint for a custom courier.

curl --location 'https://api.parcellab.com/hook-custom-courier’ \
  --header content-type: application/json' \
  --data ‘{
       "user_id": "OWI=",
       "orderNo": "ORD-123",
       "event": "Delivered Doorstep",
       "timestamp": "2016-01-01T22:22:22:000Z",
       "location": "Berlin, DE"
}’