# Trackings/Orders

## 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.

{% hint style="info" %}
For details on creating a tracking/order with the API v4 Enhanced (preview), see our [trackings/orders API v4 reference](/docs/developers/orders/full-order-api-spec.md).
{% endhint %}

## 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.

<details>

<summary><mark style="color:green;">POST</mark> Create or Update a Tracking/Order</summary>

You can create or update a tracking and order in the parcelLab system using the `order` endpoint.&#x20;

{% hint style="info" %}
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.
{% endhint %}

{% hint style="success" %}
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](/docs/developers/v2/data-elements/data-model.md#tags).
{% endhint %}

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

<mark style="color:green;">`POST`</mark> `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](/docs/developers/v2/data-elements/data-model.md), where all available keys can be found. All attributes are named key/value pairs in a flat JSON formatted object.

{% code title="payload.json" %}

```javascript
{
  "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": "max-mustermann@abc.xyz",
  "street": "Landwehrstr. 39",
  "zip_code": "80336",
  "city": "München"
}
```

{% endcode %}

</details>

<details>

<summary><mark style="color:green;">POST</mark> Create a Test Tracking/Order</summary>

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

<mark style="color:green;">`POST`</mark> `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 <support@parcellab.com>

</details>

## 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.

<details>

<summary><mark style="color:green;">POST</mark> Create a Tracking</summary>

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

<mark style="color:green;">`POST`</mark> `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](/docs/developers/v2/data-elements/data-model.md). All attributes are named key/value pairs in a flat JSON formatted object.

{% code title="payload.json" %}

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

{% endcode %}

</details>

<details>

<summary><mark style="color:green;">POST</mark> Create a Tracking with XML</summary>

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

<mark style="color:green;">`POST`</mark> `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

</details>

<details>

<summary><mark style="color:green;">POST</mark> Create a Test Tracking</summary>

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

<mark style="color:green;">`POST`</mark> `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

</details>

<details>

<summary><mark style="color:blue;">GET</mark> Recent Test Tracking Request</summary>

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.

```javascript
{
  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](https://parcellab.com/en/contact)​ and we'll get back to you.

</details>

## 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.

{% hint style="info" %}
For examples of programming languages, please [fill in our contact form](https://parcellab.com/en/contact) and they will be provided on request.
{% endhint %}

For a simple test, cURL can be used.

{% code title="sample-call-with-curl.sh" %}

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

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/v2/orders/trackings-orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.