Canonical Change Order Implementation Guide and Specifications

Modified on Tue, May 26 at 9:25 AM

ECGrid Simplify

Canonical Change Order Format Specification

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

1. Purpose

This document defines the canonical change order format used by ECGrid Simplify. It is the single source of truth for change 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 change order. A JSON Schema (Simplify_XML_ChangeOrder.schema.json) provides machine-enforceable validation. This document is the human-readable companion.

2. Scope

In scope:

Change order document structure (header and detail lines).
Field-level definitions, data types, length limits, and validation rules.
Canonical XML and JSON representations.
Party identification, order references, and change reason codes.
Date ranges for delivery, shipment, and blanket periods.

Out of scope:

Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
Functional acknowledgments and application responses.
Change cost impact calculations and approval workflows.

3. Document Structure

A change order payload contains one or more change orders. Each change order has a single header block. The header contains trading partner identifiers, order references, document metadata, multiple party blocks (Buyer, Seller, ShipTo, BillTo, Store, Warehouse, Carrier), and one or more detail lines representing line item changes.

Top-level shape:

changeOrders[]

└── changeOrder (required, exactly one)

├── header (required, exactly one)

│ ├── tradingPartnerID

│ ├── documentId

│ ├── sender / senderQualifier

│ ├── receiver / receiverQualifier

│ ├── purchaseOrderNumber / purchaseOrderDate

│ ├── revisionNumber

│ ├── documentStatusCode

│ ├── dateInformation (multiple date ranges)

│ ├── buyer, seller, billTo, shipTo, store, warehouse, carrier (party blocks)

│ └── detail[] (1..n line items)

4. Header Fields

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 change order document.	CO-123456
userId	string	1–35	No	User ID of the person creating the change order.	USER123
sender	string	2–17	Yes	Sender ID 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 in the 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
creationDateTime	string	14–17	Yes	Date/time the change order was created. YYYYMMDDHHMMSS or CCYYMMDDHHMMSSZZZ.	20260526143001
documentStatusCode	string	1–3	Yes	Status code (e.g., 00=Original, 01=Replace, 04=Void).	00
documentOrderType	string	2	Yes	Document type code (e.g., 02=Purchase Order, 05=Change Order).	05
purchaseOrderNumber	string	1–22	Yes	Original purchase order number being changed.	123456
purchaseOrderDate	string	8	No	Original PO issue date. YYYYMMDD.	20260423
customerOrderNumber	string	1–22	No	Buyer's internal order number.	CUST-789
revisionNumber	string	1–6	Yes	Revision/change sequence number for this change order.	1
lastUpdateDateTime	string	14–17	No	Last update date/time. YYYYMMDDHHMMSS.	20260526143001
totalTaxAmount	number	1–17	No	Total tax for the change order.	50.00
totalOrderAmount	number	1–17	No	Total monetary amount including tax.	1050.00
totalLines	integer	1–5	No	Count of detail lines.	10
totalQty	number	1–15	No	Total quantity across all lines.	100

5. Date Information Block

The dateInformation block contains multiple date ranges used for delivery scheduling, shipment timing, and blanket order periods. All date fields accept YYYYMMDD format or empty string when not supplied.

Field	Type	Length	Req	Description	Example
requestedDeliveryDateRange.beginDate	string	0 or 8	No	Requested delivery period start date. YYYYMMDD.	20260501
requestedDeliveryDateRange.endDate	string	0 or 8	No	Requested delivery period end date. YYYYMMDD.	20260515
requestedShipDateRange.beginDate	string	0 or 8	No	Requested shipment period start date.	20260425
requestedShipDateRange.endDate	string	0 or 8	No	Requested shipment period end date.	20260430
blanketDateRange.beginDate	string	0 or 8	No	Blanket order validity period start date.	20260101
blanketDateRange.endDate	string	0 or 8	No	Blanket order validity period end date.	20261231
ticketingDateRange.beginDate	string	0 or 8	No	Ticketing/invoicing period start date.	20260501
ticketingDateRange.endDate	string	0 or 8	No	Ticketing/invoicing period end date.	20260531

Note: All dates are optional. Empty dates should be represented as empty strings in JSON or self-closing tags in XML.

6. Party Address Block

The same party structure is used for buyer, seller, billTo, shipTo, store, warehouse, and carrier. This allows flexibility in specifying multiple parties involved in the change order.

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
name	string	1–60	Yes	Legal name of the party.	Acme Corp
name2	string	1–60	No	Secondary name line.	Division A
name3	string	1–60	No	Tertiary name line.	Dept. 5
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
cityCode	string	1–10	No	City code if applicable.
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.

7. Detail Line

The detail array is required and must contain at least one line. Each line represents a change to a line item on the original purchase order.

Field	Type	Length	Req	Description	Example
lineItemNumber	integer	1–6	Yes	Sequential line number within the change order.	1
poLineItemNumber	integer	1–6	No	Reference to the line number on the original PO.	5
changeReasonCode	string	1–3	Yes	Reason for the change (e.g., QI=Quantity Increase, QD=Quantity Decrease, PD=Price Down, PU=Price Up, CD=Cancel Line).	QI
sku	string	1–48	Yes	SKU or internal product identifier.	HOR9904088
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
invoiceQty	number	1–15	No	New quantity for this line item change.	5
quantityUnitOfMeasure	string	2–3	No	Unit of measure (e.g. EA, CS, LB, KG).	EA
unitPriceNet	number	1–17	No	New net unit price (if changed).	95.50
description	string	1–255	No	Description of the change.	Increased quantity per verbal authorization.

8. Naming Conventions

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

9. XML Example

<ChangeOrderMessage>
<ChangeOrder>
<TradingPartnerId>SEV2TEST01</TradingPartnerId>
<DocumentId>CO-123456</DocumentId>
<UserId>USER123</UserId>
<SenderQualifier>SE</SenderQualifier>
<Sender>SEV2TEST01</Sender>
<ReceiverQualifier>SE</ReceiverQualifier>
<Receiver>SEV2TEST02</Receiver>
<CreationDateTime>20260526143001</CreationDateTime>
<DocumentStatusCode>00</DocumentStatusCode>
<DocumentOrderType>05</DocumentOrderType>
<PurchaseOrderNumber>123456</PurchaseOrderNumber>
<PurchaseOrderDate>20260423</PurchaseOrderDate>
<RevisionNumber>1</RevisionNumber>
<DateInformation>
<RequestedDeliveryDateRange>
<BeginDate>20260501</BeginDate>
<EndDate>20260515</EndDate>
</RequestedDeliveryDateRange>
<RequestedShipDateRange>
<BeginDate>20260425</BeginDate>
<EndDate>20260430</EndDate>
</RequestedShipDateRange>
</DateInformation>
<Buyer>
<PartyIdentification>12345</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Acme Corp</Name>
<StreetAddress1>123 Main St</StreetAddress1>
<City>Albany</City>
<StateCode>NY</StateCode>
<PostalCode>12207</PostalCode>
<CountryCode>US</CountryCode>
</Buyer>
<Seller>
<PartyIdentification>54321</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Widget Supplier Inc</Name>
<StreetAddress1>456 Oak Ave</StreetAddress1>
<City>Springfield</City>
<StateCode>IL</StateCode>
<PostalCode>62701</PostalCode>
<CountryCode>US</CountryCode>
</Seller>
<ShipTo>
<PartyIdentification>12345-001</PartyIdentification>
<PartyIdentificationTypeCode>92</PartyIdentificationTypeCode>
<Name>Acme Warehouse</Name>
<StreetAddress1>999 Distribution Dr</StreetAddress1>
<City>Newark</City>
<StateCode>NJ</StateCode>
<PostalCode>07101</PostalCode>
<CountryCode>US</CountryCode>
</ShipTo>
<OrderLineItem>
<LineItemNumber>1</LineItemNumber>
<POLineItemNumber>5</POLineItemNumber>
<ChangeReasonCode>QI</ChangeReasonCode>
<Sku>HOR9904088</Sku>
<SupplierAssignedPartNumber>VN123456789</SupplierAssignedPartNumber>
<BuyerAssignedPartNumber>BY123456789</BuyerAssignedPartNumber>
<InvoiceQty>5</InvoiceQty>
<QuantityUnitOfMeasure>EA</QuantityUnitOfMeasure>
<UnitPriceNet>95.50</UnitPriceNet>
<Description>Increased quantity per verbal authorization</Description>
</OrderLineItem>
</ChangeOrder>
</ChangeOrderMessage>

10. JSON Example

{
"changeOrders": [
{
"changeOrder": {
"tradingPartnerId": "SEV2TEST01",
"documentId": "CO-123456",
"userId": "USER123",
"sender": "SEV2TEST01",
"senderQualifier": "SE",
"receiver": "SEV2TEST02",
"receiverQualifier": "SE",
"creationDateTime": "20260526143001",
"documentStatusCode": "00",
"documentOrderType": "05",
"purchaseOrderNumber": "123456",
"purchaseOrderDate": "20260423",
"revisionNumber": "1",
"dateInformation": {
"requestedDeliveryDateRange": {
"beginDate": "20260501",
"endDate": "20260515"
},
"requestedShipDateRange": {
"beginDate": "20260425",
"endDate": "20260430"
}
},
"buyer": {
"partyIdentification": "12345",
"partyIdentificationTypeCode": "92",
"name": "Acme Corp",
"streetAddress1": "123 Main St",
"city": "Albany",
"stateCode": "NY",
"postalCode": "12207",
"countryCode": "US"
},
"seller": {
"partyIdentification": "54321",
"partyIdentificationTypeCode": "92",
"name": "Widget Supplier Inc",
"streetAddress1": "456 Oak Ave",
"city": "Springfield",
"stateCode": "IL",
"postalCode": "62701",
"countryCode": "US"
},
"shipTo": {
"partyIdentification": "12345-001",
"partyIdentificationTypeCode": "92",
"name": "Acme Warehouse",
"streetAddress1": "999 Distribution Dr",
"city": "Newark",
"stateCode": "NJ",
"postalCode": "07101",
"countryCode": "US"
},
"orderLineItem": [
{
"lineItemNumber": 1,
"poLineItemNumber": 5,
"changeReasonCode": "QI",
"sku": "HOR9904088",
"supplierAssignedPartNumber": "VN123456789",
"buyerAssignedPartNumber": "BY123456789",
"invoiceQty": 5,
"quantityUnitOfMeasure": "EA",
"unitPriceNet": 95.50,
"description": "Increased quantity per verbal authorization"
}
]
}
}
]
}