Understanding logistical hierarchies
In SupplierXM you can create and manage your logistics both in the platform and using our read/write APIs.
A logistical hierarchy is a tree of elements, usually starting with a pallet. In this article we will take the logistics below as an example:
Pallet: 23663836037988 (x1)
└── Case: 13663836037981 (x10)
└── Pack: 03663836037984 (x20)
└── Each: 03091033779527 (x20)
In this example, 1 pallet contains 10 cases, each case contains 20 packs and each pack contains 20 elements.
The total amount of 03091033779527 elements in pallet 23663836037988 is: 1 × 10 × 20 × 20 = 4000
SupplierXM platform view of a logistic
The logistic structure is not predetermined: you can have 2 or many more levels (4 in our example).
Less common, but you can also see the case of heterogeneous pallets and cases, which contain two or more sub-levels with different GTINs, e.g.: a Pallet that contains a Case with GTIN A and another Case of GTIN B.
The logistical tree is attached to each consumer unit or display unit. The first level of the SupplierXM API response JSON is always a consumer unit (isConsumerUnit = true) or a display unit (isDisplayUnit = true).
The root key to start browsing your logistic is logisticalHierarchies. It contains a list of all the logistics attached to your current product.
Note: You can get the full tree under logisticalHierarchies either by filtering by 03663836037984 (PACK and isConsumerUnit = true) or 03091033779527 (EACH and isConsumerUnit = true) cf. JSON payload below.
What is a Display Unit ?
A display unit is usually directly present in the aisles of a physical store.
isDisplayUnitis an indicator as to whether the trade item is, or could be used, as a display unit.A display unit can only contain consumer units.
{
"gtin": "03091033779527",
"logisticalHierarchies": [
{
"gtin": "23663836037988",
"uuid": "e770afe6-e4f5-11e9-81b4-2a2ae2dbcce4",
"version": {
"gtin": "23663836037988",
"isConsumerUnit": false,
"typePackaging": {
"code": "PALLET"
}
},
"quantity": 1,
"children": [
{
"gtin": "13663836037981",
"uuid": "fbf178ec-e4f5-11e9-81b4-2a2ae2dbcce4",
"quantity": 10,
"version": {
"gtin": "13663836037981",
"isConsumerUnit": false,
"typePackaging": {
"code": "CASE"
}
},
"children": [
{
"gtin": "03663836037984",
"uuid": "052098da-e4f6-11e9-81b4-2a2ae2dbcce4",
"quantity": 20,
"version": {
"gtin": "03663836037984",
"isConsumerUnit": true,
"typePackaging": {
"code": "PACK"
}
},
"children": [
{
"gtin": "03091033779527",
"uuid": "0aa3f16c-e4f6-11e9-81b4-2a2ae2dbcce4",
"quantity": 20,
"version": {
"gtin": "03091033779527",
"isConsumerUnit": true,
"typePackaging": {
"code": "EACH"
}
},
"children": []
}
]
}
]
}
]
}
]
}
<?xmlversion='1.0'encoding='UTF-8'?>
<productsxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<version>2.0</version>
<feedDate>2020-04-20T15:00:00</feedDate>
<contentOwner>
<gln>3663215000011</gln>
</contentOwner>
<product>
<gtin>03091033779527</gtin>
<quantity>1</quantity>
<logisticalHierarchies>
<logisticalHierarchies>
<product>
<gtin>23663836037988</gtin>
<uuid>e770afe6-e4f5-11e9-81b4-2a2ae2dbcce4</uuid>
<version>
<typePackaging>PALLET</typePackaging>
<gtin>23663836037988</gtin>
<isConsumerUnit>false</isConsumerUnit>
</version>
<quantity>1</quantity>
<children>
<product>
<gtin>13663836037981</gtin>
<uuid>fbf178ec-e4f5-11e9-81b4-2a2ae2dbcce4</uuid>
<version>
<typePackaging>CASE</typePackaging>
<gtin>13663836037981</gtin>
<isConsumerUnit>false</isConsumerUnit>
</version>
<quantity>10</quantity>
<children>
<product>
<gtin>03663836037984</gtin>
<uuid>052098da-e4f6-11e9-81b4-2a2ae2dbcce4</uuid>
<version>
<typePackaging>PACK</typePackaging>
<gtin>03663836037984</gtin>
<isConsumerUnit>true</isConsumerUnit>
</version>
<quantity>20</quantity>
<children>
<product>
<gtin>03091033779527</gtin>
<uuid>0aa3f16c-e4f6-11e9-81b4-2a2ae2dbcce4</uuid>
<version>
<typePackaging>EACH</typePackaging>
<gtin>03091033779527</gtin>
<isConsumerUnit>true</isConsumerUnit>
</version>
<quantity>20</quantity>
</product>
</children>
</product>
</children>
</product>
</children>
</product>
</logisticalHierarchies>
</logisticalHierarchies>
</product>
</products>
You can browse the whole tree by descending recursively through the children node. Once it has 0 elements, you are at the lowest level of the tree.
# This sample show how to navigate recursively in a logistic.
# we consider alk_data to equal the previous json sample
def recursively_browse_logistic_tree(node, depth=0):
print ' ' * depth + '- %s is a %s (x%d)' % (
node['gtin'],
node['version']['typePackaging']['code'],
node['quantity']
)
for child in node.get('children') or []:
recursively_browse_logistic_tree(child, depth + 1)
for logistic in alk_data['logisticalHierarchies']:
recursively_browse_logistic_tree(logistic)
# - 23663836037988 is a PALLET (x1)
# - 13663836037981 is a CASE (x10)
# - 03663836037984 is a PACK (x20)
# - 03091033779527 is a EACH (x20)
Every node of the hierarchy is represented as follows:
gtin: GTIN of the current node (example: 23663836037988)uuid: unique ID of the product to differentiate multiple products with the same GTIN (example: 35c81f26-e4f6-11e9-a359-2a2ae2dbcce4)version:
-- WhenisConsumerUnit= false andisDisplayUnit= false --> every logistical information
-- WhenisConsumerUnit= true orisDisplayUnit= true -> a small subset of the data. If you want the whole data you either already have it from your current query at the root level (for 03091033779527 in our example) or with a new query on the other GTINs (03663836037984 in our example)
example:
{
"gtin": "23663836037988",
"typePackaging": {
"code": "PALLET"
},
"orderQuantityMinimum": 1,
"isInvoiceUnit": true,
"orderQuantityMultiple": 1,
"isPackagingMarkedReturnable": false,
"isDespatchUnit": true,
"netWeight": [
{
"expressedIn": {
"code": "kg"
},
"data": 480
}
],
"orderingUnitOfMeasure": {
"code": "pce"
}
}
quantity: quantity of elements per parent unit. (example: 42)children: list of children nodes whose parent is the current node
(one child in our example)
[
{
"gtin": "03091033779527",
"quantity": 20,
"version": {
"gtin": "03091033779527",
"isConsumerUnit": true,
"typePackaging": {
"code": "EACH"
}
},
"children": []
}
]
Best practice
For consumer units or display units you must get the data from the root level of your product, and not from the version tag of the
logisticalHierarchiestree. (version contains only a subset of the data)
03663836037984and03091033779527in our example
For logistical elements, all the information is under the version key.
The data is described as classic data from the attribute documentation . Here is an example:
{
"gtin": "03091033779527",
"logisticalHierarchies": [
{
"gtin": "23663836037988",
"uuid": "e770afe6-e4f5-11e9-81b4-2a2ae2dbcce4",
"version": {
"gtin": "23663836037988",
"isConsumerUnit": false,
"typePackaging": {
"code": "PALLET"
},
"namePublicLong": [
{
"expressedIn": {
"code": "eng-GB"
},
"data": "pallet - Name of the product"
}
],
"startAvailabilityDateTime": 1583107200,
"tags": {
"targetMarket": 826
}
},
"quantity": 1,
"children": [
{
"gtin": "13663836037981",
"uuid": "fbf178ec-e4f5-11e9-81b4-2a2ae2dbcce4",
"quantity": 10,
"version": {
"gtin": "13663836037981",
"isConsumerUnit": false,
"typePackaging": {
"code": "CASE"
},
"namePublicLong": [
{
"expressedIn": {
"code": "eng-GB"
},
"data": "case - Name of the product"
}
],
"startAvailabilityDateTime": 1583107200,
"tags": {
"targetMarket": 826
}
},
"children": [
{
"gtin": "03663836037984",
"uuid": "052098da-e4f6-11e9-81b4-2a2ae2dbcce4",
"quantity": 20,
"version": {
"gtin": "03663836037984",
"isConsumerUnit": true,
"typePackaging": {
"code": "PACK"
},
"namePublicLong": [
{
"expressedIn": {
"code": "eng-GB"
},
"data": "pack - Name of the product"
}
],
"startAvailabilityDateTime": 1583107200,
"tags": {
"targetMarket": 826
}
},
"children": [
{
"gtin": "03091033779527",
"uuid": "0aa3f16c-e4f6-11e9-81b4-2a2ae2dbcce4",
"quantity": 20,
"version": {
"gtin": "03091033779527",
"isConsumerUnit": true,
"typePackaging": {
"code": "EACH"
},
"namePublicLong": [
{
"expressedIn": {
"code": "eng-GB"
},
"data": "Name of the product"
}
],
"startAvailabilityDateTime": 1583107200,
"tags": {
"targetMarket": 826
}
},
"children": []
}
]
}
]
}
]
}
]
}
<product>
<namePublicLong languages="eng-GB">pallet - Name of the product</namePublicLong>
<startAvailabilityDateTime>2020-03-02</startAvailabilityDateTime>
<typePackaging>PALLET</typePackaging>
<gtin>23663836037988</gtin>
<tags>
<targetMarket>
<id>826</id>
</targetMarket>
</tags>
<quantity>1</quantity>
<children>
<product>
<namePublicLong languages="eng-GB">case - Name of the product</namePublicLong>
<startAvailabilityDateTime>2020-03-02</startAvailabilityDateTime>
<typePackaging>CASE</typePackaging>
<gtin>13663836037981</gtin>
<tags>
<targetMarket>
<id>826</id>
</targetMarket>
</tags>
<quantity>266</quantity>
<children>
<product>
<namePublicLong languages="eng-GB">Name of the product</namePublicLong>
<startAvailabilityDateTime>2019-03-01</startAvailabilityDateTime>
<typePackaging>EACH</typePackaging>
<gtin>03091033779527</gtin>
<tags>
<targetMarket>
<id>826</id>
</targetMarket>
</tags>
<quantity>6</quantity>
</product>
</children>
</product>
</children>
</product>
Pro-Tip:
You can use the same serializer/deserializer you use at the root level to serialize/deserialize a
versionnode, the structure is the same.
To get all available attributes for logistics per packaging type, you can filter the attributes documentation:
Example of filter to see fields you can find on logistical unit for typePackaging (Case and Pallet)
Updated over 1 year ago
Check out the following page to understand what data you can update or get in the version node: