Trackings/Orders

You can submit a new order and tracking via our API v2 LTS.

Overview

You can send tracking and order information to parcelLab via the API v2 LTS order and track endpoints. This allows you to submit tracking information (that is: courier and tracking_number) for one or multiple parcels with a corresponding order number and can also be used to inform parcelLab to expect tracking information for a specified order.

For details on creating a tracking/order with the API v4 Enhanced (preview), see our trackings/orders API v4 reference.

Order API Endpoint

Details of how the order endpoint can be used to create, test, and monitor trackings in the parcelLab system are described below.

POST Create or Update a Tracking/Order

You can create or update a tracking and order in the parcelLab system using the order endpoint.

If submitting the order details before the tracking information, the relevant tracking details that follow should be sent via the order endpoint as well when you receive it. Additionally, if you have created an order via the /presage endpoint and you want to update that existing order (for example: add a tracking number), you have to use the /presage endpoint again.

You can set tags on a tracking that allow you to easily identify custom attributes in filters and exports (for example: tags: ["category:womens fashion", "brand:Parkers", "season:W24", "category:sweater", "material:cashmere"]). For further information, see our data model documentation.

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

The details of the Create a Tracking/Order API are described in the following section.

API Details

POST https://api.parcellab.com/order

Header

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

Request Body

Name	Type	Description
payload	object	Single-level object as described in data model

Responses

• 202 - accepted

• 400 - invalid request/invalid tracking number provided

• 401 - no credentials given/invalid credentials

• 500 - error encountered

The payload holds the order-specific information, as specified in the data model, where all available keys can be found. All attributes are named key/value pairs in a flat JSON formatted object.

payload.json

{
  "xid": "id-of-delivery-before-tracking-number",
  "destination_country_iso3": "DEU",
  "client": "your-client-id",
  "orderNo": "ORDER-000001",
  "recipient": "Max Mustermann, parcelLab GmbH",
  "recipient_notification": "Max",
  "email": "[email protected]",
  "street": "Landwehrstr. 39",
  "zip_code": "80336",
  "city": "München"
}

POST Create a Test Tracking/Order

You can create a test tracking in the parcelLab system using this mock endpoint to check if the production endpoint would accept your payload.

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

The details of the Create a Test Tracking/Order API are described in the following section.

API Details

POST https://api.parcellab.com/order/mock

To test your API call, you can call our mock endpoint. The endpoint validates your authentication and payload, and returns a 202 if the production endpoint would have accepted your payload.

There will be no further processing by the system, but you can view your most recent request (see below).

Header

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

Request Body

Name	Type	Description
payload	object	Single-level object as described in data model (see request of equivalent production endpoint).

Responses

• 202 - accepted

• 400 - invalid request/invalid tracking number provided

• 401 - no or incorrect credentials provided

• 500 - request errored, please reach out to [email protected]

Track API Endpoint

Details of how the track endpoint can be used to create, test, and monitor trackings in the parcelLab system are described below.

POST Create a Tracking

You can create a new tracking in the parcelLab system using the track endpoint. This allows you to submit tracking information to parcelLab for a single parcel.

Note: If you are sending tracking information to update an order record, this should be sent via the order endpoint as well when you receive it.

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

The details of the Create a Tracking API are described in the following section.

API Details

POST https://api.parcellab.com/track

Header

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

Request Body

Name	Type	Description
payload	object	Single-level object as described in data model

Responses

• 202 - accepted

• 400 - invalid request/invalid tracking number provided

• 401 - no credentials given/invalid credentials

• 500 - error encountered

The payload holds the tracking specific information, as specified in the data model. All attributes are named key/value pairs in a flat JSON formatted object.

payload.json

{
  "tracking_number": "1234567890",
  "courier": "dhl-germany",
  "zip_code": "12345",
  "deliveryNo": "DEL-AB1234"
}

POST Create a Tracking with XML

You can use XML instead of JSON as an alternative way of transmitting data to create a tracking in the parcelLab system using the track endpoint. This allows you to submit tracking information to parcelLab for a single parcel.

Note: If you are sending tracking information to update an order record, this should be sent via the order endpoint as well when you receive it.

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

Note: The preferred method to transmit data is JSON.

The details of the Create a Tracking with XML API are described in the following section.

API Details

POST https://api.parcellab.com/track

Header

Name	Type	Description
user	number	parcelLab user ID
token	string	parcelLab API token
content-type	string	'text/xml'

Request Body

Name	Type	Description
payload	object	Single-level object as described in data model

Responses

• 202 - accepted

• 400 - invalid request/invalid tracking number provided

• 401 - no credentials given/invalid credentials

• 500 - error encountered

POST Create a Test Tracking

You can create a test tracking in the parcelLab system using this mock endpoint to check if the production endpoint would accept your payload.

The details of the Create a Test Tracking API are described in the following section.

API Details

POST https://api.parcellab.com/track/mock

To test your API call, you can call our mock endpoint. The endpoint validates your authentication and payload, and returns a 202 if the production endpoint would have accepted your payload.

There will be no further processing by the system, but you can view your most recent request (see below).

Header

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

Request Body

Name	Type	Description
payload	object	Single-level object as described in data model (see request of equivalent production endpoint)

Responses

• 202 - accepted

• 400 - invalid request/invalid tracking number provided

• 401 - no credentials given/invalid credentials

• 500 - error encountered

GET Recent Test Tracking Request

You can view your most recent request to the mock endpoint for three hours after you placed your request by calling the same route with the GET method. The user and token can be placed as URL query parameters so you can easily navigate your browser to the URL.

https://api.parcellab.com/track/mock/?user=<user>&token=<token>

You will retrieve a JSON document with three relevant keys.

{
  receivedAt: '2030-01-01T16:12:00.000Z', // time the request has been received
  validation: { // basic validation of your payload, see below
    hasAllRequiredKeys: true,
    ... 
  },
  payload: [ // your payload
    { ... }
  ]
}

The mock endpoint provides basic validation of the provided payload. However, a successful validation by the mock endpoint does not warrant all data is correct and can be used for all parcelLab functionalities. A validated payload will be accepted, processed, and stored by the system though.

The validation keys are described below.

• hasAllRequiredKeys - No required keys are missing for the system to accept the payload. This does not warrant all keys for communication are present.

• hasOnlyAllowedKeys - Payloads with keys not listed in the data model are rejected.

• hasValidIdentifier - Both courier and tracking_number must be filled.

• hasTrackingNumber - The tracking_number allows for different data types. This validates whether the given data type is accepted.

• hasValidTrackingNumber - This validates the format of the tracking_number against our catalogue of known formats for the given courier.

• courierCodeIsKnown - This validates the given courier code against all courier codes processed by parcelLab. However, even unknown courier codes will be accepted and stored by parcelLab. Unknown courier codes will not be tracked though.

For more information on validation, or if your courier code is unknown, please fill in our contact form​ and we'll get back to you.

Credentials

Credentials are assigned by our Support team as required for the services used. Overall, there are different pairs of credentials for different services to assure security.

Code Samples

You can use our API with jQuery, Node, Ruby, Python, PHP, and other programming languages.

For examples of programming languages, please fill in our contact form and they will be provided on request.

For a simple test, cURL can be used.

sample-call-with-curl.sh

curl -d '{"orderNo": "order-1234567890"}' \
  -H "Content-Type: application/json" \
  -H "user: 1" \
  -H "token: parcelLabAPItoken-30characters" \
  https://api.parcellab.com/order/