Logistical hierarchies describe the way a consumer or display unit is packaged to be shipped and delivered to the store or warehouse of the recipient (typically a retailer).

A logistical hierarchy's structure and content are contained in the logisticalHierarchies attribute that is attached to the consumer or display units shared by the source (typically a supplier).

Shared consumer and display units are part of the logistical hierarchy. However only basic information is provided in the logisticalHierarchies attribute for those units. The Product List API must be called to retrieve all the information for consumer and display units.

Structure of a logistical hierarchy

Logistical hierarchies have a tree structure. Every item in the hierarchy contains the following information:

{"logisticalHierarchies": [{
        "version": {
            "isConsumerUnit": false,
            "specializes": {
                "isBrandedBy": null,
                "isIdentifiedBy": [{"reference": "01234567890111"}],
                "kind": null
            },
            "tags": {
                "contentOwner": "",
                "targetMarket": ""
            },
            "gtin": "01234567890111",
            "namePublicLong": [{
                "expressedIn": {
                    "code": "eng-GB",
                    "description": "English",
                    "label": "English",
                    "normalizedCode": "en"
                },
                "data": "Alkemics 50 Case"
            }],
            "updatedAt": "2018-01-26T11:56:04",
            "typePackaging": {
                "code": "CASE",
                "description": "Case",
                "label": "case"
            },
            "lifeCycle": 1,
            "createdAt": "2018-01-26T11:56:04"
        },
        "gtin": "01234567890111",
        "children": [{
            "version": {
                "isConsumerUnit": true,
                "tags": {
                    "contentOwner": "",
                    "targetMarket": ""
                },
                "specializes": {
                    "isBrandedBy": null,
                    "isIdentifiedBy": [{"reference": "01234567890222"}],
                    "kind": null
                },
                "lifeCycle": 0,
                "nameLegal": [{
                    "expressedIn": {
                        "code": "eng-GB",
                        "description": "English",
                        "label": "English",
                        "normalizedCode": "en"
                    },
                    "data": "Alkemics Chocolate Milk"
                }],
                "gtin": "01234567890222",
                "namePublicLong": [{
                    "expressedIn": {
                        "code": "eng-GB",
                        "description": "English",
                        "label": "English",
                        "normalizedCode": "en"
                    },
                    "data": "Alkemics Chocolate Milk"
                }],
                "namePublicShort": [{
                    "expressedIn": {
                        "code": "eng-GB",
                        "description": "English",
                        "label": "English",
                        "normalizedCode": "en"
                    },
                    "data": "Alkemics Chocolate Milk"
                }],
                "updatedAt": "2018-01-26T11:57:55",
                "typePackaging": {
                    "code": "EACH",
                    "description": "Base unit",
                    "label": "Base unit"
                },
                "isDisplayUnit": false,
                "createdAt": "2018-01-26T11:56:02"
            },
            "gtin": "01234567890222",
            "children": [],
            "quantity": 50
        }]
    }]}

gtin

GTIN of the specific hierarchical level (logistical unit). Every logistical unit must be identified by a unique and valid GTIN.

uuid

We generate a UUID to uniquely identify each level of a product.

children

Link to the child logistical unit(s). A logistical unit can have multiple logistical children with a different GTIN. This element is always empty at the lowest level of the hierarchy.

quantity

Indicates how many of this logistical units are contained in the parent logistical unit.

version

This includes all product information provided for a specific logistical unit identified by a GTIN.

The list of available product information attributes is available in our Attributes documentation. On this page, you can filter attributes to see only the fields available for a specific hierarchy level.

Within the version element, typePackaging describes the hierarchy level of the trade item. It corresponds to the TradeItemUnitDescriptorCode GDSN attribute. The possible values for this attribute are listed below:

Alkemics code	Definition	GDSN code
EACH	The lowest level of the hierarchy that is intended or labeled for individual resale	BASE_UNIT_OR_EACH
PACK	A logistical unit between case and each. This may be a consumable inner pack (e.g. a pack of cigarettes) or simply a logistical pack (e.g. a dozen toothbrushes)	PACK_OR_INNER_PACK
CASE	A standard trade item shipping unit that contains one or multiple GTINs. Includes a ½ or ¼ pallet and a ½ or ¼ box pallet	CASE
PALLET	A unit load that contains one or multiple GTINs. Includes box pallet	PALLET

isMainHierarchyUnit

On a product, all logistical hierarchies associated with it will be shared with the boolean isMainHierarchyUnit set to True.

This product may also be a part of a pack or a Display Unit, shared separately. In this case, the attribute isMainHierarchyUnit is set to True in the main logistical hierarchy, and set to False in the logistical hierarchies of the pack or Display Unit.

N.B: isMainHierarchyUnit is not mandatory in secondary logistical hierarchies.

{"logisticalHierarchies": [
    {"gtin": "03663836022249",
    "version": {
        "gtin": "03663836022249",
        "typePackaging": {
            "code": "PALLET"
        }
    },
    "children": [{
        "product_key_id": 2627878,
        "gtin": "03663836022233",
        "quantity": 2,
        "isConsumerUnit": false,
        "version": {
            "gtin": "03663836022233",
            "typePackaging": {
                "code": "CASE",
                "label": "colis"
            }
        },
        "children": [{
            "product_key_id": 2627866,
            "gtin": "01234567891222",
            "quantity": 4,
            "version": {
                "gtin": "01234567891222",
                "typePackaging": {"code": "PACK"}
            },
            "children": [{
                "product_key_id": 2627865,
                "gtin": "03962400029005",
                "quantity": 6,
                "isMainHierarchyUnit": true,
                "version": {
                    "gtin": "03962400029005",
                    "typePackaging": {"code": "EACH",}
                }
            }]
        }]}
    ]},
    {"gtin": "03663836022233",
    "version": {
        "gtin": "03663836022233",
        "typePackaging": {
            "code": "CASE"
        }
    },
    "children": [{
        "product_key_id": 2627866,
        "gtin": "01234567891222",
        "quantity": 4,
        "version": {
            "gtin": "01234567891222",
            "typePackaging": {
                "code": "PACK",
                "label": "pack"
            }
        },
        "children": [{
            "product_key_id": 2627893,
            "gtin": "03962400029005",
            "quantity": 6,
            "isConsumerUnit": true,
            "version": {
                "gtin": "03962400029005",
                "typePackaging": {
                    "code": "EACH",
                    "label": "unité de base"
                }
            }
        }]
    }]}
]}