Xero and Orderful integration

What moves between them

Purchase orders and invoices originating in Xero flow into Orderful in two directions. Outbound: Xero POs and invoices are translated to X12 850 (purchase order) and 810 (invoice) documents and delivered via Orderful to your trading partners based on their ISA identifiers. Inbound: EDI acknowledgments (855), change acknowledgments (865), and invoice confirmations (810 inbound) from partners arrive at Orderful and are routed back to Xero as manual journal entries, purchase order attachments, or invoice line items depending on the document type. Outbound sync is triggered by Xero webhooks; inbound sync runs on a polling cadence (5-10 minute intervals) or via Orderful webhook push.

How ml-connector handles it

ml-connector securely stores both the Xero OAuth2 credentials (client ID and secret) and the Orderful API key, then obtains a fresh Xero access token every 25 minutes before expiry to avoid runtime failures. When a purchase order or invoice is created or updated in Xero, the webhook notifies ml-connector immediately, which fetches the full record, maps Xero accounts and line items to the trading partner's ISA identifiers and segment requirements, translates the data into valid X12 EDI format, and posts it to Orderful's /v4 create endpoint with the stream set to 'live' for production routing. When Orderful receives EDI documents from trading partners (via webhooks or polling), ml-connector translates them back to Xero line-item format and attaches them to the matching PO or invoice for audit and reconciliation. Xero's requirement that webhook payloads be followed up with a full GET request is handled automatically so the complete record is always available. ml-connector retries Orderful API calls that return transient errors (5xx, 429) with exponential backoff and logs every translation, delivery, and error to a searchable audit trail so failed documents can be debugged and replayed.

A real-world example

A mid-sized distributor runs Xero for accounting and orders inventory from suppliers and sells it to customer accounts. Previously, the supply-chain team exported purchase orders from Xero as CSV each morning, converted them to X12 850 documents by hand, and uploaded them to Orderful, then waited for supplier acknowledgments (855) to trickle back and manually reconciled them against Xero POs to confirm what was ordered versus what was accepted. With Xero and Orderful connected, each Xero PO is automatically translated to X12 and routed to the supplier's EDI inbox within seconds. Supplier acknowledgments flow back into Xero automatically and are attached to the original PO, so the team can see at a glance which orders were confirmed, which were partially accepted, and which had issues, all without re-keying or manual reconciliation.

What you can do

• •Translate Xero purchase orders into X12 850 documents and deliver them to Orderful for routing to suppliers based on their EDI ISA identifiers.
• •Send Xero invoices as X12 810 invoices to Orderful for delivery to your customers or trading partners.
• •Receive supplier and customer EDI documents (855 acknowledgments, 865 change acknowledgments, 810 inbound invoices) from Orderful and attach them to matching Xero purchase orders and invoices for audit and reconciliation.
• •Authenticate Xero with OAuth2 and maintain token freshness before expiry, and Orderful with the static API key, both stored encrypted.
• •Translate EDI documents bidirectionally between Xero line-item format and X12 segments, with automatic retry and a full searchable audit trail on every document.

Questions

How does ml-connector know which trading partner to send a Xero purchase order to in Orderful?

Xero purchase orders include supplier contact records that you map to Orderful ISA identifiers (sender and receiver codes) during setup. When a PO is created in Xero, ml-connector looks up the supplier, finds the corresponding ISA pair, and includes those identifiers in the X12 850 document posted to Orderful so the right supplier receives the right order.

What happens if a translation to X12 fails or an Orderful API call times out?

ml-connector logs the error with full context (the original Xero record, the partial translation, the API response) to a searchable audit trail. You can review the error, fix the underlying cause (e.g., a missing ISA mapping), and replay the document from the audit log without re-creating it in Xero. Transient errors (5xx, 429) are retried automatically with exponential backoff.

Can ml-connector send both purchase orders and invoices to the same trading partner?

Yes. Xero purchase orders translate to X12 850 documents, and Xero invoices (or bills) translate to X12 810 documents. Both use the same ISA identifiers, so the same trading partner can receive both types of documents routed through Orderful.