GS1 field reference

Hii Retail accepts a profile of the GS1 eCom Despatch Advice message (urn:gs1:ecom:despatch_advice:xsd:3) — the XML standard used across retail supply chains to tell a receiver what has been shipped.

The profile is close to the standard. It differs in two narrow ways:

• A small number of otherwise-optional elements are mandatory — the expected delivery time and a per-line amount with its currency. Goods Received cannot place a delivery in time or value them without these.
• Elements the standard defines but Hii Retail does not use are ignored. They do not cause a rejection.

Everything else follows GS1. If your system already produces despatch advices, the work is usually adding the two mandatory elements and making sure the receiving store is identifiable — not building a new document.

For how to send the document, see GS1 import. For a complete example, see GS1 XML example.

What the import requires

Header

Element	Required	Becomes	Notes
despatchAdviceIdentification/entityIdentification	✅	The delivery note number	Must be stable and unique per shipper — it is part of the delivery's identity
note	➖	The delivery's comment	Free text from the supplier or warehouse
receiver/gln	⚠ one of	The receiving store	Resolved via Business Unit Management
receiver/additionalPartyIdentification type businessUnitId	⚠ one of	The receiving store	Used directly, no lookup. Preferred
shipper/additionalPartyIdentification type businessPartnerId	⚠ one of	An external shipper	Send this when the shipper is a supplier or warehouse
shipper/additionalPartyIdentification type businessUnitId	⚠ one of	Another store as shipper	Preferred when the goods come from another store
shipper/gln	⚠ one of	The shipping business unit or supplier	Resolved via Business Unit Management, then Business Partner. See Identifying the store
shipper/organisationDetails/organisationName	➖	The shipper's name	Display name only
despatchInformation/estimatedDeliveryDateTime	✅	The delivery date	ISO 8601. Mandatory in this profile although GS1 treats it as optional

At least one of receiver/gln and the receiver's businessUnitId must be present, and likewise at least one of the shipper's businessPartnerId, businessUnitId and gln. Sending business unit ids is recommended — see Identifying the store.

Logistic units (containers)

Element	Required	Becomes	Notes
despatchAdviceLogisticUnit	✅	A container	One or more. Lines live inside logistic units
logisticUnitIdentification/sscc	✅	The container id
parentLogisticUnitId/sscc	➖	The parent container	Omit on the outermost unit. Nesting may be any depth

A logistic unit may hold lines, hold only other units, or both. The common shape is one root pallet holding no lines of its own, with the lines in its child units.

⚠ Lines are always inside a logistic unit. A line item placed outside any logistic unit is rejected as invalid GS1, so a document is refused rather than imported with a line missing. Nesting, though, is not required. A shipment that is not palletised is sent as one logistic unit with an SSCC, holding every line, and no parentLogisticUnitId.

Lines

Element	Required	Becomes	Notes
lineItemNumber	✅	The line id	Unique across the whole document, not per container
despatchedQuantity	✅	The expected quantity	May be fractional for weighed or measured items
transactionalTradeItem/gtin	⚠ one of	The line's GTIN
transactionalTradeItem/additionalTradeItemIdentification type itemId	⚠ one of	The Hii Retail item id	Preferred. Send this and the GTIN becomes optional
transactionalItemData/batchNumber	➖	The batch number
transactionalItemData/bestBeforeDate	➖	The best-before date
transactionalItemData/itemExpirationDate	➖	The expiration date
transactionalItemData/serialNumber	➖	Serial numbers	May repeat
purchaseOrder	➖	The originating order	Omit for a delivery not raised against an order
purchaseOrder/entityIdentification	⚠	The order id	Required if purchaseOrder is present
purchaseOrder/lineItemNumber	➖	The order line id
totalLineAmount	✅	The line's unit price
totalLineAmount@currencyCode	✅	The line's currency
customer/additionalPartyIdentification type customerId	➖	The customer order reference	Send when the goods are reserved for a named customer

At least one of the GTIN and the item id must be present, and which one you send changes how failures behave — see Identifying items. Sending both is normal and is the most robust option: the item id is what resolves the line, and the GTIN travels through to consumers.

⚠ A missing ✅ field is rejected immediately; an unresolvable item is not. Everything in the tables above is checked against the document itself and answered with 400 before the request returns. Identifying an item is different — it needs data from outside the document, so it happens after the caller has been given 202, and a GTIN that does not resolve fails silently as far as the sender is concerned. Always confirm the import landed.

What is ignored

GS1 despatch advices commonly carry elements this profile does not read. They are harmless — the document is not rejected for containing them — but nothing in Hii Retail will reflect them:

Ignored	Use instead
documentStatusCode, creationDateTime, contentOwner	—
shipTo	receiver
actualShipDateTime, despatchInformation/despatchDateTime	despatchInformation/estimatedDeliveryDateTime
countryOfOrigin, packageTypeCode	—
requestedItemIdentification	transactionalTradeItem/gtin and the itemId identification
Any other GS1-compliant element	—

🛑 shipTo is not the receiver. A generator that identifies the destination store with shipTo and leaves receiver empty will be rejected, because the receiving store cannot be resolved. This is the most common reason a working GS1 export fails against Hii Retail.

Mapping to a delivery

Once accepted, the document becomes one delivery:

GS1	Delivery
entityIdentification	Delivery note number
receiver	The receiving store
shipper + its identification type	The shipper, and whether it is a store or an external partner
organisationName	Shipper name
estimatedDeliveryDateTime	Delivery date
note	Comment
Outermost despatchAdviceLogisticUnit	Root container
Each despatchAdviceLineItem	A delivery line, with its container chain
despatchedQuantity	Expected quantity — never the approved one

The import only ever sets expected quantities. What was actually accepted is decided by the store and published afterwards — see Quantities and adjustments.

Further reading

The GS1 standard itself is documented by GS1; this page covers only where Hii Retail differs from it. The example document is a known-good starting point — adapting it is usually faster than adapting a generic GS1 export.