--- updatedAt: 2026-01-12T15:03:47.000Z agentTools: projectIndex: https://docs.supplierxm.salsify.com/llms.txt --- # Logistical hierarchies 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](https://docs.supplierxm.salsify.com/docs/retrieve-product) 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: ```json Logistical hierarchies {"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](https://docs.supplierxm.salsify.com/docs/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. ```text Main Hierarchy {"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" } } }] }]} ]} ``` ## activeListing (retailer only) Indicates whether the logistical hierarchy has an active listing. When a supplier shares a listing with a retailer, **activeListing** is set to *True*. It remains *True* whether the retailer accepts the listing or not. If the retailer refuses the listing, or the listing is removed, **activeListing** is set to *False*. If the supplier modifies the GTIN at the *highest level* of the shared logistical hierarchy, this will be considered a *new* logistical hierarchy. The retailer might then see two logistical hierarchies: the old one, with **activeListing** set to *False*, and the new one with the modified GTIN and **activeListing** set to *True*.