Required data when operating carriers

In order to allow for frictionless carrier operations certain data is needed and it is considered best practice to store / supply these in the entities used in the process. Please see the following table in order to find out which data is needed and where to provide it correctly.

Recommended data for shipping using fulfillmenttools

Recommendation Levels

We categorized the data needed for successful shipping operations into.

Mandatory You cannot send any parcel without this information

Recommended Providing this data is recommended - especially when doing international shipments

For a smooth operation we recommend to always provide all the information of Recommendation-Level Mandatory and Recommended - especially when dealing with international shipping!

Optional

Providing this data is optional.

Possibility to overwrite given values

fulfillmenttools offers the possibility to overwrite default values for the address used to request a label in the end. By default the facility address is taken when creating the shipment or the parcels. However, you can replace the address where the shipment is originating from if needed without the need of touching the facility address. This adds further flexibility when implementing your own workflows.

In which way overwriting values is supported is being mentioned in the following sections explicitly.

Facilities / Source of a parcel

Recommendation-Level	Parameter	taken from
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	taken from
Mandatory	Consumer or Target postal address (preferably with a housenumber)	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	taken from
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 of the good>, for example 0302110010 (Rainbow Trout)" }
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": "<the value of the good per unit in the smallest indivisible unit of the currency>, 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":"<the currency of the customs value, either EUR or USD>", "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":"<the number of decimal Places>", "type":"NUMBER" }

Overwriting customs related data

orderLine.article.attributes ▷ listing.attributes

(▷ = left overwrites right)

Field Deprecation of listing.legal.hsCode, listing.price and orderLineItem.shopPrice Providing the values using the above mechanism will overwrite already present values that were taken for calculation around customs that might be existent due to legacy reasons in listings or orderLineItems.

Insured shipments / Insurance values

fulfillmenttools offers the possibility to supply insurance relevant data to carriers. This is especially important for carriers, that offer this kind of service as the value of the parcels is calculated taking these values into consideration before the label is requested at the carrier.

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":<insurance value of the good per unit in the smallest indivisible unit of the currency>, "type": "NUMBER" }
Recommended	Insurance currency This value presents the currency in ISO-4217.	order.orderLine.article.attributes { "category": "insurance", "key":"currency", "value":"<the currency of the insurance 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)

No overwriting of non-insurance values from other categories

fulfillmentools offers the possibility to supply multiple values: Be it insurance related, customs related or similar. Please be aware: There is no fallback / overwriting mechanism between the different categories! In other words: If you need perform non-domestic shipments the customs data has to be provided in the customs category - there is no fallback to (maybe present) values of other categories like for example insurance and vice versa.

Physical dimensions & weight

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

Overwriting dimensional data

orderLine.article.attributes ▷ listing.attributes

(▷ = left overwrites right)