Required data when operating carriers

For successful carrier operations, specific data is required. It is a best practice to provide this data in the relevant entities. This guide outlines the required data, its recommendation level, and the correct location for it.

Data recommendation levels

The data fields are categorized into three levels:

• Mandatory: The system cannot process a shipment without this information.

• Recommended: Providing this data is highly recommended for smooth operations, especially for international shipments. For the best results, always provide all Mandatory and Recommended information.

• Optional: This data is not required for standard operations but can support specific carrier features or workflows.

Overwriting default values

fulfillmenttools provides the flexibility to override default data, such as addresses, for specific workflows without altering the original source entities like a facility. The override hierarchy for each data type is explicitly documented in the following sections.

Parcel source

This section describes the data required to identify the origin of a parcel.

Recommendation Level	Parameter	Source
Mandatory	Source Address	facility.address
Recommended	Telephone Number	facility.address.phoneNumbers
Recommended	Email Address	facility.address.emailAddresses

Overwriting source Address of shipments

parcel.sender ▷ shipment.sourceAddress ▷ facility.address (default)

(▷ = left overwrites right)

Consumer / Target of a parcel

Recommendation Level	Parameter	Source
Mandatory	Consumer or target postal address, including a house number	order.consumer.addresses[addressType = POSTAL_ADDRESS]
Recommended	Consumer telephone number	order.consumer.addresses[addressType = POSTAL_ADDRESS].phoneNumbers[0]
Recommended	Consumer email address	order.consumer.email

Overwriting target address of shipments

Regarding address and phone numbers

parcel.recipient ▷ shipment.targetAddress ▷ order.consumer.addresses[addressType = POSTAL_ADDRESS] (default)

Regarding email address

parcel.recipient ▷ shipment.targetAddress ▷ order.consumer.email (default) ▷ carrier.configuration.fallBackTrackAndTraceEmail (fallback)

(▷ = left overwrites right)

Customs / International Shipments

The following data is especially important when sending non-domestic shipments. However, best-practice is to always provide this data / provide it in listings of facilities that are performing international shipments.

Recommendation Level	Parameter	Source
Recommended	HS Code (preferably 8 digits) The Harmonized Commodity Description and Coding System, also known as the Harmonized System (HS) of tariff nomenclature is an internationally standardized system of names and numbers to classify traded products. (...) -- Source: Wikipedia	order.orderLine.article.attributes { "category": "customs", "key": "hsCode", "value": "<8-digit HS Code>", "type": "STRING" }
Recommended	Customs value per unit The value of the good per unit in the smallest indivisible unit of the currency. For example: Cents for EUR (25 EUR have the value 2500) or piastres for EGP (50 EGP have the value 5000). This value will be used when you request labels for non-domestic shipments. Taking the goods that are inside a parcel into consideration the customs value is calculated. The value of a unit is multiplied with the quantity of items present in the parcel.	order.orderLine.article.attributes { "category": "customs", "key":"valuePerUnit", "value": ", for example: 20000", "type":"NUMBER" }
Recommended	Customs currency This value depicts the currency used for providing customs related data in ISO-4217 when requesting a parcel label.	order.orderLine.article.attributes { "category": "customs", "key": "currency", "value": "", "type": "CURRENCY" }
Recommended	Customs number of decimal places This number depicts the number of decimal places used for the currency and value per unit. Note: If not passed, this value will be filled automatically upon item creation according to ISO-4217.	order.orderLine.article.attributes { "category": "customs", "key": "numberOfDecimalPlaces", "value": "", "type": "NUMBER" }

Overwriting customs related data

orderLine.article.attributes ▷ listing.attributes

(▷ = left overwrites right)

Insured shipments

fulfillmenttools supports providing insurance-related data to carriers. The system uses these values to calculate the total insurance value of a parcel before requesting a label.

Recommendation-Level	Parameter	taken from
Recommended	Insurance value per unit The value of the good per unit in the smallest indivisible unit of the currency. For example: Cents for EUR (25 EUR have the value 2500) or piastres for EGP (50 EGP have the value 5000).	order.orderLine.article.attributes { "category": "insurance", "key": "valuePerUnit", "value": "", "type": "NUMBER" }
Recommended	Insurance currency The currency of the insurance value in ISO 4217 format.	order.orderLine.article.attributes { "category": "insurance", "key": "currency", "value": "", "type": "CURRENCY" }
Recommended	Insurance number of decimal places This number depicts the number of decimal places used for the currency and value per unit. Note: If not passed, this value will be filled automatically upon item creation according to ISO-4217.	order.orderLine.article.attributes { "category": "customs", "key":"numberOfDecimalPlaces", "value":"<the number of decimal Places>", "type":"NUMBER" }

Overwriting insurance related data

orderLine.article.attributes ▷ listing.attributes

(▷ = left overwrites right)

Attribute Categories Are Independent Attribute categories like customs and insurance are distinct. The system does not fall back from one category to another. For example, customs data must be provided in the customs category; the system will not use values from the insurance category as a substitute.

Physical dimensions and weight

Recommendation-Level	Parameter	taken from
Recommended	Weight of a single item (in grams)	order.orderLine.article.attributes { "category": "dimensions", "key": "weightPerUnit", "value": "", "type": "NUMBER" }
Optional	Height of a single item (in mm)	order.orderLine.article.attributes { "category": "dimensions", "key": "height", "value": "", "type": "NUMBER" }
Optional	Width of a single item (in mm)	order.orderLine.article.attributes { "category": "dimensions", "key": "width", "value": "", "type": "NUMBER" }
Optional	Length of a single item (in mm)	order.orderLine.article.attributes { "category": "dimensions", "key": "length", "value": "", "type": "NUMBER" }

Overwriting dimensional data

orderLine.article.attributes ▷ listing.attributes

(▷ = left overwrites right)