James Allman | JA Technology Solutions LLC
Building EDI X12 Documents: A Supplier's Guide
Reading an 850 purchase order is one skill. Building the 855, 856, 810, and 997 that close the loop is another. Here is what outbound EDI looks like from the supplier side, and where it breaks.
If you have recently been told that a new retail buyer requires EDI, or you are already trading with one and your invoices keep getting kicked back, this article is for you. It is written for the supplier side: the vendors, distributors, and manufacturers who need to send compliant EDI to their retail trading partners, not the buyers receiving it. The companion article EDI X12: What's Inside an 850, 810, and 856 covers the reading side in detail. This one covers the building side.
The core of outbound EDI is a predictable document loop. An 850 purchase order arrives from the buyer. You send back an 855 PO acknowledgment. When the goods ship, you send an 856 advance ship notice. When billing, you send an 810 invoice. When the buyer remits payment, they may send an 820 remittance advice. A 997 functional acknowledgment closes each transmission on both sides. Getting any one of these wrong costs money, and getting the 856 wrong costs the most.
The supplier document loop: 850 in, five documents out
The 850 arrives via your VAN, AS2 connection, or SFTP directory. Your first task is to parse it, extract the PO number from BEG03, map the line items from the PO1 loops, and confirm you can fulfill the order. That confirmation is the 855 PO acknowledgment. The 855 BEG segment references the original PO number, and each line carries an ACK segment with a status code: IA (accepted), IQ (accepted with change), IR (rejected). If you accept a line but with a different quantity or ship date, IQ is the correct code, and you supply the modified value.
The 856 advance ship notice is the next document and the one that causes the most compliance failures. It must be transmitted before the truck arrives at the buyer's dock. Most retailers require it within a specific window, often 24 hours before delivery and no later than the ship date. The 856 uses HL hierarchical level segments to describe the physical shipment, and every SSCC-18 barcode on every pallet or carton must match what is in the document. The 810 invoice follows after delivery. Its BIG04 must contain the exact PO number from the original 850: this is the cross-reference that drives three-way matching at the buyer. The 820 remittance comes back from the buyer when they pay.
The X12 envelope: what rejects the whole interchange
Every X12 document travels inside three nested envelopes. The ISA segment opens the interchange, the GS segment opens the functional group, and the ST segment opens the transaction set. Each has a matching trailer: IEA for ISA, GE for GS, SE for ST. The control number in each trailer must match the one in the corresponding header, and the SE01 element must contain an exact count of every segment from ST through SE inclusive. Getting any of these wrong rejects the entire interchange at the partner's translator, not just the affected transaction.
The ISA segment is exactly 106 characters and is the only fixed-length segment in X12. It also declares the element separator, sub-element separator, and segment terminator for the rest of the file. Your output must use the same characters the ISA declares. Most implementations use an asterisk (*) as the element separator, a tilde (~) as the segment terminator, and a colon (:) as the sub-element separator, but nothing in the standard requires those specific characters. Read the ISA before parsing; never assume the delimiters.
The GS segment carries the functional identifier code that tells the receiver what kind of documents are in the group: PO for purchase orders, PR for PO acknowledgments, SH for ship notices, IN for invoices. One GS group should contain only one transaction type. The version element (GS08) typically reads 004010 for the widely deployed 4010 release or 005010 for 5010. Your trading partner's implementation guide will specify which version they require. You can inspect any outbound file with the EDI File Parser to confirm the envelope is correctly formed before transmitting.
Trading-partner implementation guides and certification
Every retailer publishes an implementation guide, sometimes called a companion guide or mapping spec, that defines exactly how they expect each transaction set built. These guides override the base X12 standard at every point where the standard leaves flexibility. A segment that is optional in the standard may be mandatory for a specific partner. An element that the standard allows as free-form text may be restricted to a defined value list. The SSCC-18 format on the 856 MAN segment, the qualifier code on the N1 ship-to loop, the specific pack structure (shipment/order/item versus shipment/order/pack/item) the buyer's receiving system requires: none of that is in the X12 specification. All of it is in the implementation guide.
Most retailers require you to pass a certification test before going live. That process typically involves transmitting sample documents against a test account and receiving back a set of 997 functional acknowledgments plus feedback on any spec violations. Common reasons certification fails: the BSN02 shipment ID format is wrong, the SSCC-18 does not match their label specification, the CTT01 count does not match the actual number of line items, or the N1 qualifier codes use the generic values instead of the buyer-specific ones. Certification failures are not rare; plan for at least two or three rounds. The EDI 856 ASN Builder, EDI 850 PO Builder, EDI 855 PO Ack Builder, and EDI 810 Invoice Builder produce valid 4010 documents you can use to run against a test environment before your integration is built.
Implementation guides are also not static. Retailers update them when they change their receiving systems, add new required segments, or tighten tolerances on existing ones. An integration that passed certification three years ago may no longer comply. Change notices arrive on short timelines, and some partners enforce the new spec before everyone has had a chance to update. Monitoring the acknowledgments your partner sends back after each transmission is the only reliable way to catch compliance drift early.
The 856 ASN: where the chargebacks are
Compliance chargebacks are the financial consequence of getting EDI wrong, and the 856 advance ship notice generates more of them than any other document. The two most common triggers are a missing or late ASN (the document was not transmitted before the shipment arrived), and an ASN that does not match the physical shipment (the SSCC-18 on the document does not match the label on the pallet, or the quantities in the HL item loops do not match what the receiving dock counted). Either way, the retailer cannot receive the shipment electronically, and that labor cost comes back to the supplier as a chargeback.
The HL hierarchy is the structural source of most ASN failures. Each HL segment carries a unique sequential ID (HL01), a parent ID (HL02), and a level code (HL03). The standard level codes for a retail ASN are S for shipment (the top level), O for order (one per PO being fulfilled), P for pack (one per pallet or carton), and I for item. Not all trading partners require the pack level, but the ones that do use it to drive cross-docking: the pallet label's SSCC-18 is in the MAN segment at the pack level, and if it does not match the physical label, the conveyor system cannot route the pallet. Missing a level, assigning the wrong parent ID, or getting the HL01 sequence out of order produces an ASN that parses without error but fails at the receiver's validator.
The 810 invoice follows a similar pattern for a different reason. Its BIG04 must contain the PO number exactly as it appeared in the 850 BEG03. Even a leading zero difference, a dash where the buyer's system used a space, or a truncated value causes the buyer's three-way match to fail. An 810 that does not match an open PO goes into an exceptions queue where it sits until someone manually reconciles it. In high-volume relationships, that hold translates directly into delayed payment.
Grocery UCS variants: 875, 880, and 852
Grocery distribution runs on a parallel set of transaction sets under the UCS (Uniform Communication Standard) dialect, which is the grocery-industry extension of ANSI X12. The 875 Grocery Products Purchase Order is the buyer-side equivalent of the 850, used by wholesale grocery distributors like UNFI and KeHE when ordering from suppliers. The 880 Grocery Products Invoice is the supplier's billing document, serving the same role as the 810. Both use G-series segments (G72 for order identification, similar to BEG; G78 for item identification, similar to PO1/IT1) that differ from the standard X12 segment names and element layouts.
The 852 Product Activity Report is a third grocery-specific document. It travels from the retailer or distributor back to the supplier and carries point-of-sale movement data: what sold, at what rate, what the current inventory is, and what the reorder quantity should be. Suppliers use 852 data to anticipate replenishment demand and reduce out-of-stocks. The EDI 875 Grocery Products PO Builder, EDI 880 Grocery Invoice Builder, and EDI 852 Product Activity Builder cover these formats. The X12 Segment Reference includes the G-series segments for UCS documents alongside the standard X12 set.
One practical note for suppliers who trade with both grocery wholesale and general retail buyers: the 875/880 world and the 850/810 world have different implementation guide ecosystems, different testing processes, and sometimes different VANs. A supplier onboarding to a new grocery distributor who already has a working retail EDI setup will still need to treat the grocery integration as a separate project. The envelope structure is the same, but the transaction content is different enough that the same mapping logic does not carry over.
The 997 functional acknowledgment: your receipt of record
The 997 is the simplest document in the supplier loop and the one most often underestimated. It is a formal acknowledgment from the receiver that a functional group arrived and could be parsed. It does not mean the business content was accepted, only that the document was syntactically readable. The 997 AK9 segment carries the overall result: A for accepted, R for rejected, E for accepted with errors. If the document was rejected, AK3 and AK4 segments drill down to the specific segment and element that failed.
You send 997s in response to every transmission your trading partners send to you, including 820 remittance documents and 850 purchase orders. Your trading partners send 997s in response to every 855, 856, and 810 you transmit. Monitoring those inbound 997s is the fastest way to detect a compliance problem before it becomes a chargeback. An R response from your buyer's translator means one of your documents failed before anyone reviewed the content. Without 997 monitoring, that failure is invisible until the buyer's accounts payable team calls about a missing invoice. The EDI 997 Functional Acknowledgment Builder generates valid acknowledgments for testing your inbound handling.
One habit worth building from the start: log every outbound control number and track which ones have received a 997. GS control numbers are typically sequential per trading partner per day. If a control number is missing from the acknowledgment log, you did not get a 997 for it. That gap is worth investigating before the payment cycle closes.
From a manual process to a working integration
The tools on this site cover the everyday cases: building and inspecting individual documents, checking segment structure, verifying envelope control numbers. They are the right starting point when you are learning a partner's spec, debugging a rejection, or building test files for certification. For the actual integration, the part where 850s land in your order management system automatically, 856s are generated from your WMS shipment confirmation, and 810s are produced from your invoicing system with the right PO cross-references, that is a different project.
I build these integrations for suppliers and distributors who need to look like a complete EDI shop to their retail buyers. The work covers inbound mapping (converting the buyer's 850 into whatever shape your order entry system expects), outbound mapping (generating a validator-clean 855, 856, and 810 from your system's native data), exception handling (what happens when an 850 has a product not in your item file, or an 820 references an invoice you cannot find), acknowledgment processing, and the glue to your transport layer (AS2, SFTP, VAN). See the EDI services page for what that work looks like in practice, or Ask James to describe your current setup and what a new trading partner is requiring.