Retail EDI Parser
Retail EDI Parser is an open-source Python library with no external dependencies. It detects the transaction type, extracts the fields that matter and returns clean JSON your systems and AI workflows can use.
- Python
A Python library that reads X12 retail EDI transactions and returns structured, readable data for orders, shipments, invoices and payments.
- Python 3.9 or higher
- ANSI X12 EDI
- JSON
- Python standard library only
- No external dependencies
The challenge
Retail and supply chain partners still exchange purchase orders, ship notices, invoices and remittances as X12 EDI files. The format is compact and strict, and it is hard for people and for newer systems to read directly.
Teams end up writing one-off parsers for each partner and each document type. The results differ from file to file, which makes the data hard to validate, hard to route and hard to hand to analytics or AI steps with confidence.
What it does
Transaction auto-detection
Reads the envelope and transaction header to identify the X12 transaction type, so one entry point handles purchase orders, ship notices, invoices and other retail documents.
Eighteen transaction types
Covers common retail documents including purchase orders, acknowledgments, ship notices, invoices, adjustments, remittances, catalogs, inventory advice, order status and functional acknowledgments.
Delimiter detection
Reads the interchange header to find the element, component and segment separators in use, so compliant files with different delimiters parse without configuration.
Structured output
Returns a result object with the envelope, parsed summary, raw segments, errors and warnings, and can serialize everything to JSON for downstream systems.
Helper accessors
Shortcut methods return line items, trading parties and totals directly, so common reads do not need knowledge of the nested structure for each transaction.
Reference lookups
Ships lookup tables that turn codes such as entity roles, units of measure, product identifier types and acknowledgment codes into readable names.
How it works
Pass in raw X12
Give the parser the raw EDI text as a string. No file format conversion or configuration is needed before parsing starts.
Detect and split
The parser reads the interchange header to find the delimiters, splits the file into segments and identifies the transaction type.
Parse by type
A parser specific to that transaction type reads the segments and builds fields, party details, line items and totals into a dictionary.
Use the result
Read the summary, call the helper methods, check errors and warnings, or export the full result as JSON for the next system.
Under the hood
- Language
- Python 3.9 or higher
- Standards
- ANSI X12 EDI
- JSON
- Libraries
- Python standard library only
- No external dependencies
- Packaging
- Single module file
- pyproject metadata
Inside the harness
Data transfer
EDI files arrive over governed channels. The parser turns them into structured data after transfer, so downstream steps work with validated fields rather than raw files.
Guardrails
Parse results carry errors and warnings, which lets a workflow stop or route a malformed file before an AI step or a business system acts on it.
Audit
Raw segments are kept in the result next to the parsed fields, so any extracted value can be traced back to the original EDI line.
Policy
Rules can run on the structured output, such as which trading partners and transaction types are accepted, before data moves further in a governed setup.
Business outcome
One reader for many documents. Teams stop maintaining separate parsers per document type and work with one consistent interface and one output shape.
Data ready for downstream use. Orders, shipments, invoices and payments become plain structures that analytics, integration and AI workflows can use without EDI knowledge.
Easier checking and tracing. Errors, warnings and retained raw segments make it simpler to review a questionable file and explain where a value came from.
Low adoption effort. With no external dependencies, the library can be reviewed, vendored and tested inside a team's own environment.
Where it is used
- Reading inbound purchase orders from retail partners and turning them into order records for an internal system.
- Converting ship notices into shipment, pallet and item details for warehouse and logistics tracking.
- Matching invoices and remittance advice to orders as part of an accounts payable or reconciliation workflow.
- Preparing EDI documents as structured input for analytics or AI-assisted exception handling in a governed pipeline.
Frequently asked questions
How do I use it?
The README describes three routes: copy the single module into your project, clone the repository, or install it as a package if one is published. Then create the parser and call parse on the EDI text.
Which transactions does it support?
The README lists eighteen X12 transactions: 810, 812, 820, 830, 832, 840, 843, 846, 850, 855, 856, 860, 861, 867, 869, 870, 997 and 999. Check your partner files against your own samples.
What licence is it under?
The README and package metadata state the MIT licence. The repository does not contain a separate licence file, so confirm the terms with the maintainers before relying on it in a product.
Is it production-ready?
Treat it as a starting point to review. The repository does not provide a test suite, so validate it against your own partner files and implementation guides before using it for live business traffic.
Using this in a governed AI setup?
Talk to us about running it inside the harness, with policy, guardrails and audit around it.