ECGrid Simplify

Canonical Package Status Format Specification

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

1. Purpose

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

The Package Status (997) document communicates delivery and shipment status information for packages and parcels. It includes status codes, delivery appointments, tracking information, delivery exceptions, and address change notifications. Both XML and JSON representations convey the same logical status data. A JSON Schema (Simplify_Package_Status.schema.json) provides machine-enforceable validation. This document is the human-readable companion.

2. Scope

In scope:

• Package status document structure (header and detail lines).
• Field-level definitions, data types, length limits, and validation rules.
• Canonical XML and JSON representations.
• Status codes, delivery appointments, and delivery exceptions.
• Package tracking, weight, charges, and service level information.
• Multiple party types and address change tracking.

Out of scope:

• Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
• Real-time GPS and location coordinates.
• Driver signature images and proof-of-delivery photographs.
• Carrier-specific exception codes and internal routing logic.

3. Document Structure

A Package Status payload contains a single status report with header information, multiple party references (shipper, consignee, billing parties), and one or more detail records containing package status information and delivery location details.

packageStatusMessage

└── packageStatus (required, exactly one)

     ├── header (required information)

     │     ├── tradingPartnerId

     │     ├── documentId / transactionRefNumber

     │     ├── sender / receiver

     │     ├── transactionPurposeCode / transactionDate

     │     └── vendor information

     ├── parties (shipper, signer, ultimateConsignee, billTo, freightBillTo, shipNoticeTo, thirdParty)

     └── detail[] (1..n package status records)

4. Header Fields

The header section contains transaction-level status information.

5. Party Information Blocks

Multiple party types are used in package status: Shipper, Signer, UltimateConsignee, BillTo, FreightBillTo, ShipNoticeTo, and ThirdParty. All use the same party structure.

6. Detail Records - Package Status Information

The detail array contains one or more package status records with status details and party references (shipTo, deliveryTo, changedTo for address changes).

7. Delivery Location and Address Changes

Detail-level party records track original shipTo address, actual deliveryTo address (if different), and changedTo address if delivery location has been modified.

8. Naming Conventions

• XML: PascalCase for all element names (e.g. PackageStatus, ShipmentStatusCode, DeliveryCode).
• JSON: camelCase for all field names (e.g. packageStatus, shipmentStatusCode, deliveryCode).
• Field semantics and length limits are identical across both. Only casing differs.
• Empty optional values in XML use self-closing tags (e.g. <Zone/>). In JSON, use empty string or null.

9. Status Code Reference

• Common shipment status codes:

• 01 = Pickup
• 02 = In Transit
• 03 = Delivered
• 04 = Exception/Failed Delivery
• 05 = On Hold
• 06 = Returned to Shipper
• 07 = Appointment Scheduled

10. XML Example

<PackageStatusMessage>
<PackageStatus>
<TradingPartnerId>SEV2TEST01</TradingPartnerId>
<DocumentId>PS-2026-05-001</DocumentId>
<SenderQualifier>SE</SenderQualifier>
<Sender>SEV2TEST01</Sender>
<ReceiverQualifier>SE</ReceiverQualifier>
<Receiver>SEV2TEST02</Receiver>
<VendorId>VEND12345</VendorId>
<TransactionPurposeCode>00</TransactionPurposeCode>
<TransactionDate>20260520</TransactionDate>
<TransactionRefNumber>TX-2026-05-001</TransactionRefNumber>
<Shipper>
<PartyIdentification>54321-WH</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Widget Supplier</Name>
<StreetAddress1>456 Oak Ave</StreetAddress1>
<City>Springfield</City>
<StateCode>IL</StateCode>
<PostalCode>62701</PostalCode>
<CountryCode>US</CountryCode>
</Shipper>
<UltimateConsignee>
<PartyIdentification>12345-STORE</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Acme Store #5</Name>
<StreetAddress1>555 Retail Road</StreetAddress1>
<City>New York</City>
<StateCode>NY</StateCode>
<PostalCode>10001</PostalCode>
<CountryCode>US</CountryCode>
</UltimateConsignee>
<Detail>
<AssignedNumber>1</AssignedNumber>
<Status>
<RefId>TRACK-12345</RefId>
<RefIdQualifier>01</RefIdQualifier>
<Detail>
<PackageId>PKG-001</PackageId>
<ShipmentStatusCode>02</ShipmentStatusCode>
<AppointmentStatusCode>01</AppointmentStatusCode>
<AppointmentReasonCode>01</AppointmentReasonCode>
<Date>20260520</Date>
<Time>1430</Time>
<Weight>25.50</Weight>
<WeightQualifier>B</WeightQualifier>
<Zone>ZONE-01</Zone>
<ServiceLevelCode>01</ServiceLevelCode>
<DeliveryCode>01</DeliveryCode>
<Charge>45.99</Charge>
<RateQualifier>01</RateQualifier>
<PaymentMethod>Prepaid</PaymentMethod>
<CountryCode>US</CountryCode>
</Detail>
</Status>
<ShipTo>
<PartyIdentification>12345-STORE</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Acme Store #5</Name>
<StreetAddress1>555 Retail Road</StreetAddress1>
<City>New York</City>
<StateCode>NY</StateCode>
<PostalCode>10001</PostalCode>
<CountryCode>US</CountryCode>
<DockNumber>DOCK-A1</DockNumber>
<Note>Leave at loading dock</Note>
</ShipTo>
<DeliveryTo>
<PartyIdentification>12345-STORE</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Acme Store #5</Name>
<StreetAddress1>555 Retail Road</StreetAddress1>
<City>New York</City>
<StateCode>NY</StateCode>
<PostalCode>10001</PostalCode>
<CountryCode>US</CountryCode>
<Note>Delivered to receiving area</Note>
</DeliveryTo>
</Detail>
</PackageStatus>
 </PackageStatusMessage>

11. JSON Example

{
"packageStatusMessage": {
"packageStatus": {
"tradingPartnerId": "SEV2TEST01",
"documentId": "PS-2026-05-001",
"senderQualifier": "SE",
"sender": "SEV2TEST01",
"receiverQualifier": "SE",
"receiver": "SEV2TEST02",
"vendorId": "VEND12345",
"transactionPurposeCode": "00",
"transactionDate": "20260520",
"transactionRefNumber": "TX-2026-05-001",
"shipper": {
"partyIdentification": "54321-WH",
"partyIdentificationTypeCode": "92",
"name": "Widget Supplier",
"streetAddress1": "456 Oak Ave",
"city": "Springfield",
"stateCode": "IL",
"postalCode": "62701",
"countryCode": "US"
},
"ultimateConsignee": {
"partyIdentification": "12345-STORE",
"partyIdentificationTypeCode": "92",
"name": "Acme Store #5",
"streetAddress1": "555 Retail Road",
"city": "New York",
"stateCode": "NY",
"postalCode": "10001",
"countryCode": "US"
},
"detail": [
{
"assignedNumber": 1,
"status": {
"refId": "TRACK-12345",
"refIdQualifier": "01",
"detail": {
"packageId": "PKG-001",
"shipmentStatusCode": "02",
"appointmentStatusCode": "01",
"appointmentReasonCode": "01",
"date": "20260520",
"time": "1430",
"weight": 25.50,
"weightQualifier": "B",
"zone": "ZONE-01",
"serviceLevelCode": "01",
"deliveryCode": "01",
"charge": 45.99,
"rateQualifier": "01",
"paymentMethod": "Prepaid",
"countryCode": "US"
}
},
"shipTo": {
"partyIdentification": "12345-STORE",
"partyIdentificationTypeCode": "92",
"name": "Acme Store #5",
"streetAddress1": "555 Retail Road",
"city": "New York",
"stateCode": "NY",
"postalCode": "10001",
"countryCode": "US",
"dockNumber": "DOCK-A1",
"note": "Leave at loading dock"
},
"deliveryTo": {
"partyIdentification": "12345-STORE",
"partyIdentificationTypeCode": "92",
"name": "Acme Store #5",
"streetAddress1": "555 Retail Road",
"city": "New York",
"stateCode": "NY",
"postalCode": "10001",
"countryCode": "US",
"note": "Delivered to receiving area"
}
}
]
}
}
 }