QuickBooks Online and Stedi integration

What moves between them

Outbound bills and invoices from QuickBooks Online are translated to Stedi's JSON representation, then transformed into X12 810 invoice EDI format and routed to your trading partners via SFTP or AS2 based on each partner's configuration. Inbound 850 purchase orders and 856 advance shipment notices from trading partners are received by Stedi, parsed from X12 EDI into JSON, and pushed via webhook to ml-connector, which creates or updates purchase orders and line items in QuickBooks Online. The sync is one-way for outbound invoices and one-way inbound for PO acknowledgments, on whatever schedule your trading partners and Stedi connectivity enforce.

How ml-connector handles it

ml-connector stores the Stedi API key encrypted and presents it on every request to Stedi's REST API. For QuickBooks Online, it manages the OAuth token pair: detecting when the access token expires and requesting a new one with the refresh token, and detecting when the refresh token is about to rotate so it captures the new token before the old one is revoked. On the outbound side, ml-connector reads bills and invoices from QuickBooks Online via polling (since QBO publishes only the operation and entity ID in webhooks), maps them to Stedi's JSON schema for the appropriate EDI document type (usually 810 for invoices), and posts them with a unique Idempotency-Key header so Stedi deduplicates retries. On the inbound side, ml-connector receives Stedi's webhook callbacks for transaction.processed.v2 events (inbound EDI that Stedi has already parsed to JSON), maps the EDI segments to QuickBooks Online bill fields, and creates purchase orders and line items with full audit trails. ml-connector tracks the Stedi webhook timeout strictly (5-second response window) to prevent Stedi from retrying due to a slow reply.

A real-world example

A small-to-mid-market distributor uses QuickBooks Online for accounting and has trading partners who send and receive EDI documents. Before the integration, the company manually exported invoices from QuickBooks Online, converted them to X12 810 files in Stedi, and then sent them to partners. Inbound 850 purchase orders from partners were received in Stedi, converted by hand to a spreadsheet, and then re-entered into QuickBooks Online as bills. With QuickBooks Online and Stedi connected, each new invoice flows automatically from QuickBooks Online to Stedi and out to the partner as EDI, and each inbound purchase order from a partner flows through Stedi back into QuickBooks Online as a bill, eliminating both the manual export step and the re-entry work.

What you can do

• •Translate QuickBooks Online invoices and bills into X12 810 EDI format and route them to trading partners via Stedi.
• •Create purchase orders and line items in QuickBooks Online from inbound X12 850 and 856 EDI documents processed by Stedi.
• •Manage OAuth token refresh for QuickBooks Online, including rotation of long-lived refresh tokens before they expire.
• •Present the Stedi API key on every request and deduplicate outbound writes with Idempotency-Key headers.
• •Maintain complete audit trails for every document translation and maintain strict 5-second webhook response times to Stedi.

Questions

How does the integration handle QuickBooks Online's OAuth token refresh?

ml-connector detects when the QuickBooks Online access token is about to expire and uses the refresh token to request a new pair. Because QuickBooks Online rotates refresh tokens every 24 to 26 hours, ml-connector watches for the rotation event in responses and captures the new refresh token before the old one is revoked, so the authorization chain never breaks.

Does the integration work with both outbound and inbound EDI?

Yes. Outbound bills and invoices from QuickBooks Online are translated to X12 EDI and routed to your trading partners via Stedi. Inbound purchase orders and advance shipment notices from trading partners are received by Stedi, parsed into JSON, and pushed to ml-connector, which creates purchase orders in QuickBooks Online. The two directions are independent, so you can enable one or both.

Why does the integration track Stedi's 5-second webhook response time?

Stedi imposes a strict 5-second timeout on all webhook callbacks. If ml-connector does not respond within that window, Stedi retries up to 4 times at 90-second intervals. ml-connector is designed to validate and queue the inbound EDI transaction immediately, then process it asynchronously, so it always responds to Stedi within the window.