Canonical Shipment Status Message Implementation Guide and Specifications

Modified on Tue, May 26 at 9:40 AM

ECGrid Simplify

Canonical Shipment Status Message Format Specification

Version: 1.0 Date: May 26, 2026 Owner: ECGrid Product

1. Purpose

This document defines the canonical Shipment Status Message format used by ECGrid Simplify. It is the single source of truth for shipment status message structure, field definitions, data types, length limits, required fields, and serialization rules across XML and JSON.

The Shipment Status Message (856) communicates real-time or near real-time shipment status updates for in-transit and completed shipments. It provides status codes, timestamps, reason codes, and delivery stop information. This lightweight format focuses on shipment tracking events and status transitions. Both XML and JSON representations convey the same logical status data. A JSON Schema (Simplify_Shipment_Status_Message.schema.json) provides machine-enforceable validation. This document is the human-readable companion.

2. Scope

In scope:

Shipment status message document structure (header and detail events).
Field-level definitions, data types, length limits, and validation rules.
Canonical XML and JSON representations.
Status codes, reason codes, and shipment event timestamps.
Shipment tracking references and carrier information.
Delivery destination and stop sequence tracking.

Out of scope:

Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
Real-time GPS coordinates and geolocation data.
Driver signature images and proof-of-delivery photographs.
Carrier-specific exception codes and proprietary status systems.

3. Document Structure

A Shipment Status Message payload contains a single shipment with header information, a single shipTo party record, and one or more detail records representing status events or delivery stops. The message is designed to be lightweight and frequently sent to provide near real-time tracking updates.

Top-level shape:

shipmentStatusMessage

└── shipmentStatus (required, exactly one)

├── header (required information)

│ ├── tradingPartnerID

│ ├── documentId / shipmentId

│ ├── sender / receiver

│ ├── carrierRefNumber

│ └── scac (carrier code)

├── shipTo (delivery destination)

└── detail[] (1..n status events)

4. Header Fields

The header section contains shipment-level tracking and routing information.

Field	Type	Length	Req	Description	Example
tradingPartnerID	string	1–35	Yes	ECGrid trading partner identifier. Routes the document.	SEV2TEST01
documentId	string	1–35	Yes	Unique identifier for this shipment status message.	SSM-2026-05-001
userId	string	1–35	No	User ID of the person/system generating the status.	SYSTEM001
sender	string	2–17	Yes	Sender ID (typically carrier) in the qualifier namespace.	SEV2TEST01
senderQualifier	string	1–4	Yes	Qualifier for sender ID (e.g. SE, ZZ, 01, 14).	SE
receiver	string	2–17	Yes	Receiver ID (typically shipper/buyer) in qualifier namespace.	SEV2TEST02
receiverQualifier	string	1–4	Yes	Qualifier for receiver ID.	SE
groupSender	string	1–9	No	EDI functional group sender ID.	1
groupReceiver	string	1–9	No	EDI functional group receiver ID.	1
vendorID	string	1–35	No	Vendor/supplier identifier.	VEND12345
shipmentId	string	1–35	Yes	Unique shipment identifier for tracking.	SHIP-2026-05-001
carrierRefNumber	string	1–35	No	Carrier reference or tracking number.	TRACK-12345
scac	string	2–4	No	Standard Carrier Alpha Code identifying carrier.	SAIA

5. Ship To Party Information

The shipTo block identifies the destination for the shipment. It includes address details and optional contact, government, and financial institution information.

Field	Type	Length	Req	Description	Example
shipTo.partyIdentification	string	1–80	Yes	Party identifier (DUNS, GLN, internal code, etc.).	12345-DEST
shipTo.partyIdentificationTypeCode	string	1–5	Yes	Qualifier for identifier (92=internal, 1=DUNS).	92
shipTo.name	string	1–60	Yes	Legal name of the destination party.	Acme Distribution Center
shipTo.name2	string	1–60	No	Secondary name line.	East Coast Facility
shipTo.name3	string	1–60	No	Tertiary name line.
shipTo.streetAddress1	string	1–55	Yes	Street address line 1.	555 Commerce Drive
shipTo.streetAddress2	string	1–55	No	Street address line 2.	Building B
shipTo.streetAddress3	string	1–55	No	Street address line 3.
shipTo.city	string	2–30	Yes	City.	Atlanta
shipTo.cityCode	string	1–10	No	City code if applicable.
shipTo.stateCode	string	2	No	State or province code. 2 chars for US/CA.	GA
shipTo.postalCode	string	3–15	Yes	Postal/ZIP code.	30303
shipTo.countryCode	string	2	Yes	ISO 3166-1 alpha-2 country code. 2 chars exact.	US
shipTo.provinceCode	string	2–3	No	Province code (non-US/CA).
shipTo.vatNumber	string	1–20	No	VAT/Tax ID number for the party.
shipTo.governmentRefNumber	string	1–35	No	Government reference number (passport, license).
shipTo.tradeRefNumber	string	1–35	No	Trade reference number for customs/import.
shipTo.financialInstitutionAccountNumber	string	1–35	No	Financial institution account number.

6. Detail Records - Status Events

The detail array contains one or more status event records, each representing a shipment state change or milestone event at a specific delivery stop.

Field	Type	Length	Req	Description	Example
assignedNumber	integer	1–6	No	Sequential event or detail number.	1
stopSequenceNumber	integer	1–6	No	Sequence of delivery stop within shipment.	1
shipmentStatus.code	string	1–3	Yes	Status code (e.g., 01=Pickup, 02=In Transit, 03=Delivered).	02
shipmentStatus.reason	string	1–255	No	Reason or description of the status code.	Shipment in transit to destination hub
shipmentStatus.date	string	8	Yes	Date of status event. YYYYMMDD.	20260520
shipmentStatus.time	string	4	No	Time of status event. HHMM (24-hour).	1430

7. Status Code Reference

Standard shipment status codes for the code field:

01 = Pickup

Shipment picked up from origin.

02 = In Transit

Shipment in transit between locations.

03 = Delivered

Shipment delivered to destination.

04 = Exception/Failed Delivery

Delivery attempt failed or exception occurred.

05 = On Hold

Shipment held pending resolution or customer request.

06 = Returned to Shipper

Shipment returned to origin.

07 = Appointment Scheduled

Delivery appointment confirmed.

08 = Out for Delivery

Shipment loaded on delivery vehicle.

09 = Customs Cleared

International shipment cleared customs.

10 = Customs Hold

International shipment detained in customs.

8. Naming Conventions

XML: PascalCase for all element names (e.g. ShipmentStatusMessage, ShipmentStatus, StatusCode).
JSON: camelCase for all field names (e.g. shipmentStatusMessage, shipmentStatus, statusCode).
Field semantics and length limits are identical across both. Only casing differs.
Empty optional values in XML use self-closing tags (e.g. <Reason/>). In JSON, use empty string or null.

9. Lightweight Design Principles

The Shipment Status Message is intentionally compact and optimized for frequent, real-time status updates. Key principles:

Minimal header: Only essential tracking references (shipmentId, carrierRefNumber, scac).
Single shipTo: Only one delivery destination per message (stateless updates).
Repeating status events: Multiple detail records allow series of status transitions.
No nested complexity: Flat structure for fast parsing and processing.
Frequent transmission: Designed to be sent multiple times per shipment lifecycle.

10. XML Example

<ShipmentStatusMessage>
<ShipmentStatus>
<TradingPartnerID>SEV2TEST01</TradingPartnerID>
<DocumentId>SSM-2026-05-001</DocumentId>
<SenderQualifier>SE</SenderQualifier>
<Sender>SEV2TEST01</Sender>
<ReceiverQualifier>SE</ReceiverQualifier>
<Receiver>SEV2TEST02</Receiver>
<VendorID>VEND12345</VendorID>
<ShipmentId>SHIP-2026-05-001</ShipmentId>
<CarrierRefNumber>TRACK-12345</CarrierRefNumber>
<SCAC>SAIA</SCAC>
<ShipTo>
<PartyIdentification>12345-DEST</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Acme Distribution Center</Name>
<Name2>East Coast Facility</Name2>
<StreetAddress1>555 Commerce Drive</StreetAddress1>
<StreetAddress2>Building B</StreetAddress2>
<City>Atlanta</City>
<StateCode>GA</StateCode>
<PostalCode>30303</PostalCode>
<CountryCode>US</CountryCode>
</ShipTo>
<Detail>
<AssignedNumber>1</AssignedNumber>
<StopSequenceNumber>1</StopSequenceNumber>
<ShipmentStatus>
<Code>01</Code>
<Reason>Shipment picked up from origin</Reason>
<Date>20260520</Date>
<Time>0800</Time>
</ShipmentStatus>
</Detail>
<Detail>
<AssignedNumber>2</AssignedNumber>
<StopSequenceNumber>1</StopSequenceNumber>
<ShipmentStatus>
<Code>02</Code>
<Reason>Shipment in transit to destination hub</Reason>
<Date>20260520</Date>
<Time>1430</Time>
</ShipmentStatus>
</Detail>
<Detail>
<AssignedNumber>3</AssignedNumber>
<StopSequenceNumber>1</StopSequenceNumber>
<ShipmentStatus>
<Code>08</Code>
<Reason>Out for delivery - arrived at facility</Reason>
<Date>20260521</Date>
<Time>0900</Time>
</ShipmentStatus>
</Detail>
<Detail>
<AssignedNumber>4</AssignedNumber>
<StopSequenceNumber>1</StopSequenceNumber>
<ShipmentStatus>
<Code>03</Code>
<Reason>Delivered to destination</Reason>
<Date>20260521</Date>
<Time>1100</Time>
</ShipmentStatus>
</Detail>
</ShipmentStatus>
</ShipmentStatusMessage>

11. JSON Example

{
"shipmentStatusMessage": {
"shipmentStatus": {
"tradingPartnerID": "SEV2TEST01",
"documentId": "SSM-2026-05-001",
"senderQualifier": "SE",
"sender": "SEV2TEST01",
"receiverQualifier": "SE",
"receiver": "SEV2TEST02",
"vendorID": "VEND12345",
"shipmentId": "SHIP-2026-05-001",
"carrierRefNumber": "TRACK-12345",
"scac": "SAIA",
"shipTo": {
"partyIdentification": "12345-DEST",
"partyIdentificationTypeCode": "92",
"name": "Acme Distribution Center",
"name2": "East Coast Facility",
"streetAddress1": "555 Commerce Drive",
"streetAddress2": "Building B",
"city": "Atlanta",
"stateCode": "GA",
"postalCode": "30303",
"countryCode": "US"
},
"detail": [
{
"assignedNumber": 1,
"stopSequenceNumber": 1,
"shipmentStatus": {
"code": "01",
"reason": "Shipment picked up from origin",
"date": "20260520",
"time": "0800"
}
},
{
"assignedNumber": 2,
"stopSequenceNumber": 1,
"shipmentStatus": {
"code": "02",
"reason": "Shipment in transit to destination hub",
"date": "20260520",
"time": "1430"
}
},
{
"assignedNumber": 3,
"stopSequenceNumber": 1,
"shipmentStatus": {
"code": "08",
"reason": "Out for delivery - arrived at facility",
"date": "20260521",
"time": "0900"
}
},
{
"assignedNumber": 4,
"stopSequenceNumber": 1,
"shipmentStatus": {
"code": "03",
"reason": "Delivered to destination",
"date": "20260521",
"time": "1100"
}
}
]
}
}
}