Xero and Stedi integration

What moves between them

The main flow is Xero outbound into Stedi. When a purchase order or invoice is created or updated in Xero, ml-connector listens to the webhook, retrieves the full record via GET, and translates it into Stedi's JSON format for X12 EDI conversion. Xero contact records are synced to Stedi partnerships so that supplier and customer master data stays current. Xero payment records and bank transactions flow into Stedi's transaction tracking for reconciliation. The reverse flow is lighter: Stedi's inbound EDI acknowledgments (855, 865) and shipment notices (856) are parsed to JSON and can be written back to Xero as notes or linked to the original purchase order for tracking. All flows use Xero's OAuth2 bearer token refresh cycle and Stedi's static API Key.

How ml-connector handles it

ml-connector stores both credential sets encrypted and manages Xero's 30-minute token expiry by refreshing on each 401 response. It listens to Xero webhooks for PurchaseOrder, Invoice, Contact, and Payment CREATE and UPDATE events, fetches the full record, and enqueues a translation job. Each translation to Stedi includes an Idempotency-Key in the Authorization header to prevent accidental duplicate sends in the 24-hour deduplication window. Xero purchase orders map to Stedi's 850 PO, and invoices map to Stedi's 810 Invoice with line items, totals, and payment terms preserved. Contact names and addresses flow into Stedi partnerships to keep supplier and customer master data aligned. Xero's rate limit of 60 calls per minute per tenant requires backoff on 429 responses; ml-connector queues large batches and staggered retrieval. Xero's webhook metadata-only delivery requires a follow-up GET to the Accounting API, so two API calls per event are expected. Stedi's webhook endpoint timeout of 5 seconds means ml-connector must queue translations asynchronously rather than translating synchronously during webhook receipt. Tracking category mappings and custom fields are preserved in Stedi's mapping rules so cost allocation and project codes round-trip through EDI. File delivery status (success, failed) from Stedi is queried and updated back to Xero as an invoice or purchase order note.

A real-world example

A mid-sized manufacturing distributor runs Xero for accounting and needs to send purchase orders to suppliers via EDI (X12 850). Previously, a person exported POs from Xero each day, reformatted them in an Excel macro, and uploaded them to a third-party EDI service. With Xero and Stedi connected, each new PO in Xero automatically converts to X12, routes to suppliers over their preferred transport (SFTP for large vendors, AS2 for smaller ones), and a returned acknowledgment lands back in Xero as an attachment for month-end reconciliation. The team saves the daily manual reformat step and gains visibility into EDI delivery status without leaving the accounting system.

What you can do

• •Translate Xero purchase orders and invoices into X12 EDI (850 PO, 810 Invoice) and route them to trading partners via SFTP, FTPS, or AS2.
• •Sync Xero contacts to Stedi partnerships so supplier and customer master data stays current across both systems.
• •Receive inbound EDI acknowledgments (855 PO Acknowledgment, 865 Change Acknowledgment) and shipment notices (856 ASN) from Stedi, parse them to JSON, and attach them to the original Xero PO or invoice.
• •Manage Xero OAuth2 token expiry and refresh, Stedi API Key auth, and Idempotency-Key deduplication across all outbound EDI translations.
• •Track EDI file delivery status from Stedi and update Xero PO and invoice records with delivery confirmation, error logs, and reconciliation notes.

Questions

Which direction does data move between Xero and Stedi?

The main flow is Xero to Stedi. Purchase orders and invoices created in Xero are translated to X12 EDI and routed to trading partners. Contact records sync so supplier and customer master data stays aligned. Stedi inbound acknowledgments and shipment notices route back to Xero as notes and attachments on the original records. Xero is read-only for incoming EDI; ml-connector does not create new Xero invoices from inbound X12.

How does the integration handle Xero's webhook metadata and token expiry?

Xero webhooks include only the record ID, not the full payload, so ml-connector must fetch the complete record from the Xero Accounting API on each event. Xero access tokens expire every 30 minutes, and ml-connector refreshes them on a 401 response using the 60-day refresh token. Both operations are queued asynchronously to stay within Xero's 60 calls per minute rate limit per tenant.

What happens if Stedi's EDI translation fails or takes longer than the webhook timeout?

ml-connector does not wait for Stedi's EDI file execution during the Xero webhook receipt. Instead, it enqueues the translation asynchronously so the webhook returns within Stedi's 5-second requirement. Stedi retries webhook delivery up to 4 times over 90 seconds if a file fails to translate, and ml-connector queries Stedi's file execution status separately to update Xero with delivery confirmation or error details.