Data Model

The data model covers the foundational elements of a tracking and order record in the parcelLab system via our API v2 LTS.

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.

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.

Required Keys for Trackings

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

This tracking information can be sent with the corresponding order number using the order endpoint.

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

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

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.

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.

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.

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

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

Key	Type	Necessity	Description
deliveryNo	String	Optional	Internal delivery number.
customerNo	String	Optional	Internal customer number.
consignmentNo	String	Optional	Consignment number identifying the parcel.
weight	String	Optional	Weight of the package.
courierServiceLevel	String	Optional; Required for Promise	Product or service level from carrier.
warehouse	String	Optional; Required for Promise	Warehouse from which the delivery was shipped.
market	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.
cashOnDelivery	Number	Optional	The cash on delivery (COD) amount.
branchDelivery	Boolean	Optional	Whether the shipment is a branch delivery.
statuslink	String	Optional	Alternative status link.
order_date	Date / DateTime	Optional	Date of ordering by customer.
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_info property.

These fields are all optional.

Key	Type	Description
name	String	Full name of the billing recipient.
phone	String	Phone number of the billing recipient.
email	String	Email address of the billing recipient.
street	String	Street of the billing recipient.
city	String	City of the billing recipient.
zip_code	String	Postal code of the billing recipient.
region	String	State of the billing recipient.
country_iso3	String	Country of the billing recipient.

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.

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

Key	Type	Necessity	Description
articleNo	String	Required	Article number.
articleName	String	Required	Article name.
articleCategory	String	Optional; Required for Category-Based Return Reasons	Article category.
articlePrice	Numeric	Optional; Required for: Returns Portal Customer Segmentation
articleUrl	String	Optional; Required for Product Recommendations	URL to the product page.
articleImageUrl	String	Optional; Required for Product Recommendations	Full URL to the product image
size	String	Optional	Article size.
color	String	Optional	Article color.
quantity	Numeric	Optional; Required for: Returns Portal Customer Segmentation Product Recommendations	Amount of the purchased product.
returnableQuantity	Numeric	Optional; Required for Already Returned Items feature	Quantity eligible for return.

A list of articles looks like this:

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

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:

tracking-with-custom-fields.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.
  }
}

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.

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"]
}

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.

Data Model Field	Name	Shopify	Non-Shopify
tracking_number	Tracking number on label	Courier label tracking	Courier label tracking
courier	Carrier Code	parcelLab Courier code	parcelLab Courier code
consignmentNo	Return ID	parcelLab RMA ID	parcelLab RMA ID
orderNo	Order Number	Order name	Order number
deliveryNo	Split Reference	Split/warehouse ref	Split/warehouse ref
transportNo	RMA Number	RMA Sequence ID	RMA Sequence ID
customerNo	Customer ID	not set	Customer ID
xid	External ID	Shopify Return GID	Return ID

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:

593B

sample-payload.json

Open

Sample payload