# Data Model

## Overview

The most basic record in parcelLab is a tracking. A tracking can represent a parcel or a pallet, or anything else that is identified by a unique tracking number. You can submit tracking information for one or more parcels with a corresponding order number.

{% hint style="success" %}
Please use [<mark style="color:blue;">PUT</mark> `v4/track/orders`](/docs/developers/orders/full-order-api-spec.md#put-v4-track-orders) as the default endpoint to create new trackings and orders in the API v4 Enhanced.
{% endhint %}

## Keys for Trackings

The tracking details can be sent with the corresponding order in the tracking array in the mutations of the `/v4/track/orders` endpoint.

The following table lists the keys that can be used to create a tracking.

| Key                        | Type                                                                   | Description                                                                             |
| -------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| tracking\_number           | String                                                                 | Unique tracking number.                                                                 |
| courier                    | Carrier code                                                           | Short code of the carrier (see below).                                                  |
| recipient\_postal\_code    | String                                                                 | Postal (zip) code.                                                                      |
| destination\_country\_iso3 | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) | Destination country (for example: `DEU` ), if different from order destination country. |

The following list contains some carrier codes. If you need a carrier code that is not on this list, please contact your Implementation Manager for the specific carrier codes required.

<details>

<summary>Carrier Codes</summary>

The carrier codes listed here are displayed in the format `Carrier Name: Key`.

* La Poste: colissimo
* DHL Global Mail: dhl-gm
* DHL: dhl-germany, dhl-benelux
* DPD: dpd-de
* FedEx: fedex
* GLS Germany/France/Denmark: gls
* Mondial Relay: mondial
* Royal Mail: royalmail
* UPS Mail: ups-mi

</details>

## Special Keys for Trackings

The following table lists special keys that alter how the system handles trackings.

| Key                     | Type    | Description                                                                                                                                          |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| is\_return              | Boolean | If `true`, the delivery is handled as a return. Dispatch delays will not be monitored and the tracking will not be considered for general reporting. |
| cancelled\_date         | String  | The date/time when the order was cancelled.                                                                                                          |
| cancelled\_reason       | String  | The reason for cancelling an order. This can be `customer`, `inventory`, `payment`, `other`.                                                         |
| notifications\_inactive | Boolean | If `true`, communication to the customer is stopped immediately.                                                                                     |

## Creating Orders

Orders can be explicitly created in parcelLab using the `v4/track/orders` endpoint. To group trackings into an order, an order number needs to be supplied. This order number then links all trackings together and consolidates communications (for example: email, SMS, and so on) and the Order Status page.

{% hint style="info" %}
If submitting the order details before the tracking information, you can send the relevant tracking details that follow via the `v4/track/orders` endpoint as well when you receive it. For further information, see [how to update an order record](/docs/developers/orders/full-order-api-spec.md#create-or-update-a-tracking-order).
{% endhint %}

| Key                        | Type                                                                   | Description                                  |
| -------------------------- | ---------------------------------------------------------------------- | -------------------------------------------- |
| account                    | Integer                                                                | parcelLab user ID associated with the order. |
| order\_number              | String                                                                 | Order number.                                |
| destination\_country\_iso3 | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) | Destination country (for example: `DEU` ).   |
| recipient\_email           | String                                                                 | Email address of recipient.                  |

## Multi-Shop Setup

If several shops (for example: shops with multiple domains, dedicated shops for specific countries, or otherwise individual corporate identity) are used within one account in the parcelLab App, each tracking is assigned to a shop using the `client_key` field.

| Key         | Type   | Description                                       |
| ----------- | ------ | ------------------------------------------------- |
| client\_key | String | Client/shop of the tracking in internal encoding. |

The values in the `client_key` field can be copied from internal systems and can be any string. Each client is implicitly linked to a shop in the parcelLab system and is the easiest way to assign a sender name, domain, and email template.

{% hint style="info" %}
The `client_key` field that is used for multi-shop setup is not to be confused with [the `customer_number` field that is used to individualize notifications](#optional-keys-for-notifications).
{% endhint %}

## Keys for Notifications

The following table lists the keys that can be used for notifications that are sent from parcelLab.

{% hint style="info" %}
Some of the following keys may be required to enable additional product functionality.
{% endhint %}

<table><thead><tr><th width="218.16611724351685">Key</th><th width="112">Type</th><th width="129">Necessity</th><th>Description</th></tr></thead><tbody><tr><td>recipient_name</td><td>String</td><td>Optional</td><td>Name of the recipient used in notifications (including salutation).</td></tr><tr><td>recipient_email</td><td>String</td><td>Required</td><td>Email address of recipient.</td></tr><tr><td>address_line</td><td>String</td><td>Required</td><td>Street address of delivery.</td></tr><tr><td>postal_code</td><td>String</td><td>Required</td><td>Postal (zip) code of delivery.</td></tr><tr><td>city</td><td>String</td><td>Required</td><td>City of delivery.</td></tr><tr><td>country_iso3</td><td><a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3">ISO 3166-1 alpha-3</a></td><td>Required</td><td>Country of delivery (for example: <code>DEU</code>).</td></tr><tr><td>phone</td><td>String</td><td>Optional</td><td>Phone number of recipient.</td></tr><tr><td>language_iso2</td><td><a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO 639-1</a></td><td>Optional</td><td>Language used by recipient (for example: <code>de</code> for German).</td></tr><tr><td>delivery_number</td><td>String</td><td>Optional</td><td>Delivery number of shipment in order.</td></tr><tr><td>customer_number</td><td>String</td><td>Optional</td><td>Customer number (for example: from the retailer).</td></tr><tr><td>identifiers_consignment</td><td>String</td><td>Optional</td><td>Consignment number identifying the parcel.</td></tr><tr><td>weight</td><td>String</td><td>Optional</td><td>Weight of the package.</td></tr><tr><td>courier_service_level</td><td>String</td><td>Optional; Required for Promise</td><td>Product or service level from carrier.</td></tr><tr><td>warehouse</td><td>String</td><td>Optional; Required for Promise</td><td>Warehouse from which the delivery was shipped.</td></tr><tr><td>channel</td><td>String</td><td>Optional; Required for Marketplace Support</td><td>Marketplace used for sale.</td></tr><tr><td>complete</td><td>Boolean</td><td>Optional</td><td>Whether the shipment is complete.</td></tr><tr><td>upgrade</td><td>Boolean</td><td>Optional</td><td>Whether the shipment has an upgrade or individualization.</td></tr><tr><td>cash_on_delivery</td><td>Number</td><td>Optional</td><td>The cash on delivery (COD) amount.</td></tr><tr><td>branch_delivery</td><td>Boolean</td><td>Optional</td><td>Whether the shipment is a branch delivery.</td></tr><tr><td>status_link</td><td>String</td><td>Optional</td><td>Link to track the status of the delivery.</td></tr><tr><td>order_date</td><td>Date/DateTime</td><td>Optional</td><td>Date of ordering by customer.</td></tr><tr><td>announced_send_date</td><td>Date/DateTime</td><td>Optional</td><td>Announced dispatch date or send date</td></tr><tr><td>announced_delivery_date</td><td>Date</td><td>Optional; Required for Trending Late</td><td>Announced delivery date.</td></tr></tbody></table>

{% hint style="info" %}
When these fields are sent as a structured `shipping_address` object, the address object must include valid, non-empty values for `address_line`, `postal_code`, `city`, and `country_iso3`. If the full address is unavailable, omit the `shipping_address` object instead of sending blank or `null` required address fields.
{% endhint %}

{% hint style="info" %}
All dates and times should be sent in UTC format (that is: `YYYY-MM-DDTHH:mm:ss.sssZ`) or include a timezone offset or specification, as in the following examples:

* Date only: 2024-12-13
* Date and time: 2024-12-13T12:08:55.638Z
* Date and time with timezone offset: 2024-12-13T12:08:55.638+01:00
  {% endhint %}

## Billing Address

The following table lists the fields that can be used to store all related billing information for the customer billing address in the optional `billing_address` property.

<table><thead><tr><th width="170.78721099351685">Key</th><th width="128.62109375">Type</th><th width="165.984375">Necessity</th><th>Description</th></tr></thead><tbody><tr><td>first_name</td><td>String</td><td>Optional</td><td>First name of the billing recipient.</td></tr><tr><td>last_name</td><td>String</td><td>Optional</td><td>Last name of the billing recipient.</td></tr><tr><td>company_name</td><td>String</td><td>Optional</td><td>Company name of the billing recipient.</td></tr><tr><td>address_line</td><td>String</td><td>Required</td><td>Street and house number of the billing recipient.</td></tr><tr><td>address_line_extra</td><td>String</td><td>Optional</td><td>Additional address line of the billing recipient.</td></tr><tr><td>postal_code</td><td>String</td><td>Required</td><td>Postal (zip) code of the billing recipient.</td></tr><tr><td>city</td><td>String</td><td>Required</td><td>City of the billing recipient.</td></tr><tr><td>country_iso3</td><td><a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3">ISO 3166-1 alpha-3</a></td><td>Required</td><td>Country of the billing recipient (for example: <code>DEU</code>).</td></tr><tr><td>region_code</td><td><a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-2 alpha-2</a></td><td>Optional</td><td>State or province code of the billing recipient.</td></tr><tr><td>phone</td><td>String</td><td>Optional</td><td>Phone number of the billing recipient.</td></tr></tbody></table>

## Article List

A list of articles allows you to specify the detailed contents of an order by defining for each item in the list the quantity, article number, and article name in the optional `articles_order` property.

{% hint style="info" %}
This is the article information for the order. You can define which articles are dispatched in each shipment later as part of the shipment payload.
{% endhint %}

The following table lists the required and optional keys for article lists.

{% hint style="info" %}
Some of the following keys may be required to enable additional product functionality.
{% endhint %}

<table><thead><tr><th width="211">Key</th><th width="128">Type</th><th>Necessity</th><th>Description</th></tr></thead><tbody><tr><td>version</td><td>String</td><td>Optional</td><td>Possible values <code>v1</code> or <code>v2</code>.</td></tr><tr><td>line_item_id</td><td>String</td><td>Required</td><td>Retailer ID of the article.</td></tr><tr><td>SKU</td><td>String</td><td>Optional</td><td>Stock Keeping Unit (SKU) of the article.</td></tr><tr><td>product_id</td><td>String</td><td>Optional</td><td>Product ID of the article in the retailer’s system, if different from the SKU.</td></tr><tr><td>order_item_id</td><td>String</td><td>Required</td><td>Article ID in the order.</td></tr><tr><td>article_name</td><td>String</td><td>Required</td><td>Article name.</td></tr><tr><td>article_category</td><td>String</td><td>Optional; Required for Category-Based Return Reasons</td><td>Article category.</td></tr><tr><td>article_store_url</td><td>String</td><td>Optional; Required for Product Recommendations</td><td>URL to the product page.</td></tr><tr><td>article_image_url</td><td>String</td><td>Optional; Required for Product Recommendations</td><td>Full URL to the product image.</td></tr><tr><td>article_brand</td><td>String</td><td>Optional</td><td>Brand of the article.</td></tr><tr><td>size</td><td>String</td><td>Optional</td><td>Article size.</td></tr><tr><td>color</td><td>String</td><td>Optional</td><td>Article color.</td></tr><tr><td>width</td><td>Numeric</td><td>Optional</td><td>Article width.</td></tr><tr><td>height</td><td>Numeric</td><td>Optional</td><td>Article height.</td></tr><tr><td>length</td><td>Numeric</td><td>Optional</td><td>Article length.</td></tr><tr><td>length_unit</td><td>String</td><td>Optional</td><td>Article length unit of measurement.</td></tr><tr><td>weight</td><td>Numeric</td><td>Optional</td><td>Article weight.</td></tr><tr><td>weight_unit</td><td>String</td><td>Optional</td><td>Article weightt unit of measurement.</td></tr><tr><td>unit_price</td><td>Numeric</td><td><p>Optional; Required for:</p><ul><li>Returns Portal</li><li>Customer Segmentation</li></ul></td><td>Article price.</td></tr><tr><td>quantity</td><td>Numeric</td><td><p>Optional; Required for:</p><ul><li>Returns Portal</li><li>Customer Segmentation</li><li>Product Recommendations</li></ul></td><td>Amount of the purchased product.</td></tr><tr><td>amount_invoiced</td><td>Numeric</td><td>Optional</td><td>Amount invoiced for the article.</td></tr><tr><td>origin_country_iso3</td><td><a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3">ISO 3166-1 alpha-3</a></td><td>Optional</td><td>Country of origin of the article, might be required based on shipment regulations.</td></tr><tr><td>is_bulky</td><td>Boolean</td><td>Optional</td><td>Whether the article is bulky.</td></tr><tr><td>tags</td><td>String</td><td>Optional</td><td>Tags for the article (for example: category:home-apparel).</td></tr><tr><td>additional_attributes</td><td>Object</td><td>Optional</td><td>Additional attributes for the article. Requires a <code>key</code> and optional <code>value</code> for the additional attribute.</td></tr><tr><td>status</td><td>String</td><td>Optional</td><td>Order status of the article. Can be <code>shipped</code>, <code>pending</code>, <code>processing</code>, <code>cancelled</code>, <code>returned</code>.</td></tr></tbody></table>

A list of articles looks like this:

{% tabs %}
{% tab title="article-list.json" %}

```json
[
  {
    "line_item_id":       "retailer ID of article" (String),  // required
    "order_item_id":      "article ID" (String),              // optional
    "article_name":       "article name" (String),            // optional
    "article_category":   "article category" (String),        // optional
    "article_store_url":  "url to the product page" (String), // optional
    "article_image_url":  "full url to image" (String),       // optional
    "size": 		"article size" (String),            // optional
    "color":  		"article color" (String),           // optional
    "quantity":       "amount of purchased item" (Numeric)",  // optional
  },

  ...
]
```

{% endtab %}
{% endtabs %}

## Custom Fields

{% hint style="info" %}
The API v4 Enhanced standardises common use cases that previously required custom fields. Therefore, many of the common fields can now be directly used in the standard parameters.
{% endhint %}

Custom fields can be used to add additional content to the notifications that does not fit in any other field. These must be written inside `tracking.additional_fields` in tracking mutations sent to the `/v4/track/orders` endpoint. Custom fields must be coordinated with parcelLab and submitted as key-value pairs inside that object.

{% hint style="info" %}
Custom fields cannot be used for filtering in the parcelLab App. Therefore, it’s recommended to use the standard fields or tags and use custom fields only if additional information should still be submitted.
{% endhint %}

Keys of `additional_fields` are arbitrary but must be of `String` type. Key values can be of any data type. Do not send customer-defined keys at the top level of `tracking`; place them inside `additional_fields` instead. An example can look like this.

{% tabs %}
{% tab title="tracking-with-custom-fields.json" %}

```json
{
  "mutations": [
    {
      "type": "add_tracking",
      "tracking": {
        "tracking_number": "0035999222335558TEST",
        "courier": "fedex",
        "courier_service_level": "STANDARD",
        "delivery_number": "PO_S100001903",
        "warehouse": "US_WEST",
        "additional_fields": {
          "seller_organization_code": "PL_01",
          "pickupBoxCabinNo": "48"
        }
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Tags

Tags can be used to identify specific information in trackings in order to easily find them via filters and in exports.

{% hint style="info" %}
Tags are important to be able to filter trackings on custom attributes as information specified in custom fields is not searchable.
{% endhint %}

Tags are an array of `String` type. An example of individual tags for a tracking can look like this:

{% tabs %}
{% tab title="tracking-with-tags.json" %}
{% code overflow="wrap" %}

```json
{
  "tracking_number": "PK23583755931",
  "courier": "dhl",
  "articleNo": "PKWCS1224",
  "articleName": "Coral Sweater",
  "quantity": "1",
  "tags": ["category:womens fashion", "brand:Parker’s", "season:W24",  
  "category:sweater", "material:cashmere"]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Sample JSON Payload

A sample JSON payload can be found here as demonstration of the data structure.

{% file src="/files/OKpIJJxdKPrWdiVr4NWe" %}


---

# 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/data-elements/data-model.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.