Data model

Our data model described the keys of the basic record in parcelLab, a tracking. A tracking can represent a parcel or a pallet, everything that is identified by a unique tracking number.

Required keys

All required keys must be supplied for every tracking

Key

Type

Description

courier

Courier code

short code of the courier (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 (e.g. DEU or DE)

For a list of allowed courier codes please refer here:

Creating orders

Orders cannot be explicitly created in parcelLab, but only implicitly. For each tracking in an order, simply a orderNo is given. This orderNo then links all trackings together and consolidate communications via email, SMS etc and also the tracking page.

Key

Type

Description

orderNo

String

Order number

Multi-shop setup

If several shops (e.g. shops with multiple domains, dedicated shops for specific countries, or otherwise individual CI) are used within one account, each tracking is assigned to a shop using the key client.

Key

Type

Description

client

String

client (Mandant in German) of the tracking in internal encoding

The values in the field client 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.

Keys required for notifications

To be able to send out sensible notifications to customers, the following keys are required/ strongly recommended.

Key

Type

Description

recipient_notification

String

name of the recipient used in notifications

email

String

email 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 (e.g. de for German)

Special Keys

These special keys alter how the system handles the trackings.

Key

Type

Description

return

Boolean

if true the delivery is handled as a return, i.e. by default no communication is sent to the set recipient, dispatch delays will not be monitored, and the tracking will not be considered for general reporting

cancelled

Boolean

if true delivery is cancelled, i.e. no communication is sent to the set recipient, all monitoring and reporting is disabled

Optional keys

These additional keys can be used to further individualise notifications.

Key

Type

Description

deliveryNo

String

internal delivery number

customerNo

String

internal customer number

weight

String

weight of the package

courierServiceLevel

String

product or service level from courier

warehouse

String

warehouse from where delivery was shipped

market

String

marketplace used for sale

complete

Boolean

whether the shipment is complete

upgrade

Boolean

whether the shipment has an upgrade or individualisation

cashOnDelivery

Number

the C.O.D. (Nachnahme) amount

branchDelivery

Boolean

whether the shipment is a branch delivery

statuslink

String

alternative status link

order_date

Date / DateTime

date of ordering by customer

send_date

Date / DateTime

announced dispatch/ send date

announced_delivery_date

Date

announced delivery date

All dates can be either be in the format YYYY-MM-DD or YYYY-MM-DD HH:mm:ss

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 field articles. 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
quantity: Integer, // optional
},
...
]

Custom fields

Custom fields can be used to add additional content to the notifications that doesn't 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 bust must be a String, values can be 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 custom field is not set, the placeholder will show an empty string ''.

Sample JSON payload

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