Data Model

The data model covers the foundational elements of a tracking and order record in the parcelLab system via our API v4 Enhanced (preview).

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.

Please use PUT v4/track/orders as the default endpoint to create new trackings and orders in the API v4 Enhanced (preview).

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

Carrier Codes

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

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.

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.

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

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.

Keys for Notifications

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

Some of the following keys may be required to enable additional product functionality.

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

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

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.

Key	Type	Necessity	Description
first_name	String	Optional	First name of the billing recipient.
last_name	String	Optional	Last name of the billing recipient.
company_name	String	Optional	Company name of the billing recipient.
address_line	String	Required	Street and house number of the billing recipient.
address_line_extra	String	Optional	Additional address line of the billing recipient.
postal_code	String	Required	Postal (zip) code of the billing recipient.
city	String	Required	City of the billing recipient.
country_iso3	ISO 3166-1 alpha-3	Required	Country of the billing recipient (for example: DEU).
region_code	ISO 3166-2 alpha-2	Optional	State or province code of the billing recipient.
phone	String	Optional	Phone number of the billing recipient.

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.

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.

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

Some of the following keys may be required to enable additional product functionality.

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

A list of articles looks like this:

article-list.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
  },

  ...
]

Custom Fields

The API v4 Enhanced (preview) standardises common use cases that previously required custom fields. Therefore, many of the common fields can now be directly used in the standard parameters.

Custom fields can be used to add additional content to the notifications that does not fit in any other field. These are written in additional_fields in the tracking array in the mutations of the /v4/track/orders endpoint. Custom fields can be set individually but must be coordinated with parcelLab. Multiple custom fields can be submitted as a list of custom fields.

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.

Keys of additional_fields 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.

tracking-with-custom-fields.json

"mutations": [
        {
            "type": "add_tracking",
            "tracking": {
                "tracking_number": "0035999222335558TEST",
                "courier": "postnord",
                "courier_service_level": "STANDARD",
                "additional_fields": {
                    "locationCode": "012"
                    "pickupBoxCabinNo": "48"
                }
            }
        }
    ]

Tags

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

Tags are important to be able to filter trackings on custom attributes as information specified in custom fields is not searchable.

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

tracking-with-tags.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"]
}

Sample JSON Payload

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

2KB

sample-payload.json