Sage X3 and Orderful integration

What moves between them

The main flow is outbound from Sage X3 to Orderful. Purchase orders and sales invoices created or modified in Sage X3 are polled every 15 minutes, translated into EDI X12 format (850 for purchase orders, 810 for invoices), and posted to Orderful for routing to trading partners. Inbound EDI documents received by Orderful (such as 810 invoices from suppliers and 856 ship notices) are retrieved via polling, translated into Sage X3 purchase order acknowledgments and supplier invoices, and posted to the appropriate GL accounts. All mappings between Sage X3 product codes and supplier IDs and the ISA identifiers required by Orderful happen once during setup and reused on every sync.

How ml-connector handles it

ml-connector stores the Sage X3 server URL, folder name, and either Basic Auth credentials or OAuth2 client ID and secret encrypted. It polls Sage X3 on a 15-minute schedule using the GraphQL (Xtrem) endpoint if available (V12+) or the REST api1 endpoint for older instances, filtering on updatedDate to pick up only changed records. It tracks the 5-minute Sage X3 token expiry and refreshes proactively. For Orderful, ml-connector stores the API key encrypted and creates outbound EDI documents with the correct ISA identifiers, sender and receiver codes, and the stream field set per environment. It posts 850 purchase orders and 810 invoices to Orderful's /v4 create endpoint. For inbound, ml-connector polls /v3/polling-buckets every 10 minutes for 810 supplier invoices, 820 payment remittances, and 856 ship notices, translates them back into Sage X3 document types, and posts them to the GL accounts and cost centers mapped during setup. Every record is tracked with a job ID so a failed EDI transmission or GL posting can be replayed without duplicate entries.

A real-world example

A mid-sized food distributor runs Sage X3 for procurement and inventory and sends purchase orders to 30+ regional suppliers. Before the integration, procurement staff manually entered each purchase order into a separate EDI translation tool, then emailed or uploaded the X12 file to each supplier's portal. Supplier invoices came back as EDI files and had to be manually translated and keyed into Sage X3, creating invoice matching delays and GL reconciliation work. With Sage X3 and Orderful connected, each purchase order flows from Sage X3 to Orderful instantly, is translated to X12, and is routed to the supplier's preferred channel (AS2, SFTP, or email). Inbound supplier invoices are automatically translated back into Sage X3, matched to the original PO, and posted to GL. The procurement team saves 5 hours per week on translation and manual entry, and month-end close is faster because AP aging is accurate.

What you can do

• •Poll Sage X3 purchase orders and sales invoices on a schedule, translate them to X12 EDI format, and post them to Orderful for delivery to trading partners.
• •Retrieve inbound EDI invoices and ship notices from Orderful, translate them into Sage X3 documents, and post them to GL accounts with full audit trails.
• •Manage the Sage X3 OAuth2 token lifecycle, refresh proactively before expiry, and handle both GraphQL (Xtrem) and legacy REST api1 endpoints.
• •Map Sage X3 supplier IDs, product codes, and cost centers to Orderful ISA identifiers and trading partner codes so EDI routing is accurate.
• •Replay failed EDI transmissions and GL postings using job IDs, with no duplicate entries or orphaned records.

Questions

Which direction does data flow between Sage X3 and Orderful?

The main flow is outbound from Sage X3 to Orderful. Purchase orders and invoices in Sage X3 are translated to EDI and posted to Orderful for routing to suppliers. Inbound EDI documents from suppliers (invoices, ship notices, remittances) are retrieved from Orderful, translated back into Sage X3 documents, and posted to GL. Reference data such as supplier IDs and cost centers are mapped in both directions during setup.

Does ml-connector handle the Sage X3 OAuth2 token refresh and API version differences?

Yes. ml-connector tracks the 5-minute Sage X3 access token expiry and refreshes proactively using the 30-day refresh token. It supports both the GraphQL (Xtrem) endpoint for V12+ and the legacy REST api1 endpoint for older Sage X3 instances, auto-detecting which is available on your server. It handles the customer-specific server URL and folder path so no tenant registry is needed.

What happens if an EDI translation or GL posting fails in Orderful?

Every EDI document and GL posting is assigned a job ID for deduplication. If a translation fails or a GL post to Sage X3 does not succeed, ml-connector logs the failure, stores the record encrypted, and replays it without creating duplicate entries. A full audit trail is kept for every transaction, so failed records can be inspected and replayed manually if needed.