Checkpoints

Our API allows you to retrieve the current status of a tracking or order with ease.

Get Checkpoints

Details of how the v2/checkpoints endpoint can be used to retrieve the checkpoints for a tracking in the parcelLab system are described below.

GET Checkpoints via Courier and Tracking Number

You can retrieve the checkpoints for a tracking using the courier and tracking_number with the v2/checkpoints endpoint.

The details of the Get Checkpoints via Courier and Tracking Number API are described in the following section.

API Details

GET https://api.parcellab.com/v2/checkpoints

Query Parameters

Name

Type

Description

tno

string

Tracking number

courier

string

Courier code

lang

string

Language in ISO 3166-1 alpha-3 format. Defaults to en.

An example request is displayed below to show the format for retrieving checkpoints via the courier and tracking number.

curl --location 'https://api.parcellab.com/v2/checkpoints/?tno=00340000000000000001&courier=dhl&lang=de

Responses

200 - accepted

An example successful response is displayed below to show the format for retrieving checkpoints.

{
  "header": [
    {
      "id": "579f6444b6a1bb4fbaab5610",
      "tracking_number": "00340000000000000001",
      "courier": {
        "name": "dhl-germany",
        "prettyname": "DHL",
        "trackingurl": "https://nolp.dhl.de/ne~~~00001",
        "trackingurl_label": "Klicken Sie hier für weitere Informationen zur Sendung."
      },
      "last_delivery_status": {
        "status": "Zugestellt",
        "status_details": "Die Ware wurde erfolgreich zugestellt.",
        "code": "Delivered"
      },
      "delay": false,
      "exception": false
    }
  ],
  "body": {
    "579f6444b6a1bb4fbaab5610": [
      {
        "shown": true,
        "status": "OrderProcessed",
        "status_text": "Bestellung verarbeitet",
        "status_details": "Die Bestellung wurde verarbeitet.",
        "full_courier_status": "If exists, date of order, else date of import to parcelLab",
        "location": "Sample City",
        "timestamp": "2015-08-10T15:18:27.000Z"
      }
    ]
  }
}

GET Checkpoints via Order Number

You can retrieve the checkpoints for a tracking using the orderNo and your user_id with the v2/checkpoints endpoint.

Note: If you want to include return trackings, add the &showReturns=true parameter. To only include active returns (returns portal labels or returns dropped off to the carrier), add &showActiveReturns=true instead. The response header will then include entries you can identify via header.delivery_info.isReturn.

The details of the Get Checkpoints via Order Number API are described in the following section.

API Details

GET https://api.parcellab.com/v2/checkpoints

Query Parameters

Name

Type

Description

user

number

parcelLab user ID

orderNo

string

Assigned order number

lang

string

Language as ISO 3166-1 alpha-3, defaults to en

showReturns

boolean

Optional: set to true to include return labels alongside forward shipments

showActiveReturns

boolean

Optional: set to true to include only active returns (returns portal labels or returns dropped off to carrier)

An example request is displayed below to show the format for retrieving checkpoints via the order number.

curl --location 'https://api.parcellab.com/v2/checkpoints/?user=USERID&orderNo=12ORDER34&lang=de’

Responses

200 - accepted

An example successful response is displayed below to show the format for retrieving checkpoints.

{
  "header": [
    {
      "id": "579f6444b6a1bb4fbaab5610",
      "tracking_number": "00340000000000000001",
      "courier": {
        "name": "dhl-germany",
        "prettyname": "DHL",
        "trackingurl": "https://nolp.dhl.de/ne~~~00001",
        "trackingurl_label": "Klicken Sie hier für weitere Informationen zur Sendung."
      },
      "last_delivery_status": {
        "status": "Zugestellt",
        "status_details": "Die Ware wurde erfolgreich zugestellt.",
        "code": "Delivered"
      },
      "delay": false,
      "exception": false
    }
  ],
  "body": {
    "579f6444b6a1bb4fbaab5610": [
      {
        "shown": true,
        "status": "OrderProcessed",
        "status_text": "Bestellung verarbeitet",
        "status_details": "Die Bestellung wurde verarbeitet.",
        "full_courier_status": "If exists, date of order, else date of import to parcelLab",
        "location": "Sample City",
        "timestamp": "2015-08-10T15:18:27.000Z"
      }
    ]
  }
}

GET Checkpoints via XID

You can retrieve the checkpoints for a tracking using the xid and your user_id with the v2/checkpoints endpoint.

The details of the Get Checkpoints via XID API are described in the following section.

API Details

GET https://api.parcellab.com/v2/checkpoints

Query Parameters

Name

Type

Description

user

number

User ID in parcelLab

xid

string

Assigned xid

lang

string

Language as ISO 3166-1 alpha-3, defaults to en

An example request is displayed below to show the format for retrieving checkpoints via XID.

curl --location 'https://api.parcellab.com/v2/checkpoints/?user=USERID&xid=12XID34&lang=de’

Responses

200 - accepted

An example successful response is displayed below to show the format for retrieving checkpoints.

{
  "header": [
    {
      "id": "579f6444b6a1bb4fbaab5610",
      "tracking_number": "00340000000000000001",
      "courier": {
        "name": "dhl-germany",
        "prettyname": "DHL",
        "trackingurl": "https://nolp.dhl.de/ne~~~00001",
        "trackingurl_label": "Klicken Sie hier für weitere Informationen zur Sendung."
      },
      "last_delivery_status": {
        "status": "Zugestellt",
        "status_details": "Die Ware wurde erfolgreich zugestellt.",
        "code": "Delivered"
      },
      "delay": false,
      "exception": false
    }
  ],
  "body": {
    "579f6444b6a1bb4fbaab5610": [
      {
        "shown": true,
        "status": "OrderProcessed",
        "status_text": "Bestellung verarbeitet",
        "status_details": "Die Bestellung wurde verarbeitet.",
        "full_courier_status": "If exists, date of order, else date of import to parcelLab",
        "location": "Sample City",
        "timestamp": "2015-08-10T15:18:27.000Z"
      }
    ]
  }
}

The return of a successful call of this endpoint gives a 200 OK status code and a JSON encoded response object. This object consists of a header and body.

Return Header

The header is an array that provides an overview of all trackings returned. When requesting the API with a combination of courier and tracking_number, the array will always have header.length === 1.

For authed requests, all standard return documents for returns created through parcelLab will be available in the header for the checkpoints endpoint.

The details of the header for each tracking are described in the following table.

Key

Type

Description

String

The ID of the tracking which serves as the key in the body.

tracking_number

String

The tracking number of the tracking.

courier

Object

Details about the courier.

last_delivery_status

Object

Details about the current status 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.

Courier Object

The details of the courier object for each tracking are described in the following table.

Key

Type

Description

name

String

The courier code (for example: dhl-germany).

prettyname

String

The display name of the courier (for example: DHL).

trackingurl

String

The URL of the courier's own tracking page.

trackingurl_label

String

The localized label of the trackingurl.

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.

Last Delivery Status Object

The details of the last delivery status object for each tracking are described in the following table.

For further information, see the complete list of status codes that can be used.

Key

Type

Description

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.

Return Body

The body is an object that provides an array of checkpoints for each tracking (identified by their id) in the header.

The details of the array for each tracking are described in the following table.

Key

Type

Description

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.

timestamp

String

The date and time of the checkpoint, formatted as Date.prototype.toJSON().

Get Tracking Details

Details of how the v2/tracking-details endpoint can be used to retrieve the details of a tracking in the parcelLab system are described below.

GET Tracking Details

You can retrieve all the status details of a tracking using the orderNo with the tracking-details endpoint.

For low volume requests, the v2/tracking-details endpoint retrieves the complete and latest status details of a delivery. As all data is being pulled synchronously, expect higher response times. For high volume calls, we require using the normal checkpoints API described above. The resulting JSON will have the same structure as the v2/checkpoints endpoint above but will feature more details for the action box (details below).

The details of the Get Tracking Details API are described in the following section.

API Details

GET https://api.parcellab.com/v2/tracking-details

Query Parameters

Name

Type

Description

orderNo

string

primary reference number of the order

lang

string

language as ISO 3166-1 alpha-3, defaults to en

Header

Name

Type

Description

user

number

parcelLab user ID

token

string

parcelLab API token

content-type

string

'application/json'

Responses

200 - accepted

An example successful response is displayed below to show the format for retrieving tracking details (same results as checkpoints above, with more details in the action box).

{
  "header": [
    {
      "id": "579f6444b6a1bb4fbaab5610",
      "tracking_number": "00340000000000000001",
      "courier": {
        "name": "dhl-germany",
        "prettyname": "DHL",
        "trackingurl": "https://nolp.dhl.de/ne~~~00001",
        "trackingurl_label": "Klicken Sie hier für weitere Informationen zur Sendung."
      },
      "last_delivery_status": {
        "status": "Zugestellt",
        "status_details": "Die Ware wurde erfolgreich zugestellt.",
        "code": "Delivered"
      },
      "delay": false,
      "exception": false
    }
  ],
  "body": {
    "579f6444b6a1bb4fbaab5610": [
      {
        "shown": true,
        "status": "OrderProcessed",
        "status_text": "Bestellung verarbeitet",
        "status_details": "Die Bestellung wurde verarbeitet.",
        "full_courier_status": "If exists, date of order, else date of import to parcelLab",
        "location": "Sample City",
        "timestamp": "2015-08-10T15:18:27.000Z"
      }
    ]
  }
}

The additional details in the action box are type-specific (for example: if the tracking.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`

For a prediction, a sub document is included with the scheduled delivery date. This is displayed in the format below.

actionBox-prediction.json

"actionBox": {
  "type": "prediction",
  "label": "Estimated Delivery:",
  "prediction": {
    "label": "Estimated Delivery:",
    "type": "prediction",
    "timeCaption": "",
    "dateOfMonth": "21",
    "dayOfWeek": "Saturday",
    "month": "December",
    "caption": "The delivery has been announced by DHL.",
    "startTime": "11:30",
    "endTime": "13:30"
  }
}

Type `pickup-location`

For a delivery to be collected, a sub document is included with the opening hours. This is displayed in the format below.

The format of the opening hours is the same as used by the Google Maps API.

actionBox-pickup.json

"actionBox": {
    "type": "pickup-location",
    "address": "Kurfürstenplatz 8, 80796 München",
    "openingHours": [
      {
        "close": {
          "day": 1,
          "time": "1800"
        },
        "open": {
          "day": 1,
          "time": "0800"
        }
      },
      ...
    ]
  },

Get Sender Information for a Tracking

Details of how the sender endpoint can be used to retrieve sender information for an order or tracking in the parcelLab system are described below.

GET Sender Information for a Tracking

You can retrieve the sender information given for an order or tracking using the courier and tracking_number with the sender endpoint.

Note: All request parameters specified above for v2/checkpoints are also supported.

The details of the Get Sender Information for a Tracking API are described in the following section.

API Details

GET https://api.parcellab.com/sender

Query Parameters

Name

Type

Description

tno

string

Tracking number

courier

string

Courier code

lang

string

Language in in ISO 3166-1 alpha-3 format. Defaults to en.

An example request is displayed below to show the format for retrieving sender information for a tracking.

curl --location 'https://api.parcellab.com/sender/?tno=003400SOMETRACKING&courier=dhl-germany&lang=de’

Responses

200 - accepted

Get Article List of a Tracking

Details of how the v2/checkpoints endpoint can be used to retrieve the article list for an order or tracking in the parcelLab system are described below.

GET Article List of Tracking

You can retrieve the article list for an order or tracking using the courier and tracking_number with the v2/checkpoints endpoint. In order to retrieve the article list, request authentication through the security hash &s= is required.

Note: All request parameters specified above for v2/checkpoints are also supported.

The details of the Get Article List of a Tracking API are described in the following section.

API Details

GET https://api.parcellab.com/v2/checkpoints

Query Parameters

Name

Type

Description

tno

string

Tracking number

courier

string

Courier code

lang

string

Language in in ISO 3166-1 alpha-3 format. Defaults to en.

string

Security hash

An example request is displayed below to show the format for retrieving the article list of a tracking.

curl --location 'https://api.parcellab.com/sender/?tno=003400SOMETRACKING&courier=dhl-germany&lang=de&s=ABCD1234’

Responses

200 - accepted

Get Notifications of a Tracking

Details of how the v2/notifications endpoint can be used to retrieve all notifications for a tracking in the parcelLab system are described below.

GET Notifications of Tracking

You can retrieve all sent notifications for a tracking using the userId and trackingId with the v2/notifications endpoint.

The details of the Get Notifications for a Tracking API are described in the following section.

API Details

GET https://api.parcellab.com/v2/notifications

Path Parameters

Name

Type

Description

tid

string

parcelLab tracking ID

Header

Name

Type

Description

user

number

parcelLab user ID

token

string

parcelLab API token

An example request is displayed below to show the format for retrieving the notifications for a tracking.

curl --location 'https://api.parcellab.com/v2/notifications?tid=50ae00000000000000000001’ \
  --header 'user: 100' \
  --header 'token: parcelLabAPItoken-30characters' \

Responses

200 OK

All notifications for selected tracking or order will be shown in the JSON response body formatted as an array of objects with the following fields:

Array sorted by timestamp (oldest → newest) across channels. Each item includes type (email|sms|webhook|app) and, when applicable, from_other_tracking (true if it belongs to a sibling tracking of the same order).
Email fields: id, subject, created, sentAt, message/messageType/prettyName, opened, clicked, bounced, rescueLink, live, attachments [{url,filename?,isOptional}], optional source (slot/trigger data).
SMS fields: id, messageType/prettyName, message, receiver, clicked, segments, sender, trackingId, failed, courier, optional source.
Webhook fields: id, messageType/prettyName, status, success, isFinalAttempt, receiver (URL without query), headers, message (request body), response_headers, response_body, response_error, is_push_notification, timing, payload_size, optional source.
App execution fields: id, installedApp, customApp, slug, appName, appType, appKey, success, input, output, duration, deduplicationId, created/timestamp, optional source.
Email attachment URLs are pre-signed (1-day expiry); opened/clicked are nulled if the account has hideEmailEngagement enabled.

401 UNAUTHORIZED

Not authorized to access data for this tracking.

Plain text response body: Access denied.

404 NOT FOUND

Requested tracking cannot be found. This does not reflect the case of a tracking without any notifications, which would be an empty array response with status 200.

Plain text response body: Nothing found.

500 INTERNAL SERVER ERROR

Server error when processing result or accessing database.

Plain text response body: Error accessing database.

PreviousOrder/Warehouse Events NextOrder Status Page Configuration

Last updated 2 months ago

Was this helpful?

hashtagGet Checkpoints

hashtagAPI Details

hashtagQuery Parameters

hashtagResponses

hashtagAPI Details

hashtagQuery Parameters

hashtagResponses

hashtagAPI Details

hashtagQuery Parameters

hashtagResponses

hashtagReturn Header

hashtagCourier Object

hashtagLast Delivery Status Object

hashtagReturn Body

hashtagGet Tracking Details

hashtagAPI Details

hashtagQuery Parameters

hashtagHeader

hashtagResponses

hashtagType prediction

hashtagType pickup-location

hashtagGet Sender Information for a Tracking

hashtagAPI Details

hashtagQuery Parameters

hashtagResponses

hashtagGet Article List of a Tracking

hashtagAPI Details

hashtagQuery Parameters

hashtagResponses

hashtagGet Notifications of a Tracking

hashtagAPI Details

hashtagPath Parameters

hashtagHeader

hashtagResponses

Get Checkpoints

API Details

Query Parameters

Responses

API Details

Query Parameters

Responses

API Details

Query Parameters

Responses

Return Header

Courier Object

Last Delivery Status Object

Return Body

Get Tracking Details

API Details

Query Parameters

Header

Responses

Type `prediction`

Type `pickup-location`

Get Sender Information for a Tracking

API Details

Query Parameters

Responses

Get Article List of a Tracking

API Details

Query Parameters

Responses

Get Notifications of a Tracking

API Details

Path Parameters

Header

Responses