# 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="warning" %}
Individual fields have **no character length limit**.

Embedding of large base64 values is discouraged, and if those are transmitted they are automatically replaced by an URL to our file storage, so cannot be directly retrieved from our API.

The maximum permitted payload size is 1 MB, larger payloads will be rejected by the API.
{% endhint %}

## Required Keys for Trackings

The following table lists the required keys that must be supplied for every `tracking`.

{% hint style="info" %}
This tracking information can be sent with the corresponding order number using the `order` endpoint.
{% endhint %}

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

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                                                                                                                                          |
| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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             | Boolean | If `true`, delivery is cancelled (that is: no communication is sent to the set `recipient`). All monitoring and reporting is disabled.               |
| notificationsInactive | Boolean | If `true`, communication to the customer is stopped immediately.                                                                                     |

## Creating Orders

Orders can be explicitly created in parcelLab using the `order` 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, the relevant tracking details that follow should be sent via the `order` endpoint as well when you receive it. For further information, see [how to update an order record](/docs/developers/v2/orders/trackings-orders.md#put-update-a-tracking-order).
{% endhint %}

| Key     | Type   | Description   |
| ------- | ------ | ------------- |
| orderNo | String | Order number. |

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

| Key    | Type   | Description                                                        |
| ------ | ------ | ------------------------------------------------------------------ |
| client | String | Client (*Mandant* in German) of the tracking in internal encoding. |

The values in the `client` 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` field that is used for multi-shop setup is not to be confused with [the `customerNo` field that is used to individualize notifications](#optional-keys-for-notifications).
{% endhint %}

## Required Keys for Notifications

The following table lists the required keys that should be supplied for notifications that are sent from parcelLab.

| Key                     | Type                                                               | Description                                                            |
| ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| recipient\_notification | String                                                             | Name of the recipient used in notifications (including salutation).    |
| recipient               | String                                                             | Name of the recipient used in the parcelLab App.                       |
| email                   | String                                                             | Email address of recipient.                                            |
| street                  | String                                                             | Street address of delivery.                                            |
| city                    | String                                                             | City of delivery.                                                      |
| phone                   | String                                                             | Phone number of recipient.                                             |
| language\_iso3          | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | ISO code of language used by recipient (for example: `de` for German). |

## Optional Keys for Notifications

The following table lists additional keys that can be used to further individualize notifications.

{% 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>deliveryNo</td><td>String</td><td>Optional</td><td>Internal delivery number.</td></tr><tr><td>customerNo</td><td>String</td><td>Optional</td><td>Internal customer number.</td></tr><tr><td>consignmentNo</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>courierServiceLevel</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>market</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>cashOnDelivery</td><td>Number</td><td>Optional</td><td>The cash on delivery (COD) amount.</td></tr><tr><td>branchDelivery</td><td>Boolean</td><td>Optional</td><td>Whether the shipment is a branch delivery.</td></tr><tr><td>statuslink</td><td>String</td><td>Optional</td><td>Alternative status link.</td></tr><tr><td>order_date</td><td>Date / DateTime</td><td>Optional</td><td>Date of ordering by customer.</td></tr><tr><td>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" %}
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_info` property.

{% hint style="info" %}
These fields are all optional.
{% endhint %}

<table><thead><tr><th width="268.16611724351685">Key</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>String</td><td>Full name of the billing recipient.</td></tr><tr><td>phone</td><td>String</td><td>Phone number of the billing recipient.</td></tr><tr><td>email</td><td>String</td><td>Email address of the billing recipient.</td></tr><tr><td>street</td><td>String</td><td>Street of the billing recipient.</td></tr><tr><td>city</td><td>String</td><td>City of the billing recipient.</td></tr><tr><td>zip_code</td><td>String</td><td>Postal code of the billing recipient.</td></tr><tr><td>region</td><td>String</td><td>State of the billing recipient.</td></tr><tr><td>country_iso3</td><td>String</td><td>Country of the billing recipient.</td></tr></tbody></table>

## Article List

A list of articles allows you to specify the detailed contents of a delivery by defining for each item in the list the quantity, article number, and article name. It is written into the `articles` field.

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>articleNo</td><td>String</td><td>Required</td><td>Article number.</td></tr><tr><td>articleName</td><td>String</td><td>Required</td><td>Article name.</td></tr><tr><td>articleCategory</td><td>String</td><td>Optional; Required for Category-Based Return Reasons</td><td>Article category.</td></tr><tr><td>articlePrice</td><td>Numeric</td><td><p>Optional; Required for:</p><ul><li>Returns Portal</li><li>Customer Segmentation</li></ul></td><td></td></tr><tr><td>articleUrl</td><td>String</td><td>Optional; Required for Product Recommendations</td><td>URL to the product page.</td></tr><tr><td>articleImageUrl</td><td>String</td><td>Optional; Required for Product Recommendations</td><td>Full URL to the product image</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>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>returnableQuantity</td><td>Numeric</td><td>Optional; Required for Already Returned Items feature</td><td>Quantity eligible for return.</td></tr></tbody></table>

A list of articles looks like this:

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

```json
[
  {
    "articleNo":       "article number (String)",            // required
    "articleName":      "article name (String)",              // required
    "articleCategory":  "article category (String)",          // optional
    "articleUrl":       "url to the product page (String)",   // optional
    "articleImageUrl":  "full url to image (String)",         // optional
    "size":             "article size (String)",              // optional
    "color":            "article color (String)",             // optional
    "quantity":         Integer,                              // optional
  },
  ...
]
```

{% endtab %}
{% endtabs %}

## Custom Fields

Custom fields can be used to add additional content to the notifications that does not fit in any other field. These are written into the sub-object in `customFields`. Custom fields can be set individually but must be coordinated with parcelLab. Multiple custom fields can be submitted as a list of custom fields.

Keys of `customFields` are arbitrary but must be of `String` type. Key values can be of any data type. An example of individual custom fields can look like this:

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

```json
{
  "courier": "ups",
  "tracking_number": "1Z0...01",
  ...
  "customFields": {
    "sample_string":  "Any String",  // Any key name and any data type, e.g. String
    "sampleNumber":   "1234",          // ... or number ...
    "anyboolean":     "true",          // ... or bool ...
    "mylist":         [{ a: 1 }],    // ... or even an array.
    ...                            // Add any other keys as well.
  }
}
```

{% endtab %}
{% endtabs %}

Any added custom field can immediately be used as a placeholder like this: `{{sample_string/customField}}`. If a placeholder is used and the custom field is not set, the placeholder will show an empty string.

## 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 %}

## Reference Numbers (for Return Portals)

This section describes how to manage reference numbers within return portals using various data model fields, ensuring seamless integration for both Shopify and non-Shopify platforms.

The following table lists the data model fields for return portal reference numbers and the equivalent mappings for Shopify and non-Shopify returns.

<table><thead><tr><th width="150.5">Data Model Field</th><th width="155">Name</th><th width="198">Shopify</th><th width="212">Non-Shopify</th></tr></thead><tbody><tr><td><code>tracking_number</code></td><td>Tracking number on label</td><td>Courier label tracking</td><td>Courier label tracking</td></tr><tr><td><code>courier</code></td><td>Carrier Code</td><td>parcelLab Courier code</td><td>parcelLab Courier code</td></tr><tr><td><code>consignmentNo</code></td><td>Return ID</td><td>parcelLab RMA ID</td><td>parcelLab RMA ID</td></tr><tr><td><code>orderNo</code></td><td>Order Number</td><td>Order name</td><td>Order number</td></tr><tr><td><code>deliveryNo</code></td><td>Split Reference</td><td>Split/warehouse ref</td><td>Split/warehouse ref</td></tr><tr><td><code>transportNo</code></td><td>RMA Number</td><td>RMA Sequence ID</td><td>RMA Sequence ID</td></tr><tr><td><code>customerNo</code></td><td>Customer ID</td><td><em>not set</em></td><td>Customer ID</td></tr><tr><td><code>xid</code></td><td>External ID</td><td>Shopify Return GID</td><td>Return ID</td></tr></tbody></table>

**Tracking number on label** (`tracking_number`)

* The tracking number printed on the return shipping label
* Provided by the courier when label is generated
* Falls back to *parcelLab RMA ID* if no-label return

**parcelLab Courier code** (`courier`)

* Internal code identifying the shipping carrier (e.g., `'dhl-germany'`, `'ups'`)
* Defaults to `'return-registration'` for returns without labels

**parcelLab RMA ID** (`consignmentNo`)

* Unique identifier for RMA (format: 24 hexadecimal characters, a-f or number)

**Order number** (`orderNo`)

* Original order number from the source system
* For Shopify returns: Defaults to full order name, not order number without prefix or Shopify GID
* Non-Shopify: Order number as provided by the source system

**RMA Sequence ID** (`transportNo`)

* parcelLab sequentially generated RMA number, only unique for retailers account id
* Auto-generated with optional prefix (for example: "RMA00001"), but only if enabled

**Customer ID** (`customerNo`)

* Customer identifier from the original order system
* Preserved from source platform (Shopify customer ID, SAP customer number, and so on)

**External ID** (`xid`)

* External system reference for tracking purposes
* Shopify returns: Shopify GID in format `gid://shopify/Return/123`
* Non-Shopify: Uses *parcelLab RMA ID*

**Split Reference** (`deliveryNo`)

* Identifier for split returns going to different warehouses
* Only populated when return has multiple destinations

## Sample JSON Payload

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

{% file src="/files/-LQpdmT\_KbaAUYcpsf3X" %}
Sample payload
{% endfile %}


---

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