Canonical ASN (SOIP) Implementation Guide and Specifications

Modified on Tue, May 26 at 9:25 AM

ECGrid Simplify

Canonical Advanced Shipment Notice (ASN) Format Specification

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

1. Purpose

This document defines the canonical Advanced Shipment Notice (ASN) format used by ECGrid Simplify. It is the single source of truth for ASN structure, field definitions, data types, length limits, required fields, and serialization rules across XML and JSON.

The ASN (also known as SOIP - Ship Order Information Program) enables suppliers to notify buyers of imminent shipments with detailed logistics, tracking, and line-item information. Both XML and JSON representations convey the same logical ASN. A JSON Schema (Simplify_XML_ASN.schema.json) provides machine-enforceable validation. This document is the human-readable companion.

2. Scope

In scope:

ASN document structure (header, shipment, and hierarchical line items).
Field-level definitions, data types, length limits, and validation rules.
Canonical XML and JSON representations.
Party identification for multiple role types (shipTo, shipFrom, buyer, seller, carrier, etc.).
Shipment logistics, transportation, equipment, and measurement details.
Hierarchical line-item structure supporting multiple packaging levels.

Out of scope:

Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
Functional acknowledgments and 997 application responses.
Warehouse management and inventory allocation logic.

3. Document Structure

An ASN payload contains one or more shipments. Each shipment has a single header block containing trading partner identifiers, shipment metadata, and status information. The header is followed by one shipment section containing multiple party blocks, logistics information, and one or more hierarchical line items representing the contents being shipped.

Top-level shape:

shipNotices[]

└── shipNotice (required, exactly one)

├── header (required, exactly one)

│ ├── tradingPartnerId

│ ├── documentId

│ ├── shipmentId / shipmentDate

│ ├── estimatedDeliveryDate

│ ├── documentStatusCode

│ └── totalNumberOfLines

└── shipment (required, exactly one)

├── shipTo, shipFrom, buyer, seller, carrier (party blocks)

├── shipmentTransportationInformation

├── shipmentMeasurements

├── equipmentDetails

└── hierarchalOrderEntity[] (1..n line items)

4. Header Fields

The header block contains ASN-level metadata 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 ASN document.	ASN-987654
userId	string	1–35	No	User ID of the person creating the ASN.	USER456
documentStatusCode	string	1–3	Yes	Status code (e.g., 00=Original, 01=Replace, 04=Void).	00
shipmentId	string	1–35	Yes	Unique shipment identifier for tracking purposes.	SHIP-2026-05-001
shipmentDate	string	8	Yes	Date shipment is scheduled or actual ship date. YYYYMMDD.	20260526
shipmentTime	string	0 or 4	No	Time shipment occurs. HHMM (24-hour) or empty.	1430
estimatedDeliveryDate	string	8	No	Expected delivery date. YYYYMMDD.	20260601
estimatedDeliveryTime	string	0 or 4	No	Expected delivery time. HHMM (24-hour) or empty.	0900
documentDate	string	8	Yes	Date ASN document was created. YYYYMMDD.	20260526
documentTime	string	0 or 4	No	Time ASN document was created. HHMM or empty.	1300
hierarchalCode	string	1–5	No	Hierarchal code for EDI functional grouping.	S
totalNumberOfLines	integer	1–5	Yes	Total count of line items in shipment.	15
documentTimeZone	string	3–5	No	Time zone code (e.g., EST, CST, PST).	EST
transactionType	string	1–3	No	Transaction type qualifier (e.g., 001=Shipment, 002=Warehouse Transfer).	001
statusReason	string	1–3	No	Reason for document status if not original (e.g., 01=Shipment Delayed).
partnerEntity.partnerQualifier	string	1–4	No	EDI partner qualifier (e.g., 01=DUNS, 02=SCAC, ZZ=Mutually Defined).	01
partnerEntity.partnerValue	string	1–35	No	EDI partner identifier value in the specified qualifier namespace.	1234567890

5. Shipment-Level Fields

The shipment section contains logistics and transportation information at the shipment level.

Field	Type	Length	Req	Description	Example
vendorId	string	1–35	No	Vendor/supplier identifier.	VEND12345
trailerNumber	string	1–35	No	Trailer or container number for shipment.	TR-54321
billOfLadingNumber	string	1–35	No	Bill of lading number.	BOL-2026-0001
masterBillOfLading	string	1–35	No	Master BOL number (for consolidated shipments).	MBIL-2026-001
trackingNumber	string	1–35	No	Carrier tracking number.	TRK-98765432
bookingNumber	string	1–35	No	Booking reference number.	BOOK-2026-001
sealNumber	string	1–35	No	Seal number on equipment.	SEAL-123456
revisionNumber	string	1–6	No	Revision sequence number for this ASN.	1
purchaseOrderNumber	string	1–22	No	Associated purchase order number.	123456
invoiceNumber	string	1–22	No	Associated invoice number.	INV-2026-001
countryOfOrigin	string	2	No	ISO 3166-1 alpha-2 country code of origin.	US
productGroup	string	1–35	No	Product group or commodity code.	PROD-GRP-A

6. Party Address Block

The same party structure is used for shipTo, shipFrom, buyer, seller, billTo, ultimateConsignee, supplier, and carrier. Each party block identifies participants in the shipment transaction.

Field	Type	Length	Req	Description	Example
partyIdentification	string	1–80	Yes	Party identifier value (DUNS, GLN, internal code, etc.).	12345
partyIdentificationTypeCode	string	1–5	Yes	Qualifier for the identifier (e.g. 92=internal, 1=DUNS, UL=GLN).	92
name1	string	1–60	Yes	Primary name line of the party.	Acme Corp
name2	string	1–60	No	Secondary name line.	Division A
streetAddress1	string	1–55	Yes	Street address line 1.	123 Main St
streetAddress2	string	1–55	No	Street address line 2.	Suite 100
streetAddress3	string	1–55	No	Street address line 3.
city	string	2–30	Yes	City.	Albany
stateCode	string	2	No	State or province code. 2 chars for US/CA.	NY
postalCode	string	3–15	Yes	Postal/ZIP code.	12207
countryCode	string	2	Yes	ISO 3166-1 alpha-2 country code. 2 chars exact.	US
vatNumber	string	1–20	No	VAT/Tax ID number for the party.
gln	string	13	No	Global Location Number (GS1 standard).	1234567890123
dockCode	string	1–10	No	Dock number or code at receiving location.	DOCK-A1

7. Shipment Transportation Information

Transportation and routing details for the shipment.

Field	Type	Length	Req	Description	Example
scac	string	2–4	No	Standard Carrier Alpha Code (SCAC).	SAIA
transportationMethod	string	1–3	No	Transportation method (e.g., OTR=Over-the-Road, AIR=Air).	OTR
transportationStage	string	1–3	No	Transportation stage (e.g., PP=Pickup, DL=Delivery, NW=Non-working).	PP
routing	string	1–35	No	Detailed routing string or sequence.	ORIGIN > HUB > DEST
shipmentStatus	string	1–3	No	Current shipment status code (e.g., 00=New, 01=In Transit, 02=Delivered).	01
serviceLevelCode	string	1–3	No	Service level (e.g., GND=Ground, EXP=Express, OVN=Overnight).	GND
transitTime	integer	1–4	No	Estimated transit time in hours.	72

8. Shipment Measurements

Physical measurements and weight information for the shipment.

Field	Type	Length	Req	Description	Example
packagingCode	string	1–5	No	Packaging code (e.g., BOX=Carton, PLT=Pallet).	PLT
ladingQuantity	integer	1–8	No	Number of shipping units (e.g., cartons, pallets).	15
shipmentGrossWeight	number	1–15	No	Gross weight of entire shipment.	5500.50
shipmentGrossWeightUOM	string	2–3	No	Unit of measure (e.g., LB=Pounds, KG=Kilograms).	LB
shipmentNetWeight	number	1–15	No	Net weight of entire shipment (excluding packaging).	5000.25
shipmentNetWeightUOM	string	2–3	No	Unit of measure for net weight.	LB
shipmentVolume	number	1–15	No	Volume of entire shipment.	125.75
shipmentVolumeUOM	string	2–3	No	Unit of measure (e.g., CF=Cubic Feet, CM=Cubic Meters).	CF

9. Equipment Details

Information about transport equipment (containers, trailers, etc.) used in the shipment.

Field	Type	Length	Req	Description	Example
equipmentInitial	string	1–4	No	Equipment initial/prefix (e.g., trailer company code).	SCAC
equipmentID	string	1–20	No	Equipment identifier number (e.g., trailer number).	54321
equipmentDescriptionCode	string	1–3	No	Equipment type code (e.g., TL=Trailer, CT=Container).	TL
equipmentType	string	1–35	No	Detailed equipment type description.	53-foot Dry Van
sealInfo.sealNumber	string	1–35	No	Seal number applied to equipment.	SEAL-123456
sealInfo.sealingParty	string	1–35	No	Organization that applied the seal.	Carrier XYZ

10. Hierarchical Line Item

The hierarchalOrderEntity array contains one or more line items representing the contents being shipped. Each item supports hierarchical packaging levels (order, pallet, case, unit) and detailed product information.

Field	Type	Length	Req	Description	Example
lineItemNumber	integer	1–6	Yes	Sequential line number within the shipment.	1
poLineItemNumber	integer	1–6	No	Reference line number from the purchase order.	5
supplierAssignedPartNumber	string	1–48	No	Supplier's part number for the item.	VN123456789
buyerAssignedPartNumber	string	1–48	No	Buyer's part number for the item.	BY123456789
gtin14	string	14	No	Global Trade Item Number (GTIN-14).	01234567890123
modelNumber	string	1–35	No	Product model number.	MODEL-XYZ-001
lotNumber	string	1–35	No	Lot or batch number of product.	LOT-2026-050
shipQuantity	number	1–15	Yes	Quantity being shipped for this line. Decimals allowed.	100.5
shipQuantityUOM	string	2–3	Yes	Unit of measure (e.g. EA=Each, CS=Case, LB=Pound).	EA
orderedQuantity	number	1–15	No	Original ordered quantity.	100.5
netUnitPrice	number	1–17	No	Net unit price (excluding tax).	45.75
grossUnitPrice	number	1–17	No	Gross unit price (including tax).	49.99
countryOfOrigin	string	2	No	ISO 3166-1 alpha-2 country code of origin for item.	CN
lineItemDescription	string	1–255	No	Text description of the line item.	Blue widget, size large

11. Naming Conventions

JSON: camelCase for all field names (e.g. shipmentId, hierarchalOrderEntity).
XML: lowercase for all element names (e.g. shipmentId, hierarchalOrderEntity).
Field semantics and length limits are identical across both. Only casing differs.
Empty optional values in XML use self-closing tags (e.g. <shipmentTime/>). In JSON, use empty string for string fields.

12. XML Example

<ShipNotices>
<ShipNotice>
<Header>
<tradingPartnerId>SEV2TEST01</tradingPartnerId>
<documentId>ASN-987654</documentId>
<documentStatusCode>00</documentStatusCode>
<shipmentId>SHIP-2026-05-001</shipmentId>
<shipmentDate>20260526</shipmentDate>
<estimatedDeliveryDate>20260601</estimatedDeliveryDate>
<documentDate>20260526</documentDate>
<totalNumberOfLines>2</totalNumberOfLines>
</Header>
<Shipment>
<vendorId>VEND12345</vendorId>
<billOfLadingNumber>BOL-2026-0001</billOfLadingNumber>
<trackingNumber>TRK-98765432</trackingNumber>
<purchaseOrderNumber>123456</purchaseOrderNumber>
<ShipFrom>
<partyIdentification>54321</partyIdentification>
<partyIdentificationTypeCode>92</partyIdentificationTypeCode>
<name1>Widget Supplier Inc</name1>
<streetAddress1>456 Oak Ave</streetAddress1>
<city>Springfield</city>
<stateCode>IL</stateCode>
<postalCode>62701</postalCode>
<countryCode>US</countryCode>
</ShipFrom>
<ShipTo>
<partyIdentification>12345</partyIdentification>
<partyIdentificationTypeCode>92</partyIdentificationTypeCode>
<name1>Acme Corp</name1>
<streetAddress1>123 Main St</streetAddress1>
<city>Albany</city>
<stateCode>NY</stateCode>
<postalCode>12207</postalCode>
<countryCode>US</countryCode>
</ShipTo>
<ShipmentTransportationInformation>
<scac>SAIA</scac>
<transportationMethod>OTR</transportationMethod>
<shipmentStatus>01</shipmentStatus>
<serviceLevelCode>GND</serviceLevelCode>
<transitTime>72</transitTime>
</ShipmentTransportationInformation>
<ShipmentMeasurements>
<packagingCode>PLT</packagingCode>
<ladingQuantity>15</ladingQuantity>
<shipmentGrossWeight>5500.50</shipmentGrossWeight>
<shipmentGrossWeightUOM>LB</shipmentGrossWeightUOM>
<shipmentVolume>125.75</shipmentVolume>
<shipmentVolumeUOM>CF</shipmentVolumeUOM>
</ShipmentMeasurements>
<EquipmentDetails>
<equipmentDescriptionCode>TL</equipmentDescriptionCode>
<equipmentType>53-foot Dry Van</equipmentType>
<sealInfo>
<sealNumber>SEAL-123456</sealNumber>
</sealInfo>
</EquipmentDetails>
<HierarchalOrderEntity>
<lineItemNumber>1</lineItemNumber>
<poLineItemNumber>5</poLineItemNumber>
<supplierAssignedPartNumber>VN123456789</supplierAssignedPartNumber>
<buyerAssignedPartNumber>BY123456789</buyerAssignedPartNumber>
<gtin14>01234567890123</gtin14>
<shipQuantity>100</shipQuantity>
<shipQuantityUOM>EA</shipQuantityUOM>
<netUnitPrice>45.75</netUnitPrice>
<countryOfOrigin>US</countryOfOrigin>
<description>
<lineItemDescription>Blue widget, size large</lineItemDescription>
</description>
</HierarchalOrderEntity>
<HierarchalOrderEntity>
<lineItemNumber>2</lineItemNumber>
<poLineItemNumber>6</poLineItemNumber>
<supplierAssignedPartNumber>VN987654321</supplierAssignedPartNumber>
<buyerAssignedPartNumber>BY987654321</buyerAssignedPartNumber>
<shipQuantity>50</shipQuantity>
<shipQuantityUOM>CS</shipQuantityUOM>
<netUnitPrice>120.00</netUnitPrice>
<description>
<lineItemDescription>Red widget, size small, case of 10</lineItemDescription>
</description>
</HierarchalOrderEntity>
</Shipment>
</ShipNotice>
</ShipNotices>

13. JSON Example

{
"shipNotices": [
{
"header": {
"tradingPartnerId": "SEV2TEST01",
"documentId": "ASN-987654",
"documentStatusCode": "00",
"shipmentId": "SHIP-2026-05-001",
"shipmentDate": "20260526",
"estimatedDeliveryDate": "20260601",
"documentDate": "20260526",
"totalNumberOfLines": 2
},
"shipment": {
"vendorId": "VEND12345",
"billOfLadingNumber": "BOL-2026-0001",
"trackingNumber": "TRK-98765432",
"purchaseOrderNumber": "123456",
"shipFrom": {
"partyIdentification": "54321",
"partyIdentificationTypeCode": "92",
"name1": "Widget Supplier Inc",
"streetAddress1": "456 Oak Ave",
"city": "Springfield",
"stateCode": "IL",
"postalCode": "62701",
"countryCode": "US"
},
"shipTo": {
"partyIdentification": "12345",
"partyIdentificationTypeCode": "92",
"name1": "Acme Corp",
"streetAddress1": "123 Main St",
"city": "Albany",
"stateCode": "NY",
"postalCode": "12207",
"countryCode": "US"
},
"shipmentTransportationInformation": {
"scac": "SAIA",
"transportationMethod": "OTR",
"shipmentStatus": "01",
"serviceLevelCode": "GND",
"transitTime": 72
},
"shipmentMeasurements": {
"packagingCode": "PLT",
"ladingQuantity": 15,
"shipmentGrossWeight": 5500.50,
"shipmentGrossWeightUOM": "LB",
"shipmentVolume": 125.75,
"shipmentVolumeUOM": "CF"
},
"equipmentDetails": {
"equipmentDescriptionCode": "TL",
"equipmentType": "53-foot Dry Van",
"sealInfo": {
"sealNumber": "SEAL-123456"
}
},
"hierarchalOrderEntity": [
{
"lineItemNumber": 1,
"poLineItemNumber": 5,
"supplierAssignedPartNumber": "VN123456789",
"buyerAssignedPartNumber": "BY123456789",
"gtin14": "01234567890123",
"shipQuantity": 100,
"shipQuantityUOM": "EA",
"netUnitPrice": 45.75,
"countryOfOrigin": "US",
"description": {
"lineItemDescription": "Blue widget, size large"
}
},
{
"lineItemNumber": 2,
"poLineItemNumber": 6,
"supplierAssignedPartNumber": "VN987654321",
"buyerAssignedPartNumber": "BY987654321",
"shipQuantity": 50,
"shipQuantityUOM": "CS",
"netUnitPrice": 120.00,
"description": {
"lineItemDescription": "Red widget, size small, case of 10"
}
}
]
}
}
]
}