---
updatedAt: 2025-06-10T23:41:01.000Z
agentTools:
  projectIndex: https://docs.supplierxm.salsify.com/llms.txt
---

# 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

<Image title="asset-054b1c3e1fcd9bbe0fce07d50947fb5d.png" alt={567} src="https://files.readme.io/1cbc1fa-asset-054b1c3e1fcd9bbe0fce07d50947fb5d.png">
  SupplierXM platform view of a logistic
</Image>

> 📘 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. `isDisplayUnit` is 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.

```json
{
    "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": []
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
```
```xml
<?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.

```python
# 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`:\
  \-- When `isConsumerUnit` = false and `isDisplayUnit` = false --> every logistical information\
  \-- When `isConsumerUnit` = true or `isDisplayUnit` = 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:

```json
{
    "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)

```json
[
    {
        "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 `logisticalHierarchies` tree. (version contains only a subset of the data)\
> `03663836037984` and `03091033779527` in our example

For logistical elements, all the information is under the version key.\
The data is described as classic data from the [attribute documentation](https://docs.supplierxm.salsify.com/docs/attributes-documentation) . Here is an example:

```json
{
    "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": []
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
```
```xml
<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 `version` node, the structure is the same.

To get all available attributes for logistics per packaging type, you can filter the attributes documentation:

<Image title="asset-778df8214128944b3a9b71e041b80ebe.png" alt={798} src="https://files.readme.io/9adccf6-asset-778df8214128944b3a9b71e041b80ebe.png">
  Example of filter to see fields you can find on logistical unit for typePackaging (Case and Pallet)
</Image>