Canonical Order Implementation GuidSpecifications

Modified on Tue, May 26 at 9:27 AM

ECGrid Simplify

Canonical Purchase Order Format Specification

Version: 1.0 Date: May 2026 Owner: ECGrid Product

1. Purpose

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

Both XML and JSON representations convey the same logical purchase order. A JSON Schema (Simplify_XML_Purchase_Order_schema.json) provides machine-enforceable validation. This document is the human-readable companion.

2. Scope

In scope:

Purchase order document structure (header and line items).
Field-level definitions, data types, length limits, and validation rules.
Canonical XML and JSON representations.
Party identification and date conventions.

Out of scope:

Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
EDI translation engine internals and mapping configuration.
Payment terms calculation, FOB allocation, and allowance/charge logic.

3. Document Structure

A purchase order payload contains one or more orders. Each order has a single root block. The root contains trading partner identifiers, document metadata, three party blocks (Seller, Buyer, ShipTo), and one or more line items.

Top-level shape:

OrderMessage

└── Order (required, exactly one)

├── TradingPartnerId

├── Sender / SenderQualifier

├── Receiver / ReceiverQualifier

├── DocumentOrderType / SecondaryOrderType

├── PurchaseOrderNumber / PurchaseOrderDate

├── BuyerAssignedPartCode / SupplierAssignedPartCode

├── Seller (party address)

├── Buyer (party address)

├── ShipTo (party address)

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

Note: The Canonical Purchase Order flows in the opposite direction from the Canonical Invoice. A trading partner submits an 850 EDI purchase order to ECGrid; Simplify translates it into the canonical format shown here for delivery to the receiving system. The canonical Purchase Order is the output of that process, not the input.

4. Header Fields

All 13 order-level fields are required by the JSON Schema. The fields map closely to BEG segment elements in the X12 850 transaction set.

Field	Type	Length	Req	Description	Example
tradingPartnerID	string	1–35	Yes	ECGrid trading partner identifier. Routes the document.	SEV2TEST01
sender	string	2–17	Yes	Sender ID in the qualifier namespace.	SEV2TEST01
senderQualifier	string	1–4	Yes	Qualifier for sender ID (e.g. ZZ, 01, 14).	ZZ
receiver	string	2–17	Yes	Receiver ID in the qualifier namespace.	SEV2TEST02
receiverQualifier	string	1–4	Yes	Qualifier for receiver ID.	ZZ
documentOrderType	string	2	Yes	BEG01 — order type code (e.g. 00 = Original PO).	00
secondaryOrderType	string	2	Yes	BEG02 — secondary order type (e.g. NE = New Order).	NE
purchaseOrderNumber	string	1–22	Yes	BEG03 — the purchase order number. Unique per sender.	30576
purchaseOrderDate	string	8	Yes	BEG05 — PO date. YYYYMMDD. 8 digits exact.	20260417
seller	party	—	Yes	Selling party. See §5.	—
buyer	party	—	Yes	Buying party. See §5.	—
shipTo	party	—	Yes	Delivery destination party. See §5.	—
detail	array	1..n	Yes	One or more line items. See §6.	—

5. Party Address Block

The same structure is used for seller, buyer, and shipTo. Five party types are supported in the full schema: ShipTo, Buyer, Seller, BillTo, and Store. All use this address structure.

Field	Type	Length	Req	Description	Example
name	string	1–60	Yes	Legal or trading name of the party.	Medigi, LLC
streetAddress1	string	1–55	Yes	Primary street address line.	200 E ROBINSON ST STE 1250
city	string	2–30	Yes	City.	ORLANDO
stateCode	string	2	Yes	State or province code. 2 chars exact for US/CA.	FL
postalCode	string	3–15	Yes	Postal/ZIP code.	32801
countryCode	string	2	No	ISO 3166-1 alpha-2 country code. 2 chars exact.	US
partyIdentification	string	1–80	No	Party identifier value (DEA, HIN, GLN, internal code, etc.).	AM1234567
partyIdentificationCode	string	1–5	No	Qualifier for the identifier type (e.g. 11 = DEA).	11

6. Detail Line

The detail array is required and must contain at least one line. Each line carries the fields below. All required line item fields are typed as string — including numeric-looking fields such as lineItemNumber, orderedQuantity, and netUnitPrice.

Field	XML Element	Type	Length	Req	Description	Example
lineItemNumber	LineItemNumber	string	1–6	Yes	PO101 — line sequence number.	1
orderedQuantity	OrderedQuantity	string	1–15	Yes	PO102 — quantity ordered.	100
quantityUnitOfMeasure	QuantityUnitOfMeasure	string	2–3	Yes	PO103 — unit of measure (e.g. EA, CA).	EA
unitPriceNet	NetUnitPrice	string	1–17	Yes	PO104 — net price per unit in document currency.	28.98
sku	Sku	string	1–48	Yes	Stock-keeping unit code (VP qualifier from PO1).	SK1234567890
buyerAssignedPartNumber	BuyerAssignedPartCode	string	1–48	Yes	Buyer’s part number (BP qualifier from PO1).	BP1234567890
supplierAssignedPartNumber	SupplierAssignedPartCode	string	1–48	Yes	Supplier’s part number (VN qualifier from PO1).	VN1234567890

Note: BuyerAssignedPartCode and SupplierAssignedPartCode appear at both the Order level and inside OrderLineItem. The Order-level values repeat the line-item values for the first (or only) line. Systems should read part codes from within OrderLineItem for line-specific processing.

7. Naming Conventions

XML: PascalCase for all element names (e.g. PurchaseOrderNumber, OrderLineItem, StreetAddress1).
JSON: PascalCase for all field names — matching the XML element names. This differs from the Canonical Invoice JSON, which uses camelCase.
Field semantics and length limits are identical across both. Only the serialization format differs.
Empty optional values in XML use self-closing tags (e.g. <CountryCode/>). In JSON, use empty string for string fields.
The JSON root key is "OrderMessage" (not "orders" as declared in the schema). Systems should use "OrderMessage" as the actual root key when consuming or producing JSON.

8. XML Example

<Order>

<Name>Medigi, LLC</Name>

<StreetAddress1>200 E ROBINSON ST STE 1250</StreetAddress1>

<City>ORLANDO</City>

</Seller>

<Buyer>

<Name>MedShorts LLC</Name>

<StreetAddress1>200 EAST ROBINSON STREET</StreetAddress1>

<City>ORLANDO</City>

</Buyer>

<Name>MEDIGI INPATIENT</Name>

<StreetAddress1>200 EAST ROBINSON STREET</StreetAddress1>

<City>ORLANDO</City>

</ShipTo>

</OrderLineItem>

</Order>

</OrderMessage>

9. JSON Example

{

"OrderMessage": {

"Order": {

"TradingPartnerId": "SEV2TEST01",

"SenderQualifier": "ZZ",

"Sender": "SEV2TEST01",

"ReceiverQualifier": "ZZ",

"Receiver": "SEV2TEST02",

"DocumentOrderType": "00",

"SecondaryOrderType": "NE",

"PurchaseOrderNumber": "30576",

"PurchaseOrderDate": "20260417",

"BuyerAssignedPartCode": "BP1234567890",

"SupplierAssignedPartCode": "VN1234567890",

"Seller": {

"PartyIdentification": "",

"PartyIdentificationCode": "",

"Name": "Medigi, LLC",

"StreetAddress1": "200 E ROBINSON ST STE 1250",

"City": "ORLANDO",

"StateCode": "FL",

"PostalCode": "32801",

"CountryCode": ""

"Buyer": {

"PartyIdentification": "",

"PartyIdentificationCode": "",

"Name": "MedShorts LLC",

"StreetAddress1": "200 EAST ROBINSON STREET",

"City": "ORLANDO",

"StateCode": "FL",

"PostalCode": "32801",

"CountryCode": ""

"ShipTo": {

"PartyIdentification": "AM1234567",

"PartyIdentificationCode": "11",

"Name": "MEDIGI INPATIENT",

"StreetAddress1": "200 EAST ROBINSON STREET",

"City": "ORLANDO",

"StateCode": "FL",

"PostalCode": "32801",

"CountryCode": ""

"OrderLineItem": {

"LineItemNumber": "1",

"OrderedQuantity": "100",

"QuantityUnitOfMeasure": "EA",

"NetUnitPrice": "28.98",

"SupplierAssignedPartCode": "VN1234567890",

"BuyerAssignedPartCode": "BP1234567890",

"Sku": "SK1234567890"

}