How to Read a Trading Partner EDI Specification Document

Every retailer publishes an EDI specification document. Walmart’s is hundreds of pages. Target’s is formatted differently than Home Depot’s. Some are clean PDFs; some are Excel files with notes in random cells. Here’s how to work through them efficiently.

What a Spec Document Actually Is

A trading partner spec is their interpretation of the X12 standard for a specific transaction. X12 gives you the full grammar — hundreds of possible segments, thousands of possible elements. A trading partner spec tells you:

• Which segments they use
• Which are mandatory vs. optional
• What values they expect in each element
• Any retailer-specific requirements that deviate from the X12 standard

The spec is not the X12 standard itself. It’s a subset, with retailer-specific rules layered on top.

The Structure of a Spec Document

Most specs are organized by segment, in the order they appear in the transaction:

1. Transaction overview — what the transaction is, when to send it, timing requirements
2. Segment table — a table listing every segment with usage indicator (M = mandatory, O = optional, C = conditional) and max use count
3. Segment detail — for each segment, the individual data elements with their own usage indicators, valid values, and notes
4. Appendices — code lists, qualifier tables, sample transactions

Start with the segment table to understand the overall structure. Then go to segment detail for the elements you’ll actually map.

Usage Indicators to Know

• M (Mandatory) — must be present or the transaction will fail
• O (Optional) — can be omitted without failing
• C (Conditional) — required when another element or segment is present; the condition is stated in the notes
• X (Not Used) — the retailer explicitly does not want this segment or element

Pay careful attention to C elements. They’re the ones that bite you when your test transactions fail and you can’t figure out why.

Finding the Qualifiers

Almost every segment uses qualifier codes — two-character codes that tell you what type of data is in the adjacent element. The spec will have a valid values column or an appendix listing accepted qualifier codes.

For example, in a DTM segment:

• 010 = Requested Ship Date
• 038 = Ship Not Before
• 017 = Cancel After

Use the wrong qualifier and the receiving system either ignores the date or rejects the transaction. Always cross-reference the qualifier tables.

What’s Often Missing from Specs

Spec documents describe the format. They don’t always tell you:

• How the data maps to the retailer’s internal systems — a PO number might need a specific format the spec doesn’t mention
• What triggers a chargeback — the compliance and routing guides are separate documents
• Undocumented requirements — some retailers have legacy requirements that never made it into the current spec
• Testing quirks — the certification portal sometimes behaves differently than the production system

This is why someone who has done a specific retailer’s EDI before is valuable. The undocumented requirements are real, and learning them by trial and error in a certification window is expensive.

Working Through a New Spec Efficiently

1. Read the overview first — understand what the transaction does and the business context
2. Find the segment table — identify all mandatory segments and write them down
3. Note the conditional segments — understand what conditions trigger them
4. Build a mapping worksheet — left column is the EDI element, right column is where it comes from in your system
5. Identify the unknowns — elements you don’t have data for yet; flag them before you start building
6. Get a sample transaction — some specs include examples; if not, ask the trading partner for one

A sample transaction is worth more than ten pages of spec. It shows you the real values in context.

When the Spec Conflicts with Reality

This happens. The spec says an element is optional; the trading partner rejects your transaction because it’s missing. The spec shows a qualifier value; the partner’s system doesn’t recognize it.

When you hit a conflict, go to the trading partner’s EDI support team first. They usually know the real requirements and can tell you what the spec got wrong.

If you’re working through a new spec and getting stuck, TebcoForge can review your mapping or handle the build entirely. We’ve read enough spec documents to know what to look for and what to ignore.