This purchase order example is a Stand Alone order:
"ODF Buyer" wants to buy 2 types of items to "ODF Supplier" and receive them at one of "ODF Buyer" store location.

On the right side, you can see:

  • the structure or the purchase order (in JSON or X12), composed of several segments and loops that could be repeated.
  • the payload example (in JSON or X12)

The ISA, GS and ST segments are part of the X12 standard and define the sender, the receiver and the transaction traded. The description of these segments can be found in this section.

🚧

Update sender and receiver to test

If you want to use the example to post a transaction or upload a transaction, make sure you edit the sender and receiver ISA IDs (marked ODF_SUPPLIER and ODF_BUYER)

BEG Beginning Segment for Purchase Order

The Beginning Segment for Purchase Order (BEG) segment provides information on the type of order, its reference and creation date.
In the example, we're looking at an original standalone order (00 = Original, SA = Standalone), a common order type in Retail. The purchase order number is PO123456789. It has been created on the August 28th, 2020.

"beginningSegmentForPurchaseOrder": [
        {
          "transactionSetPurposeCode": "00",
          "purchaseOrderTypeCode": "SA",
          "purchaseOrderNumber": "PO123456789",
          "date": "20200828"
        }
      ],
BEG*00*SA*PO1234321**20200828~

Description of the elements for the segment Beginning Segment for Purchase Order

JSON Element

X12 Element

Value

Description

transactionSetPurposeCode

BEG01

00

This code defines the purpose of order.
00 means "Original". Other qualifiers can be used, such as 01 (Cancellation) or 04 (Change).

purchaseOrderTypeCode

BEG02

SA

This code defines the type of order.
SA means "Standalone". Other qualifiers can be used, such as DS (Dropship) or DO (Domestic Order).

purchaseOrderNumber

BEG03

PO123456789

The purchase order number.

date

BEG05

20200828

The date the purchase order is created.

REF Reference Information

The Reference Information (REF) segment provides information on references that best describes the order, the buyer or the supplier.

In this example, "ODF Buyer" department number 210 has been placing this order.

"referenceInformation": [
        {
          "referenceIdentificationQualifier": "DP",
          "referenceIdentification": "210"
        }
      ]
REF*DP*210~

Elements of the segment Reference Information

JSON Element

X12 Element

Value

Description

referenceIdentificationQualifier

REF01

DP

This qualifier qualifies the type of reference given in the element referenceIdentification (REF01).

DP means "Department Number". Other qualifiers could be used, such as IA (Internal Vendor Number).

referenceIdentification

REF02

210

Value of the ReferenceIdentificationQualifier.

DTM Date/Time Reference

The Date/Time Reference (DTM) segment provides information on the important dates related to this order.

In this example, "ODF Buyer" is requesting all the products within this purchase order to be:

  • delivered by September 10th, 2020.
  • shipped by September 5th, 2020.
"dateTimeReference": [
        {
          "dateTimeQualifier": "002",
          "date": "20200910"
        },
        {
          "dateTimeQualifier": "010",
          "date": "20200905"
        }
      ]
DTM*002*20200910~         
DTM*010*20200905~

Elements of the segment Date/Time Reference (1st iteration of the segment)

JSON Element

X12 Element

Value

Description

dateTimeQualifier

DTM01

002

This qualifier qualifies the type of date given in the the element date (DTM02).

002 means "Delivery Requested". Other qualifiers could have been used, such as 106 (Required By) or 010 (Requested Ship Date).

date

DTM02

20200910

The value in this field corresponds to the qualifier above.

N1 Loop

The Address (N1) loop provides information on the relevant addresses in the purchase order.

In this purchase order, the N1 loop describes two addresses for this order:

  • The billing address - entityIdentifierCode: BT
    The billing address is 1119 Bush street, San Francisco, CA 94101. The recipient is ODF Buyer HQ.

  • The shipping address - entityIdentifierCode: ST
    The shipping address is 1207 Washington Road, Seattle, Washington, CA 98101. The recipient is ODF Buyer Main store.

Each of these addresses is included in one iteration of the N1 loop which is each composed of one or several segments:

  • Party Identification (N1) - This segment controls the content of the loop
  • Party Location (N3)
  • Geographic Location (N4)
"N1_loop": [
        {        //1st N1 loop iteration
          "partyIdentification": [
            {
              "entityIdentifierCode": "BT",
              "name": "ODF Buyer HQ"
            }
          ],
          "partyLocation": [
            {
              "addressInformation": "1119 BUSH STREET"
            }
          ],
          "geographicLocation": [
            {
              "cityName": "SAN FRANCISCO",
              "stateOrProvinceCode": "CA",
              "postalCode": "94101"
            }
          ]
        },
        {        //2nd N1 loop iteration
          "partyIdentification": [
            {
              "entityIdentifierCode": "ST",
              "name": "ODF BUYER MAIN STORE"
            }
          ],
          "partyLocation": [
            {
              "addressInformation": "1207 WASHINGTON RD"
            }
          ],
          "geographicLocation": [
            {
              "cityName": "SEATTLE",
              "stateOrProvinceCode": "WA",
              "postalCode": "98101"
            }
          ]
        }
      ]
N1*BT*ODF BUYER HQ~                                     ⇡
N3*1119 BUSH STREET~                         //1st N1 loop iteration
N4*SAN FRANCISCO*CA*94101~                              ⇣
N1*ST*ODF BUYER MAIN STORE~                             ⇡
N3*1207 WASHINGTON RD~                       //2nd N1 loop iteration
N4*SEATTLE*WA*98101~                                    ⇣

N1 Party Identification

The party identification provides the type of contact and the contact name.

  • The billing contact is ODF Buyer HQ.
  • The shipping contact is ODF Buyer Main Store.
"partyIdentification": [
            {
              "entityIdentifierCode": "BT",
              "name": "ODF Buyer HQ"
            }
          ]
N1*BT*ODF BUYER HQ~

Elements of the segment Party Identification (N1) for the shipping address (1st iteration of the N1 loop)

JSON Element

X12 Element

Value

Description

entityIdentifierCode

N101

BT

This code describes the type of date given in the the element name (N102).

BT means Bill To.
Other qualifiers can be used by buyers, such as ST (Ship To) or BY (Buying Party (Purchaser)).

name

N102

ODF BUYER HQ

The value associated with the code above.

N3 Party Location

The party location provides the address for the contact defined in the previous segment (Party Identification or N1 segment).

  • The address of the billing contact is 1119 Bush street.
  • The address of the shipping contact is 12 Main street.
"partyLocation": [
            {
              "addressInformation": "1119 BUSH STREET"
            }
          ]
N3*1119 BUSH STREET~

Elements of the segment Party Location (N3) for the shipping address (2nd iteration of the N1 loop)

JSON Element

X12 Element

Value

Description

addressInformation

N301

1119 BUSH STREET

This is address line 1

N4 Geographic Location

The geographic location provides the city and country information for the contact defined in the previous segment (Party Identification or N1 segment).

  • The billing contact is in San Francisco, California 94101.
  • The shipping contact is in Seattle, Washington 98101.
"geographicLocation": [
            {
              "cityName": "SAN FRANCISCO",
              "stateOrProvinceCode": "CA",
              "postalCode": "94101"
            }
          ]
N4*SAN FRANCISCO*CA*94101~

Elements of the segment Geographic Location (N4) for the shipping address (2nd iteration of the N1 loop)

JSON Element

X12 Element

Value

Description

cityName

N401

SAN FRANCISCO

City

stateOrProvinceCode

N402

CA

Two character state code

postalCode

N403

94101

Postal code

PO1 Loop

The PO1 loop contains the line detail. This loop describes the items the buyer wants to purchase.

In this example, ODF Buyer want to purchase two items:

  • 48 cases of vermillion sunglasses referenced with the UPC code "711719100246" and the Vendor Number 009A at $26.25 per case.
  • 120 cases of yellow sunglasses referenced with the UPC code "611719100245" and the Vendor Number 009A at $27.45 per case.

Each of these items are included in one iteration of the PO1 loop and are composed of one or several loop and segment:

  • Baseline Item Data (PO1) - This segment controls the content of the loop
  • PID Loop
"PO1_loop": [
        {        //1st PO1 loop iteration
          "baselineItemData": [
            {
              "assignedIdentification": "1",
              "quantity": "48",
              "unitOrBasisForMeasurementCode": "CA",
              "unitPrice": "26.25",
              "productServiceIDQualifier": "UP",
              "productServiceID": "711719100246",
              "productServiceIDQualifier1": "VN",
              "productServiceID1": "009"
            }
          ],
          "PID_loop": [
            {
              "productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES VERMILLION (E16249)"
                }
              ]
            }
          ]
        },
        {        //2nd PO1 loop iteration
          "baselineItemData": [
            {
              "assignedIdentification": "2",
              "quantity": "120",
              "unitOrBasisForMeasurementCode": "CA",
              "unitPrice": "27.45",
              "productServiceIDQualifier": "UP",
              "productServiceID": "611719100245",
              "productServiceIDQualifier1": "VN",
              "productServiceID1": "009A"
            }
          ],
          "PID_loop": [
            {
              "productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES YELLOW (F8C729)"
                }
              ]
            }
          ]
        }
      ]
PO1*1*48*CA*26.25**UP*711719100246*VN*009~
PID*F****SUNGLASSES VERMILLION (E16249)~
PO1*2*120*CA*27.45**UP*611719100245*VN*009A~
PID*F****SUNGLASSES YELLOW (F8C729)~

PO1 Baseline Item Data

The baseline item data segment provides the line item data.

For example, in the first iteration of the PO1 loop, the buyer wants to buy 48 cases of the item referenced with the UPC code "711719100246" and the Vendor Number 009 at $26.25 per case.

"baselineItemData": [
            {
              "assignedIdentification": "1",
              "quantity": "48",
              "unitOrBasisForMeasurementCode": "CA",
              "unitPrice": "26.25",
              "productServiceIDQualifier": "UP",
              "productServiceID": "711719100246",
              "productServiceIDQualifier1": "VN",
              "productServiceID1": "009"
            }
          ]
PO1*1*48*CA*26.25**UP*711719100246*VN*009~

JSON Element

X12 Element

Value

Description

assignedIdentification

PO101

1

This is the line number

quantity

PO102

48

This element is a quantity ordered.

The quantity is described by the element unitOrBasisForMeasurementCode (PO103).

The buyer want to buy 48 cases of line 1.

unitOrBasisForMeasurementCode

PO103

CA

This is the unit of measurement code.

The unit of measure describes the meaning of the quantity (PO102).

The buyer want to buy 48 cases line 1.

CA can mean Case. Other codes will be used by buyers such as PR (Pair) or EA (Each).

unitPrice

PO104

26.25

This is the price per unit.

This element is the price of the item for the unit of measurement defined in the element unitOrBasisForMeasurementCode (PO103).

The item is worth $26.25 per case.

productServiceIDQualifier

PO105

UP

This qualifier qualifies the reference of the item given in the element productServiceID (PO106).

UP means U.P.C. Consumer Package Code (1-5-5-1).
Other qualifiers like EA (EAN) or VN (Vendor Number) can be used by buyers.

productServiceID

PO106

711719100246

This field is the value related to the producServiceIDQualifier (PO105).

711719100246 is the UPC code of line 1.

productServiceIDQualifier1

PO107

VN

This is the second item reference qualifier to the same line item.

This qualifier qualifies the reference of the item given in the element productServiceID1 (PO108).

VN means Vendor's (Seller's) Item Number.
Other qualifiers can be used by buyers.

productServiceID1

PO108

009

This field is the value of producServiceIDQualifier1 (PO107).

009 is the vendor item number for line 1.

PID Loop

The PID loop provides the description for each PO1. That's why the PID loop is a child loop and is included in the PO1 loop.

Each of these descriptions is included in one iteration of the PID loop and are composed of one segment:

  • Product/Item Description (PID)
"PID_loop": [
            {
              "productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES VERMILLION (E16249)"
                }
              ]
            }
          ]
PID*F****SUNGLASSES VERMILLION (E16249)~

PID Product/Item Description

The product/item description segment provides descriptive information on each item of the purchase order.
In the first iteration of the PO1 loop, the purchaser want to buy the item with described as sunglasses vermillion (E16249).

"productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES VERMILLION (E16249)"
                }
              ]
PID*F****SUNGLASSES VERMILLION (E16249)~

JSON Element

X12 Element

Value

Description

itemDescriptionTypeCode

PID01

F

This qualifier qualifies the type of description the item given in the element description (PID05).

F means Free-Form.
Other qualifiers can be used by buyers.

description

PID05

SUNGLASSES VERMILLION (E16249)

This is a freeform text field describing the product.

SUNGLASSES VERMILLION (E16249) is the description of line 1.

CTT Loop

The CTT loop provides a summary of the order.

Each type of summary is included in one iteration of the CTT loop and is composed of one segment:

  • Transaction Totals (CTT)
"CTT_loop": [
        {
          "transactionTotals": [
            {
              "numberOfLineItems": "2"
            }
          ]
        }
      ]
CTT*2~

CTT Transaction Totals

The transaction totals segment provides information about totals included in this order, such as the total amount of items or the total price of the order.
In this example, the purchase order contains 2 line items, meaning the buyer placed an order for 2 types of items described in the PO1 loop.

"transactionTotals": [
            {
              "numberOfLineItems": "2"
            }
          ]
CTT*2~

JSON Element

X12 Element

Value

Description

numberOfLineItems

CTT01

2

The count of line numbers in the payload.

The buyer included 2 lines in this order. This is defined by 2 iterations of the PO1 loop.

Purchase Order Structure
"interchangeControlHeader",                //Interchange Control Header (Optional for JSON)
  "functionalGroupHeader",                 //Functional Group Header (Optional for JSON)
  "transactionSets"
      "transactionSetHeader",              //Transaction Set Header (Optional for JSON)
                                
      //Header level
      "beginningSegmentForPurchaseOrder",  //Beginning Segment for Purchase Order
      "referenceInformation",              //Reference Information
      "dateTimeReference",                 //Date/Time Reference (2 iterations)
    
      "N1_loop"                            //N1 Loop (2 iterations)
          "partyIdentification",           //Party Identification
          "partyLocation",                 //Party Location
          "geographicLocation",            //Geographic Location
      
      //Detail level
      "PO1_loop"                           //PO1 Loop (2 iterations)
          "baselineItemData",              //Baseline Item Data
          "PID_loop"                       //PID Loop
              "productItemDescription"     //Product/Item Description
    
      //Summary level
      "CTT_loop"                           //CTT Loop
          "transactionTotals",             //Transaction Totals
    
      "transactionSetTrailer"              //Transaction Set Trailer
ISA                                        //Interchange Control Header
.GS                                        //Functional Group Header

  ..ST                                       //Transaction Set Header

//Header level
...BEG                                     //Beginning Segment for Purchase Order
...REF                                     //Reference Information
...DTM                                     //Date/Time Reference (2 iterations)

...(Hidden loop)                           //N1 Loop (2 iterations)
......↳ N1                                 //Party Identification
......↳ N3                                 //Party Location
......↳ N4                                 //Geographic Location

//Detail level
...(Hidden loop)                           //PO1 Loop (2 iterations)
......↳ PO                                 //Baseline Item Data 
......↳ (Hidden loop)                      //PID Loop
.........↳ PID                             //Product/Item Description

//Summary level
...(Hidden loop)                           //CTT Loop
......↳ CTT                                //Transaction Totals

..SE                                       //Transaction Set Trailer
.GS                                        //Functional Group Trailer
ISA                                        //Interchange Control Trailer
Purchase Order Example Transaction
{
    "type": {
        "name": "850_PURCHASE_ORDER"
    },
    "stream": "test",
        "sender": {
        "isaId": "string"
    },
    "receiver": {
        "isaId": "string"
    },
    "message": {
  "transactionSets": [
    {
      "transactionSetHeader": [
        {
          "transactionSetIdentifierCode": "850",
          "transactionSetControlNumber": "0001"
        }
      ],
      "beginningSegmentForPurchaseOrder": [
        {
          "transactionSetPurposeCode": "00",
          "purchaseOrderTypeCode": "SA",
          "purchaseOrderNumber": "PO123456789",
          "date": "20200828"
        }
      ],
      "referenceInformation": [
        {
          "referenceIdentificationQualifier": "DP",
          "referenceIdentification": "210"
        }
      ],
      "dateTimeReference": [
        {
          "dateTimeQualifier": "002",
          "date": "20200910"
        },
        {
          "dateTimeQualifier": "010",
          "date": "20200905"
        }
      ],
      "N1_loop": [
        {
          "partyIdentification": [
            {
              "entityIdentifierCode": "BT",
              "name": "ODF Buyer HQ"
            }
          ],
          "partyLocation": [
            {
              "addressInformation": "1119 BUSH STREET"
            }
          ],
          "geographicLocation": [
            {
              "cityName": "SAN FRANCISCO",
              "stateOrProvinceCode": "CA",
              "postalCode": "94101"
            }
          ]
        },
        {
          "partyIdentification": [
            {
              "entityIdentifierCode": "ST",
              "name": "ODF BUYER MAIN STORE"
            }
          ],
          "partyLocation": [
            {
              "addressInformation": "1207 WASHINGTON RD"
            }
          ],
          "geographicLocation": [
            {
              "cityName": "SEATTLE",
              "stateOrProvinceCode": "WA",
              "postalCode": "98101"
            }
          ]
        }
      ],
  "PO1_loop": [
        {
          "baselineItemData": [
            {
              "assignedIdentification": "1",
              "quantity": "48",
              "unitOrBasisForMeasurementCode": "CA",
              "unitPrice": "26.25",
              "productServiceIDQualifier": "UP",
              "productServiceID": "711719100246",
              "productServiceIDQualifier1": "VN",
              "productServiceID1": "009"
            }
          ],
          "PID_loop": [
            {
              "productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES VERMILLION (E16249)"
                }
              ]
            }
          ]
        },
        {
          "baselineItemData": [
            {
              "assignedIdentification": "2",
              "quantity": "120",
              "unitOrBasisForMeasurementCode": "CA",
              "unitPrice": "27.45",
              "productServiceIDQualifier": "UP",
              "productServiceID": "611719100245",
              "productServiceIDQualifier1": "VN",
              "productServiceID1": "009A"
            }
          ],
          "PID_loop": [
            {
              "productItemDescription": [
                {
                  "itemDescriptionTypeCode": "F",
                  "description": "SUNGLASSES YELLOW (F8C729)"
                }
              ]
            }
          ]
        }
      ],
      "CTT_loop": [
        {
          "transactionTotals": [
            {
              "numberOfLineItems": "2"
            }
          ]
        }
      ],
      "transactionSetTrailer": [
        {
          "numberOfIncludedSegments": "17",
          "transactionSetControlNumber": "0001"
        }
      ]
    }
  ]
}
}
ISA*00*          *00*          *ZZ*ODF_BUYER      *ZZ*ODF_SUPPLIER   *200828*0932*U*00401*001234321*0*T*>~
GS*PO*ODF_BUYER*ODF_SUPPLIER*20200828*0932*123432*X*004010~
ST*850*0001~
BEG*00*SA*PO123456789**20200828~
REF*DP*210~
DTM*002*20200910~
DTM*010*20200905~
N1*BT*ODF BUYER HQ~
N3*1119 BUSH STREET~
N4*SAN FRANCISCO*CA*94101~
N1*ST*ODF BUYER MAIN STORE~
N3*1207 WASHINGTON RD~
N4*SEATTLE*WA*98101~
PO1*1*48*CA*26.25**UP*711719100246*VN*009~
PID*F****SUNGLASSES VERMILLION (E16249)~
PO1*2*120*CA*27.45**UP*611719100245*VN*009A~
PID*F****SUNGLASSES YELLOW (F8C729)~
CTT*2~
SE*17*0001~
GE*1*1234321~
IEA*1*001234321~