GS1 import

GS1 import is how an external system tells a store what is coming. A supplier's, warehouse's or ERP's despatch advice becomes a delivery the store can verify and approve. It is the only Goods Received ingress designed for machine-to-machine use, and the one an integration project should build against.

For the field-by-field reference, see the GS1 field reference. For a complete example document, see GS1 XML example.

Sending a document

Endpoint	POST /imports/deliveries/gs1
Body	multipart/form-data with the XML document as a file
Required header	Tenant-Id
Optional header	Correlation-Id — your own tracking id, echoed through the system. Generated if omitted
Permission	grc.delivery.import
Success	202 Accepted, with no body

⚠ The document is uploaded as a file, not posted as a JSON or XML request body. A client that sets Content-Type: application/xml and puts the document in the body will be rejected with 400. Attach the document as a file part.

One document creates one delivery. Batching several delivery notes into one upload is not supported — send one request per delivery note.

The document must be a GS1 despatch advice

The service reads the despatchAdvice element of a despatchAdviceMessage document in the GS1 despatch advice namespace (urn:gs1:ecom:despatch_advice:xsd:3), declared with the despatch_advice prefix:

<?xml version="1.0" encoding="UTF-8"?>
<despatch_advice:despatchAdviceMessage
    xmlns:despatch_advice="urn:gs1:ecom:despatch_advice:xsd:3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <despatchAdvice>
    ...
  </despatchAdvice>
</despatch_advice:despatchAdviceMessage>

⚠ Use the despatch_advice prefix exactly as shown. A document that binds the same namespace to a different prefix is not currently recognised and is rejected as an unreadable file.

⚠ Hii Retail accepts a profile of the standard, not every valid despatch advice. Two elements GS1 treats as optional are mandatory here — the expected delivery time and a per-line amount with its currency — and the receiving store must be identifiable. Elements Hii Retail does not use are ignored rather than rejected, so an existing GS1 export usually needs those additions and nothing else. Work through the GS1 field reference before the first test.

Identifying the store

GS1 identifies parties by GLN. Hii Retail identifies stores by business unit, so the receiver has to be resolved to one. There are two ways, and choosing the right one removes an entire class of failure:

Send	Resolution	Recommended
additionalPartyIdentification with type businessUnitId	Used directly. No lookup	✅ Use this when your system knows the Hii Retail business unit id
gln only	Looked up in Business Unit Management	Only when your system genuinely holds GLNs and not business unit ids

🛑 If you send a GLN, it must be registered against the business unit in Business Unit Management. An unregistered GLN fails the import with an explicit "business unit not found" error. This is the most common first-day integration failure. Sending the business unit id directly avoids the lookup altogether.

The shipper is identified the same way. Which identifier you send also decides how the delivery is classified:

Shipper sent as	Recorded as	Meaning
additionalPartyIdentification type businessPartnerId	businessPartnerId	An external supplier or warehouse. Used as sent, with no lookup
additionalPartyIdentification type businessUnitId	businessUnitId	Another business unit in the same tenant. Used as sent, with no lookup
gln only, held by one of your business units	businessUnitId	That business unit
gln only, held by no business unit	businessPartnerId	The business partner with that GLN

Send at least one of the three. A business partner id marks the shipper as external; a business unit id marks it as one of the tenant's own business units, which is what tells consumers the movement is internal rather than a purchase.

A shipper that carries only a GLN is looked up in Business Unit Management first, so a GLN that belongs to one of your stores or warehouses always resolves to it. Only when no business unit has the GLN is it looked up among your business partners:

Business partners with that GLN (any status except Deleted)	Result
exactly one	Imported, with that partner as the shipper. When the document has no organisationName, the partner's legal name becomes the shipper name
none	The import fails with Can't resolve delivery: no business unit or business partner with GLN <gln>
more than one	The import fails with Can't resolve delivery: GLN <gln> matches <n> business partners

🛑 A supplier GLN must be registered on exactly one business partner. If your suppliers identify themselves by GLN only, register each GLN on its partner in Business Partner, and do not give two partners the same GLN.

Identifying items

Each line identifies its item by GTIN, by Hii Retail item id, or by both. The item id is sent as an additionalTradeItemIdentification element with type code itemId.

The line carries	Behaviour
An item id	Accepted. The item is looked up for its name, and the line is kept even if the item is unknown
A GTIN only	The GTIN must resolve to an item for that store. If it does not, the whole delivery is rejected

🛑 Send the item id whenever your system holds it. One unresolvable barcode fails the entire delivery, not the single line — so a GTIN-only integration is only as reliable as the barcode data set up for every item in every store you ship to. Sending the item id makes the import robust at no cost to the sender.

If you can only identify items by GTIN, make sure every GTIN you will ship is set up against an item for every store you ship to, in Product, Price and Promotion.

Containers

Lines are grouped into logistic units — pallets, cages, boxes — each identified by an SSCC. A logistic unit can name a parent, which is how a pallet containing several cages is expressed. The nesting can be any depth.

Every line records the full chain of containers it sits in, so a store can approve a whole pallet or a single cage.

Because the ids are the SSCCs from your document, staff can scan a label to find and approve what is inside it — read the pallet or cage, see the lines it should contain, approve the lot. Sending accurate SSCCs is what makes that work; there is no other way for Hii Retail to connect a physical label to a delivery.

A worked example, matching the example document:

  SSCC 124523678524552123                (root pallet, no lines of its own)
   ├── SSCC 123456789123456785
   │     ├── line 1   GTIN 12345678901235   item 41   qty 10   serials ×2   order OrderNumber1/1
   │     └── line 2   GTIN 12345678901235   item 42   qty 10   serials ×2   order OrderNumber2/2
   └── SSCC 123456789123456786
         ├── line 3   GTIN 12345678901236   item 41   qty 10   batch batchnumber1   order OrderNumber3/3
         ├── line 4   GTIN 12345678901236   item 42   qty 10   batch batchnumber1   order OrderNumber4/4
         └── line 5   GTIN 12345678901236   item 43   qty 10   batch batchnumber1   order OrderNumber5/5

Root container	124523678524552123
Sub-containers	123456789123456785, 123456789123456786
Lines	5
GTINs	12345678901235, 12345678901236
Orders	OrderNumber1 … OrderNumber5
Customer order	12345, on the lines in 123456789123456786 only

Lines 3 to 5 are reserved for a customer order, which is carried per line — so one delivery can mix ordinary replenishment with goods for a named customer.

⚠ Line numbers must be unique across the whole document, not merely within a logistic unit. Two logistic units that both number their first line 1 will be rejected. Number lines sequentially across the document.

Re-sending and retries

A delivery's identity comes from the receiving store, the delivery note number and the shipper. Sending the same document again therefore refers to the same delivery, and the repeat is ignored rather than creating a duplicate.

That makes retries safe: if a request times out or fails in a way that leaves you unsure whether it arrived, send it again.

🛑 The delivery note number must be stable and unique per shipper. A sending system that generates a fresh number on each retry will create duplicate deliveries; one that reuses numbers across shipments will silently merge a new shipment into an old delivery. If your system has no stable document number, derive one from the shipment id.

Re-sending a changed document does not update the delivery. Once a delivery exists, corrections are made by the receiving store — see Delivery lifecycle.

Confirming an import landed

The import is asynchronous. 202 Accepted means the document was valid and its parties resolved — not that the delivery now exists.

🛑 One class of failure happens after the 202 and is not reported back to the caller: item resolution. Whether a GTIN corresponds to an item is a question about master data, not about the document, so it can only be answered once the request has already been answered. A GTIN that does not resolve fails the delivery at that point, and nothing is sent to the sending system.

Everything that can be judged from the document itself — required fields, duplicate line numbers, an unregistered GLN — is answered synchronously with 400. So the shape of your document is confirmed by the response; the resolvability of your item data is not.

So for an unattended integration, confirm rather than assume:

1. Post the document and keep your Correlation-Id.
2. Read the delivery back — GET /business-units/{businessUnitId}/deliveries filtered to the delivery note number, or list the store's deliveries. See API.
3. Treat "not present after a short delay" as a failure to be retried or escalated, not as success.

Building that check in from the start is much cheaper than discovering months later that a class of documents has been silently dropped.

Errors

Response	Meaning	What to fix
400 invalid file	The upload was missing, not XML, or not a despatch advice message	Check the file part is attached and the root element and namespace prefix are right
400 invalid GS1	The document parsed but does not satisfy the profile, for example a line item outside any logistic unit	Compare against the field reference
400 duplicate line number	Two lines share a line number	Number lines uniquely across the document
400 business unit not found	The receiver's GLN is not registered	Register the GLN, or send the business unit id
400 no business unit or business partner with GLN	The shipper's GLN is held by no business unit and no business partner	Register the GLN on the business partner, or send the shipper's businessPartnerId
400 GLN matches more than one business partner	Two or more partners hold the shipper's GLN	Keep the GLN on one partner, or send the shipper's businessPartnerId
502	Business Unit Management or Business Partner could not be asked	Send the document again
403	The token lacks grc.delivery.import, or is for another tenant	Check the permission and the Tenant-Id header
202 then no delivery	A GTIN did not resolve to an item for that store	Send the item id, or set the barcode up in Product, Price and Promotion. See Confirming an import landed

⚠ The invalid-GS1 response does not name the offending field. When bringing a new sender online, validate against the field reference first and change one thing at a time.

After the store approves

Approval publishes the approved quantities. If your system needs to know what was actually accepted — to close a purchase order, to reconcile an invoice, or to update its own stock — subscribe to the published event rather than polling. See External Events.