Scans and Status Events

Scans and status events describe physical scans of goods or events during the handling of the order.

Overview

Events happen during the delivery process, either through scans (for example: goods receipt scan at the warehouse) or events of the delivery (for example: confirmation of the planned delivery time via phone with the recipient).

When the information is received at parcelLab from the carrier scans, the process used ensures the best quality data is provided. The data is processed and communicated to your customers to keep them informed on the progress of their order. This involves matching the data against our internal triggers for emails, calculating transit times, and translating it to send the order updates via email to the customer and providing it on your Order Status page.

Structure of an Event

The structure of an event (this includes both scans and status events) is described in the following table.

Field	Value	Required?
Shipment	The shipment identifier (for example: barcode, order number or tracking number).	Required
Timestamp	The date and time of the event in format YYYY-MM-DD HH:mm:ss+-HH:mm.	Required
Location	The location of the event (for example: a depot or city).	Optional
StatusCode	The applicable status code.	Required
ReasonCode	The reason code for the Exception status code.	Required for Exception
Details	The details of the status, which is required for the Scheduled status code and optional for all others.	Required for Scheduled

Events can be transferred as .json or .xml, and via SFTP or the parcelLab API. See our status model for the list of available status codes, exception reasons, delivery location codes, and next actions.

Status Model

Send Status Events

Details of how the courier/events endpoint can be used to update the status of an individual delivery are described below.

POST Send Status Events

You can update the status of a delivery using the courier/events endpoint (that is: this endpoint would be called on a specific status or scan event).

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

API Details

POST https://api.parcellab.com/courier/events

Header

Name	Type	Description
token	string	Auth token for the courier provided by parcelLab
content-type	string	'application/json' or 'application/xml'

Request Body

Name	Type	Description
Events	array	JSON or XML as described below

Responses

• 200 - accepted

• 400 - if data is ill formatted, the response will describe the issue with the payload (for example: Invalid events, every "Event" needs a key "Shipment")

• 401 - if no or an invalid token is provided

Status events can be transmitted as shown below in the .json and .xml examples. The payload can alternatively be sent as a file via SFTP.

For further details on file transfers, see how you can send files to parcelLab.

events-info.json

{
    "shipment": "D000000000001",
    "event": {
        "timestamp": "02-02-2025 12:00:00.000",
        "location": "London",
        "status_code": "In Transit",
        "reason_code": "",
        "additional_details": "Weather"
    },
    "estimated_date_of_delivery": "02-02-2025 11:30:00"
}

events-info.xml

<?xml version=1.0 encoding=UTF-8?>
<Events>
  <Shipment>D000000000001</Shipment>
  <Event>
    <Timestamp>02-02-2025 12:00:00.000</Timestamp>
    <Location>London</Location>
    <StatusCode>InTransit</StatusCode>
    <ReasonCode></ReasonCode>
    <Details>Weather</Details>
  </Event>
  <EstimatedDeliveryDate>02-02-2025 11:30:00</EstimatedDeliveryDate>
</Events>

Example Payload/File

In this example, the payloads/files in .json and .xml show three different events with different status codes with reason codes and optional details.

sample-event-message.json

{
  "shipment": "D000000000001",
  "events": [
    {
      "timestamp": "02-02-2025 12:00:00.000",
      "location": "London",
      "status_code": "In Transit",
      "reason_code": "",
      "additional_details": "Weather"
    },
    {
      "timestamp": "02-02-2025 10:00:00.000",
      "location": "London",
      "status_code": "Exception",
      "reason_code": "ForceMajeure",
      "additional_details": "Weather"
    },
    {
      "timestamp": "02-02-2025 11:00:00.000",
      "location": "London",
      "status_code": "Delivered",
      "reason_code": "Doorstep",
      "additional_details": "Received by John Doe"
    }
  ],
  "estimated_date_of_delivery": "02-02-2025 11:30:00"
}

sample-event-message.xml

<?xml version=1.0 encoding=UTF-8?>
<Events>
  <Shipment>D000000000001</Shipment>
  <Event>
    <Timestamp>02-02-2025 12:00:00.000</Timestamp>
    <Location>London</Location>
    <StatusCode>InTransit</StatusCode>
    <ReasonCode></ReasonCode>
    <Details>Weather</Details>
  </Event>
  <Event>
    <Timestamp>02-02-2025 10:00:00.000</Timestamp>
    <Location>London</Location>
    <StatusCode>Exception</StatusCode>
    <ReasonCode>ForceMajeure</ReasonCode>
    <Details>Weather</Details>
  </Event>
  <Event>
    <Timestamp>02-02-2025 11:00:00.000</Timestamp>
    <Location>London</Location>
    <StatusCode>Delivered</StatusCode>
    <ReasonCode>Doorstep</ReasonCode>
    <Details>Received by John Doe</Details>
  </Event>
  <EstimatedDeliveryDate>02-02-2025 11:30:00</EstimatedDeliveryDate>
</Events>