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.

Sending custom shop events is tailored towards extending the lifecycle of a delivery with additional information of an order or consignment. Those events are shown to customers both on the order status page, and they can be used to trigger notifications.

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 (optional)	The location of the event.
event	string	Please see a list of supported events below., For more information, contact your parcelLab representative.
timestamp	string	The date/time of the event in ISO 8601 format: YYYY-MM-DD[T]HH:mm:ss.SSSZ.

Responses

• 200 - accepted

Using the deduplicate parameter (optional)

If you observe duplicated events that should only be displayed once for tracking statuses (for example: in case the system sending your data cannot guarantee unique timestamps for events), you can use the query parameter deduplicate to ensure that duplicated events are not displayed for a tracking's status in the App.

Parcel status displaying duplicated events for a tracking

Parcel status without duplicated events

To use the deduplicate parameter:

• Append the query string deduplicate=true to the URL when sending custom events to parcelLab (that is: https://api.parcellab.com/shop-event?deduplicate=true).

The parcelLab system uses the message and location keys to enforce uniqueness, so that duplicated events are not displayed in the parcel status for trackings in the App.

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

Supported Event Messages

Find details below on the supported values for the event key by category.

Warehouse Events

To provide additional information about the first mile (that is: the warehouse progress to the customer), use any of the events below.

These warehouse events do not reflect a formal lifecycle and should be considered optional events. There is no need to follow this sequence or to use all events. You can choose the event that reflects best the status update you are looking to communicate. There is no reporting or exception handling on those events, they are purely informational.

Event	Description
WarehousePending	The order was transferred to the warehouse.
WarehousePrepared	The delivery is being prepared.
WarehouseDelay	Preparation of the delivery in the warehouse has been delayed, which will cause dispatch to be later than expected.
LabelPrinted	The shipping documents were printed.
Packed	The delivery has been packed in the warehouse.
Loaded	The shipment has been loaded in the dispatch department.

Carrier Events

If required and for certain situations, you can also explicitly set the status that would usually be provided by the carrier. This is only recommended in the case of own fleet, in-store orders and so on, where you control the delivery process. For more details on those events, see our Status Model.

Event	Description
PickUpScheduled	Label created; carrier pickup expected.
LabelPrinted	Label printed; preparing handover.
InboundScan	First scan into carrier network.
InTransit	Parcel moving within carrier network.
Exception-AddressIssue	Blocked due to address problem.
Exception-Damaged	Blocked because parcel damaged.
Rerouted	Parcel rerouted to a new route.
OutForDelivery	Courier out today to deliver.
FailedAttempt	Delivery attempt failed; will retry.
PickupReady	Ready for pickup at parcel shop.
Delivered	Delivered to non-specified location.
Delivered-Doorstep	Delivered to recipient at doorstep.
ReturnToSender	Failed delivery; being returned to sender.

Return Processing Events

To update customers on received returns use the events below. This is helpful as carrier events end with a delivery to the retailer's warehouse, however this typically does not constitute for the return actually being processed.

These warehouse events do not reflect a formal lifecycle and should be considered optional events. There is no reporting or exception handling on those events, they are purely informational. For a direct integration with your warehouse system and returns intake, see our dedicated Warehouse Events for Returns API.

Event	Description
ReturnInProcess	The returned package is being processed.
ReturnProcessed	The returned items have been processed.
ReturnRefunded	The refund of the returned and accepted items has been initiated and will be credited in a few days.