Flow Routes
Flow Routes are the automation engine of x12port. Once set up, inbound EDI documents are automatically
transformed and delivered to your system — no manual steps required.
ℹ️
Flow Routes are available to both Client and Developer accounts.
Go to Flow Routes in your navigation to manage them.
The big picture
Without Flow Routes, EDI is a two-step manual process: receive a document, then convert and forward it yourself.
With Flow Routes, those steps happen automatically the moment a document arrives.
📥
1. Partner sends EDI
Your trading partner POSTs an X12 document to your inbound URL.
🔍
2. x12port matches a route
x12port looks up the best-matching Flow Route for that partner and transaction type.
⇆
3. Document is transformed
Your saved mapping is applied — converting X12 to JSON, XML, CSV, or vice versa.
📤
4. Delivered to your endpoint
The converted output is POSTed to your configured endpoint (your ERP, WMS, webhook, etc.).
Before you create a Flow Route
You need three things ready first:
- A Trading Partner — the company sending the EDI. Add one at Trading Partners if you haven't already.
- A Saved Map — a mapping you built and saved in the Visual Mapping GUI. This tells x12port how to transform the document. (How to build a mapping)
- An Endpoint — the URL where x12port should POST the converted document. Add one at Endpoints.
💡
No map yet? Start with a Quick Template in the mapper — load a pre-built rule set for common transaction types (850, 856, 810) and tweak it for your partner's specific fields. It takes about 5 minutes.
Creating a Flow Route
- Go to Flow Routes and click + New Route.
- Give the route a descriptive name — e.g. "Walmart 850 → JSON → ERP".
- Select the Trading Partner this route applies to. You can also choose Any partner for a catch-all route.
- Select the Transaction Set (e.g. 850 — Purchase Order). Choose Any tx set for a wildcard.
- Select your Saved Map — the field mapping to apply when this document arrives.
- Select your Endpoint — where to POST the transformed output.
- Click Create Route. The route is active immediately.
Match priority — which route wins?
When a document arrives, x12port checks routes in this order and uses the first match:
| Priority | Partner | Tx Set | When to use |
|---|
| 1 — Exact | Specific partner | Specific tx set | Most common — one route per partner per document type |
| 2 — Partner wildcard | Specific partner | Any tx set | One partner, all their document types go the same place |
| 3 — Tx set wildcard | Any partner | Specific tx set | Same document type from any partner |
| 4 — Catch-all | Any partner | Any tx set | Fallback for anything not matched by a more specific route |
Only active routes are considered. You can pause a route at any time using the pause button (⏸) on the route card — useful for temporarily disabling a route during testing.
Flow Routes and Auto-997
Flow Routes and Auto-997 work together. If the trading partner has Auto-997 enabled
(toggle in the partner's Edit modal), x12port will:
- Receive the inbound document
- Match and execute the Flow Route (transform + dispatch)
- Automatically generate and send a 997 Functional Acknowledgment back to the partner
You don't need to do anything — the acknowledgment is handled for you.
See the 997 Ack Tracker to monitor acknowledgment status.
Editing and deleting routes
- Pause / Resume — use the ⏸ / ▶ button on the route card. No data is lost.
- Edit — click the pencil icon to update the partner, tx set, map, or endpoint.
- Delete — click the trash icon. This is permanent.
Monitoring deliveries
Every document processed by a Flow Route appears in the Transaction Feed with:
- Direction (inbound / outbound)
- Partner name and transaction set
- Timestamp and status
If a delivery fails (endpoint unreachable, HTTP error), the transaction is logged with an error status so you can investigate.
Frequently asked questions
Do I need a Flow Route for every trading partner?
No. One catch-all route (Any partner + Any tx set) handles everything. Add specific routes only when different partners or document types need different mappings or delivery destinations.
What happens if no route matches?
The document is still received and logged in the Transaction Feed — it's never lost. x12port just skips the automatic transform and dispatch. You can process it manually from the Transaction Feed.
Can I use the same map for multiple routes?
Yes. A saved map can be reused across as many Flow Routes as you like. If you update the map in the Visual Mapping GUI and save it under the same name, all routes using that map will automatically pick up the new version.
My endpoint returned an error — what do I do?
Check the Transaction Feed for the failed transaction and note the error message. Common causes: endpoint URL is wrong, the server is down, or authentication headers are missing. Fix the endpoint at Endpoints, then reprocess the document manually.