Goods Received

The Goods Received process represents the final step in the delivery lifecycle, where the receiver store confirms and accepts the items that were shipped. This process ensures that all expected goods have arrived in proper condition and in the correct quantities.

Once the goods are physically received:

The store staff counts and verifies the items.

Each delivery can be approved entirely or partially—by container, line item, or the whole delivery.

Upon confirmation, the delivery is submitted to the system, marking it as complete.

This submission updates the system’s status for traceability, fulfillment tracking, and further integration (e.g., inventory updates or financial reconciliation).

The process supports:

📦 Full delivery approval

🧾 Line-level confirmation

🧊 Container-specific acceptance

It also allows for corrections after submission, with clear tracking of any deltas in subsequent exports.

📘 What is a Delivery Note?

A delivery note is a document used to track the shipment of item lines—optionally organized in containers—shipped from a shipper warehouse or store to a receiver store.

🔄 Delivery Note Creation Methods

There are two methods to create delivery notes in the system:

1. Manual Delivery Note Creation
2. GS1 Import

🛠️ How to Manually Create a Delivery Note

This process has two main steps: creating the delivery note itself and adding lines (items) to it.

📝 Step 1: Create a Delivery Note

Use the following API endpoint: POST /business-units/{businessUnitId}/deliveries

Sample Request Body:

{
"deliveryNoteId": "string",
"shipperId": "string",
"shipperName": "string",
"deliveryDatetime": "2025-05-30T15:32:00.530Z",
"transportationAmount": 0,
"customsAmount": 0,
"currencyCode": "string",
"comment": "string"
} 

📝 Step 2: Add Item Lines to the Delivery

📄 What are Delivery Lines?

Delivery lines represent the individual items being shipped in a delivery.

When creating a manual delivery note, delivery lines are used to:

Add specific items (itemId, gtin, orderId) to the delivery

Define the quantity of each item being shipped

Provide unit price, batch, and expiration details

Optionally assign the item to one or more containers using containerIds (if used)

If containerIds are provided, it means the item is physically packed inside those containers. If not, the item is considered unpacked and directly part of the delivery.

This step is crucial for defining what is being shipped and how it's organized.

Use this endpoint to add the actual product lines to the delivery:

POST /business-units/{businessUnitId}/deliveries/{deliveryId}/lines

Sample Request Body:

{
  "lines": [
    {
      "gtin": "string",
      "itemId": "string",
      "orderId": "string",
      "expectedQuantity": 0,
      "unitPrice": 0,
      "containerIds": ["string"],
      "bestBeforeDate": "2025-05-30",
      "expirationDate": "2025-05-30",
      "currencyCode": "string",
      "batchNumber": "string",
      "serialNumbers": ["string"]
    }
  ]
}

🔄 Creating Delivery Notes via GS1 Import

Delivery notes can be automatically imported into the system using a modified GS1 EANCOM standard, tailored specifically for HiiRetail. This approach is suitable for integrations from warehouses, suppliers, or external systems.

📥 How It Works:

An external system pushes a GS1-compliant payload to the following endpoint: POST /imports/deliveries/gs1

The system parses and validates the delivery note structure and content.

The delivery note, along with containers and item lines, is automatically created based on the payload.

✅ Rules and Requirements:

The format is based on GS1 EANCOM but simplified and includes mandatory fields required by HiiRetail.

Delivery notes missing required fields will be rejected.

Additional GS1-compliant fields not required by the service will be ignored.

What is GS1 format

The GS1 XML format you provided is based on the GS1 eCom Despatch Advice Message, which is part of the GS1 EDI (Electronic Data Interchange) standards used globally in supply chains for automated, structured, and interoperable business messaging between trading partners.

Learn more about the GS1 format:

• GS1 Format

✅ Approve / Submit Delivery (Goods Received)

Once the goods have physically arrived at the receiver store, the receiving team begins the verification process by counting and checking the delivered items. Upon successful verification, the store can mark items or containers as received and complete.

The system then updates the delivery status accordingly, progressing the delivery lifecycle to "Completed" once all expected items are accounted for.

The receiver has three methods to complete or approve a delivery:

• 📦 1. Submit Entire Delivery

  Endpoint:

  POST /business-units/{businessUnitId}/deliveries/{deliveryId}/submit

  • Use Case:

    • When the entire delivery (all containers and items) has been received and verified.

    • Suitable for cases where all goods were delivered as expected in a single operation.

  • Outcome:

    • The system marks the delivery as fully completed.

    • All line items and containers are assumed to be counted and approved.

• 🧾 2. Submit by Line Item

  Endpoint:

  POST /business-units/{businessUnitId}/deliveries/{deliveryId}/lines/{lineId}/submit

  • Use Case:

    • When the receiver has verified only a specific item line within the delivery.

    • Useful for partial deliveries or progressive receiving workflows.

  • Outcome:

    • Only the specified line item is marked as completed.

    • The overall delivery remains open until all lines are submitted.

• 📦 3. Submit by Container (Logistic Unit)

  Endpoint:

  POST /business-units/{businessUnitId}/deliveries/{deliveryId}/containers/{containerId}/submit

  • Use Case:

    • When a specific logistic unit (container) has been unpacked and verified.

    • Ideal for bulk receiving by container or when containers arrive at different times.

  • Outcome:

    • Only the specified container and its contents are marked as completed.

    • Other containers or line items remain in pending status until submitted.

🔄 Post-Submission Changes & Re-Submission

Even after a delivery (or part of it) has been submitted and marked as completed, certain changes may still be allowed — such as quantity corrections, late item additions, or metadata updates.

However, if any modification is made after submission:

✅ The updated section must be re-submitted using the appropriate endpoint (by delivery, line item, or container).

📝 The system treats this as a correction or update, ensuring the delivery record reflects the latest verified data.

📤 Re-Export & Delta Tracking

When delivery notes are re-exported (e.g., for downstream systems, reports, or integrations):

The export includes a delta section.

This delta highlights all changes since the last export, providing full traceability of adjustments made post-submission.

This mechanism ensures transparency and consistency in delivery reconciliation and audit processes.

GS1 import explanation

Brief explanation of the GS1 import process

How and when will I get the data?

Once submitted, goods received publishes events/data to PubSub. Other Hii Retail services, or external system using External Events, can subscribe to these messages.

Subscriptions

Tech	Subscription
Pub/Sub	grc.public.event.goods-received.v1
External Events	grc.public.event.goods-received.v1

Format

The JSON format.