Canonical Routing Instructions 754 Format Specification

Modified on Thu, Aug 27 at 8:38 AM

ECGrid Simplify

Version: 1.0 Date: June 2026 Owner: ECGrid Product

1. Purpose

This document defines the canonical Routing Instructions format used by ECGrid Simplify. It is the single source of truth for document structure, field definitions, data types, required fields, and serialisation rules across XML and JSON.

Both XML and JSON representations convey the same logical Routing Instructions message. The 754 transaction set is a carrier's response to a Request for Routing Instructions (753), confirming pickup date, carrier assignment, and order details.

Direction Note: The Canonical Routing Instructions flows inbound to ECGrid from the carrier or logistics provider. ECGrid receives an X12 754 EDI transaction and translates it into the canonical format for delivery to the shipper's system.

2. Scope

In scope:

Routing Instructions document structure (envelope, header, party blocks, and line items).
Field-level definitions, data types, required fields, and EDI source mapping.
Canonical XML and JSON representations.
Party identification (ShipFrom, ShipTo at header and line level) and date conventions.

Out of scope:

Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
Functional acknowledgments and application responses.
X12 754 EDI mapping rules. See Map_ANSI X12 754 004010 To Simplify XML Routing Instructions 754 - Global.csv.
Request for Routing Instructions (753). Covered in ECGrid_Simplify_753_Spec.docx.

3. Document Structure

A canonical Routing Instructions payload contains a RoutingInstructionsMessage root element with exactly one RoutingInstructions child. The child holds all header fields from the BGN and PER segments, two header-level party blocks (ShipFrom, ShipTo), and one or more LineItem entries from the LX loop. Each LineItem may also contain line-level party blocks (OrderShipFrom, OrderShipTo).

XML vs JSON Naming: Both XML and JSON use PascalCase field names throughout. The JSON root key is "RoutingInstructionsMessage" — matching the XML root element exactly.

Top-level shape:

RoutingInstructionsMessage

└── RoutingInstructions (required, exactly one)

├── TradingPartnerId / Sender / Receiver … (envelope fields, ISA/GS)

├── TransactionSetPurposeCode / ReferenceNumber … (header, BGN)

├── ContactName / ContactPhone … (contact, PER)

├── ShipFrom (party block, N1/SF)

├── ShipTo (party block, N1/ST)

└── LineItem (1..n, one per LX loop)

├── LineItemNumber / StandardCarrierAlphaCode / PickupDate …

├── OrderShipFrom (line party, LoopN1/SF)

└── OrderShipTo (line party, LoopN1/ST)

3.1 Comparison with the Canonical Request for Routing Instructions (753)

Aspect	Canonical Request for Routing Instr. (753)	Canonical Routing Instructions (754)
Root element	<RequestForRoutingInstructionsMessage> / <RequestForRoutingInstructions>	<RoutingInstructionsMessage> / <RoutingInstructions>
Transaction	753	754
GS-01 code	RF	GF
Direction	Outbound — shipper requests routing from carrier	Inbound — carrier responds with confirmed routing
JSON root key	"RequestForRoutingInstructionsMessage"	"RoutingInstructionsMessage"
Header segment	BGN (purpose, reference, date, time, timezone, action)	BGN (same fields; RoutingDate instead of RequestDate)
Carrier field	None (carrier not yet assigned)	BLR: StandardCarrierAlphaCode + PickupDate (confirmed)
Service info segment	USI: AgencyQualifier, ServiceCode, ServiceAmount	Not present in standard 754 mapping
Quantity segment	Not present in standard 753 mapping	QTY in LoopQTY: QuantityQualifier (38=Confirmed) + Quantity
Order detail segment	OID inside LoopOID (nested in LoopLX)	OID directly in LoopLX (not nested)
Party types	ShipFrom, ShipTo, BillTo (header) + OrderShipFrom, OrderShipTo (line)	ShipFrom, ShipTo (header) + OrderShipFrom, OrderShipTo (line)

4. Envelope Fields

Sourced from ISA (interchange) and GS (functional group) segments.

ISA fixed-width: ISA-06 (Sender) and ISA-08 (Receiver) are 15-character fixed-width fields padded with trailing spaces. ECGrid always trims before populating TradingPartnerId, Sender, and Receiver.

XML Element	JSON Property	Req	Description
TradingPartnerId	TradingPartnerId	Yes	ISA-06 — ECGrid trading partner identifier. 15-char fixed-width; always trimmed.
Sender	Sender	Yes	ISA-06 — Interchange sender identifier value. Trimmed.
SenderQualifier	SenderQualifier	Yes	ISA-05 — Qualifies the sender identifier type (e.g. 01=DUNS, ZZ=Mutually Defined).
Receiver	Receiver	Yes	ISA-08 — Interchange receiver identifier value. Trimmed.
ReceiverQualifier	ReceiverQualifier	Yes	ISA-07 — Qualifies the receiver identifier type.
InterchangeDate	InterchangeDate	Yes	ISA-09 — Interchange date. YYMMDD format.
InterchangeControlNumber	InterchangeControlNumber	Yes	ISA-13 — Interchange control number.
TestProductionIndicator	TestProductionIndicator	Yes	ISA-15 — T=Test, P=Production.
GroupFunctionCode	GroupFunctionCode	Yes	GS-01 — Functional identifier code (GF=Routing Instructions).

5. Header Fields

Sourced from BGN (routing instruction header) and PER (contact information) segments.

Contact phone/email extraction: PER-03 is the qualifier: TE=Telephone, EM=Email. If PER-03=TE then ContactPhone=PER-04; if PER-05=TE then ContactPhone=PER-06. Same pattern applies for ContactEmail with qualifier EM.

XML Element	JSON Property	Req	Description
TransactionSetPurposeCode	TransactionSetPurposeCode	Yes	BGN-01 — Transaction set purpose code. 00=Original, 05=Replace, 01=Cancellation.
ReferenceNumber	ReferenceNumber	Yes	BGN-02 — Reference number assigned by the sender (e.g. routing instruction ID).
RoutingDate	RoutingDate	Yes	BGN-03 — Date the routing instructions were issued. YYYYMMDD format.
RoutingTime	RoutingTime	No	BGN-04 — Time the routing instructions were issued. HHMM format.
TimeZoneCode	TimeZoneCode	No	BGN-05 — Time zone designator code (e.g. ET=Eastern, CT=Central).
ActionCode	ActionCode	No	BGN-06 — Action code qualifier.
ContactFunctionCode	ContactFunctionCode	No	PER-01 — Contact function code (e.g. CN=General Contact).
ContactName	ContactName	No	PER-02 — Contact person or department name.
ContactPhone	ContactPhone	No	PER-04 (PER-03=TE) — Contact phone number. Extracted when PER-03 qualifier is TE.
ContactEmail	ContactEmail	No	PER-04 (PER-03=EM) — Contact email address. Extracted when PER-03 qualifier is EM.

6. Party Address Blocks (N1 Loop)

Header-level party blocks are extracted from the N1 loop appearing before the LX loop. N1-01 qualifier routes data: SF=ShipFrom (pickup origin), ST=ShipTo (delivery destination). Absent loops are silently skipped; all fields output as empty string.

N1 Loop Qualifier Routing: SF=ShipFrom (origin/pickup), ST=ShipTo (destination/delivery). Absent loops are silently skipped.

6.1 ShipFrom (N1-01 = SF)

XML Element	JSON Property	Req	Description
PartyIdentification	PartyIdentification	No	N1-04 — Party identifier value (e.g. account number, location code).
PartyIdentificationType	PartyIdentificationType	No	N1-03 — Code qualifying the identifier type (e.g. 91=Assigned by Seller).
Name	Name	Yes	N1-02 — Party legal or trading name.
AdditionalName	AdditionalName	No	N2-01 — Additional name line.
StreetAddress1	StreetAddress1	No	N3-01 — Primary street address line.
StreetAddress2	StreetAddress2	No	N3-02 — Secondary address line (suite, unit, etc.).
City	City	No	N4-01 — City name.
StateCode	StateCode	No	N4-02 — Two-letter state or province code.
PostalCode	PostalCode	No	N4-03 — Postal / ZIP code.
CountryCode	CountryCode	No	N4-04 — ISO 3166-1 alpha-2 country code (e.g. US).

6.2 ShipTo (N1-01 = ST)

XML Element	JSON Property	Req	Description
PartyIdentification	PartyIdentification	No	N1-04 — Party identifier value (e.g. account number, location code).
PartyIdentificationType	PartyIdentificationType	No	N1-03 — Code qualifying the identifier type (e.g. 91=Assigned by Seller).
Name	Name	Yes	N1-02 — Party legal or trading name.
AdditionalName	AdditionalName	No	N2-01 — Additional name line.
StreetAddress1	StreetAddress1	No	N3-01 — Primary street address line.
StreetAddress2	StreetAddress2	No	N3-02 — Secondary address line (suite, unit, etc.).
City	City	No	N4-01 — City name.
StateCode	StateCode	No	N4-02 — Two-letter state or province code.
PostalCode	PostalCode	No	N4-03 — Postal / ZIP code.
CountryCode	CountryCode	No	N4-04 — ISO 3166-1 alpha-2 country code (e.g. US).

7. Line Item Fields (LoopLX)

The LineItem element repeats for each LX loop. Within each loop: LX (line number), L11 (reference), BLR (carrier + pickup date), OID (order details), G62 (date), and optionally SMD, MSI, LoopQTY (containing QTY + AT9), and LoopN1 (line parties).

LoopQTY nesting: QTY and AT9 segments are inside LoopQTY, which is nested inside LoopLX. Use source path LoopQTY/QTY/QTY01 — not a direct child of LoopLX.

OID position: In the 754 structure OID is a direct child of LoopLX (not nested in LoopOID). This differs from the 753 structure where OID is inside LoopOID.

SMD / MSI / AT9: ShipmentMethodOfPayment (SMD), MessageCode/Amount (MSI), and equipment/weight fields (AT9) are optional. They output as empty string when the segments are absent from the EDI.

XML Element	JSON Property	Req	Description
LineItemNumber	LineItemNumber	Yes	LX-01 — Line item sequence number.
ReferenceIdentification	ReferenceIdentification	No	L11-01 — Reference identification value (e.g. PO number, BOL number).
ReferenceQualifier	ReferenceQualifier	No	L11-02 — Qualifier for the reference identification (e.g. PO=Purchase Order).
FreeFormDescription	FreeFormDescription	No	L11-03 — Free-form description associated with the reference.
StandardCarrierAlphaCode	StandardCarrierAlphaCode	No	BLR-01 — SCAC code of the designated carrier (e.g. FEDX, UPSN).
PickupDate	PickupDate	No	BLR-02 — Scheduled pickup date. YYYYMMDD format.
ShipmentMethodOfPayment	ShipmentMethodOfPayment	No	SMD-01 — Shipment method of payment (e.g. PP=Prepaid, CC=Collect).
TransportationMethodCode	TransportationMethodCode	No	SMD-02 — Transportation method/mode code (e.g. M=Motor, A=Air).
PurchaseOrderNumber	PurchaseOrderNumber	No	OID-02 — Purchase order number.
ReleaseNumber	ReleaseNumber	No	OID-03 — Release number against the purchase order.
UnitOrBasisForMeasurementCode	UnitOrBasisForMeasurementCode	No	OID-04 — Unit of measure for the ordered quantity (e.g. EA, CA, PLT).
OrderQuantity	OrderQuantity	No	OID-05 — Quantity ordered on this line.
DateQualifier	DateQualifier	No	G62-01 — Date qualifier code (e.g. 11=Ship Date, 10=Pickup Date).
Date	Date	No	G62-02 — Date value associated with DateQualifier. YYYYMMDD format.
TimeCode	TimeCode	No	G62-03 — Time zone code for the date/time.
Time	Time	No	G62-04 — Time value associated with the date. HHMM format.
MessageCode	MessageCode	No	MSI-01 — Message code (e.g. rate/service type code). Optional segment.
MessageAmount	MessageAmount	No	MSI-02 — Monetary amount associated with the message code. Optional segment.
QuantityQualifier	QuantityQualifier	No	LoopQTY/QTY-01 — Qualifier for the quantity (e.g. 38=Confirmed). QTY inside LoopQTY.
Quantity	Quantity	No	LoopQTY/QTY-02 — Confirmed or adjusted quantity value.
EquipmentDescriptionCode	EquipmentDescriptionCode	No	AT9-01 — Equipment type/description code. Optional AT9 segment.
WeightQualifier	WeightQualifier	No	AT9-02 — Weight qualifier code. Optional AT9 segment.
Weight	Weight	No	AT9-03 — Shipment or equipment weight. Optional AT9 segment.
WeightUnitCode	WeightUnitCode	No	AT9-04 — Unit of measure for weight (e.g. L=Pounds, K=Kilograms).
Volume	Volume	No	AT9-05 — Volume measurement. Optional AT9 segment.
VolumeUnitQualifier	VolumeUnitQualifier	No	AT9-06 — Unit qualifier for volume (e.g. E=Cubic Feet). Optional AT9 segment.

7.1 Line-Level Party Blocks (LoopLX / LoopN1)

Each LineItem may contain line-level party blocks from the N1 loop inside LoopLX. These use the same 10-field structure as header parties.

OrderShipFrom

Ship-from party at the line level. Extracted from LoopLX/LoopN1 (N1-01=SF).

XML Element	JSON Property	Req	Description
PartyIdentification	PartyIdentification	No	N1-04 — Party identifier value (e.g. account number, location code).
PartyIdentificationType	PartyIdentificationType	No	N1-03 — Code qualifying the identifier type (e.g. 91=Assigned by Seller).
Name	Name	Yes	N1-02 — Party legal or trading name.
AdditionalName	AdditionalName	No	N2-01 — Additional name line.
StreetAddress1	StreetAddress1	No	N3-01 — Primary street address line.
StreetAddress2	StreetAddress2	No	N3-02 — Secondary address line (suite, unit, etc.).
City	City	No	N4-01 — City name.
StateCode	StateCode	No	N4-02 — Two-letter state or province code.
PostalCode	PostalCode	No	N4-03 — Postal / ZIP code.
CountryCode	CountryCode	No	N4-04 — ISO 3166-1 alpha-2 country code (e.g. US).

OrderShipTo

Ship-to party at the line level. Extracted from LoopLX/LoopN1 (N1-01=ST).

XML Element	JSON Property	Req	Description
PartyIdentification	PartyIdentification	No	N1-04 — Party identifier value (e.g. account number, location code).
PartyIdentificationType	PartyIdentificationType	No	N1-03 — Code qualifying the identifier type (e.g. 91=Assigned by Seller).
Name	Name	Yes	N1-02 — Party legal or trading name.
AdditionalName	AdditionalName	No	N2-01 — Additional name line.
StreetAddress1	StreetAddress1	No	N3-01 — Primary street address line.
StreetAddress2	StreetAddress2	No	N3-02 — Secondary address line (suite, unit, etc.).
City	City	No	N4-01 — City name.
StateCode	StateCode	No	N4-02 — Two-letter state or province code.
PostalCode	PostalCode	No	N4-03 — Postal / ZIP code.
CountryCode	CountryCode	No	N4-04 — ISO 3166-1 alpha-2 country code (e.g. US).

8. Naming Conventions

Both XML and JSON use PascalCase field names throughout (e.g. RoutingDate, StandardCarrierAlphaCode, LineItem). XML and JSON field names are identical.

The JSON root key is "RoutingInstructionsMessage" — matching the XML root element exactly.

Empty optional values: XML: <FieldName></FieldName>. JSON: "FieldName": "". Every field is always present in the output even when absent from the EDI.

All values are strings: All canonical values are typed as string — including numeric-looking fields such as OrderQuantity, Quantity, and LineItemNumber.

9. Validation Rules

Rule	Detail
Required fields	TradingPartnerId, SenderQualifier, Sender, ReceiverQualifier, Receiver, GroupFunctionCode, TransactionSetPurposeCode, ReferenceNumber, RoutingDate, and LineItemNumber (per LineItem) are always populated from the EDI.
Missing fields	Every field in the canonical structure is always present — no fields are omitted even when absent from the EDI.
ISA trimming	ISA-06 and ISA-08 are 15-character fixed-width; always trim trailing spaces.
Contact extraction	ContactPhone and ContactEmail are extracted by scanning PER-03 and PER-05 for qualifiers TE (telephone) and EM (email) respectively.
LoopQTY nesting	QTY and AT9 are inside LoopQTY (inside LoopLX). Not direct children of LoopLX. Source path: LoopQTY/QTY/QTY01.
OID path	OID is a direct child of LoopLX in 754. Source path: LoopLX/OID/OID02.
Party qualifier	Header parties: SF=ShipFrom, ST=ShipTo. Line parties (LoopLX/LoopN1): SF=OrderShipFrom, ST=OrderShipTo.
G62 date qualifiers	11=Ship Date, 10=Pickup Date. Additional qualifiers pass through in DateQualifier.
Optional segments	SMD (shipment method/mode), MSI (message code/amount), AT9 (equipment/weight) are optional — output as empty string when absent.
Multiple transactions	Multiple ST…SE blocks produce separate RoutingInstructions elements (XML) or array entries (JSON).

10. XML Example

Canonical 754 Routing Instructions in XML format. Empty tags represent optional fields not present in the source EDI.

<?xml version="1.0" encoding="UTF-8"?>

<ContactName>Jane Carrier</ContactName>

<PartyIdentification>ACME-PLANT-05</PartyIdentification>

<Name>ACME Manufacturing Corp</Name>

<StreetAddress1>1000 Industrial Pkwy</StreetAddress1>

<City>Columbus</City>

</ShipFrom>

<Name>Midwest 3PL Fulfillment</Name>

<StreetAddress1>5500 Distribution Dr</StreetAddress1>

<City>Indianapolis</City>

</ShipTo>

<PartyIdentification>ACME-PLANT-05</PartyIdentification>

<Name>ACME Manufacturing Corp</Name>

<StreetAddress1>1000 Industrial Pkwy</StreetAddress1>

<City>Columbus</City>

</OrderShipFrom>

</OrderShipTo>

</LineItem>

</RoutingInstructions>

</RoutingInstructionsMessage>

11. JSON Example

The same canonical 754 Routing Instructions in JSON format. Empty string ("") represents optional fields not present in the source EDI.

{

"RoutingInstructionsMessage": {

"RoutingInstructions": {

"TradingPartnerId": "609195581",

"Sender": "609195581",

"SenderQualifier": "01",

"Receiver": "112084681",

"ReceiverQualifier": "01",

"InterchangeDate": "260609",

"InterchangeControlNumber": "000000754",

"TestProductionIndicator": "P",

"GroupFunctionCode": "GF",

"TransactionSetPurposeCode": "00",

"ReferenceNumber": "RI-2026-060901",

"RoutingDate": "20260609",

"RoutingTime": "1656",

"TimeZoneCode": "",

"ActionCode": "",

"ContactFunctionCode": "CN",

"ContactName": "Jane Carrier",

"ContactPhone": "5559876543",

"ContactEmail": "",

"ShipFrom": {

"PartyIdentification": "ACME-PLANT-05",

"PartyIdentificationType": "91",

"Name": "ACME Manufacturing Corp",

"AdditionalName": "",

"StreetAddress1": "1000 Industrial Pkwy",

"StreetAddress2": "",

"City": "Columbus",

"StateCode": "OH",

"PostalCode": "43204",

"CountryCode": "US"

"ShipTo": {

"PartyIdentification": "WH-MW-001",

"PartyIdentificationType": "91",

"Name": "Midwest 3PL Fulfillment",

"StreetAddress1": "5500 Distribution Dr",

"City": "Indianapolis",

"StateCode": "IN",

"PostalCode": "46241",

"CountryCode": "US"

"LineItem": [

{

"LineItemNumber": "1",

"ReferenceIdentification": "REF-001",

"ReferenceQualifier": "PO",

"FreeFormDescription": "",

"StandardCarrierAlphaCode": "FEDX",

"PickupDate": "20260617",

"ShipmentMethodOfPayment": "",

"TransportationMethodCode": "",

"PurchaseOrderNumber": "PO-2026-0001",

"ReleaseNumber": "",

"UnitOrBasisForMeasurementCode": "PLT",

"OrderQuantity": "100",

"DateQualifier": "11",

"Date": "20260617",

"TimeCode": "",

"Time": "",

"MessageCode": "",

"MessageAmount": "",

"QuantityQualifier": "38",

"Quantity": "100",

"EquipmentDescriptionCode": "",

"WeightQualifier": "",

"Weight": "",

"WeightUnitCode": "",

"Volume": "",

"VolumeUnitQualifier": "",

"OrderShipFrom": {

"PartyIdentification": "ACME-PLANT-05",

"PartyIdentificationType": "91",

"Name": "ACME Manufacturing Corp",

"StreetAddress1": "1000 Industrial Pkwy",

"City": "Columbus",

"StateCode": "OH",

"PostalCode": "43204",

"CountryCode": "US"

"OrderShipTo": {

"PartyIdentification": "",

"PartyIdentificationType": "",

"Name": "",

"AdditionalName": "",

"StreetAddress1": "",

"StreetAddress2": "",

"City": "",

"StateCode": "",

"PostalCode": "",

"CountryCode": ""

}

]

}