FreshBooks and Stedi integration

What moves between them

The main flow runs from FreshBooks into Stedi. When an invoice is created or updated in FreshBooks, ml-connector receives the webhook event, translates the FreshBooks invoice to a Stedi X12 810 purchase order, and posts it to Stedi for routing to the matching trading partner via SFTP or AS2. The reverse flow brings inbound purchase orders from Stedi (received via Stedi webhook as parsed JSON from inbound X12 850) into FreshBooks as bill records tied to the matching vendor. Chart of accounts and vendor/client data are aligned so that EDI transactions reference valid FreshBooks dimensions. Each write to Stedi includes an Idempotency-Key to prevent duplicate EDI files if a request is retried.

How ml-connector handles it

ml-connector stores the FreshBooks OAuth token encrypted and exchanges it periodically to stay authorized. For Stedi, it stores the API Key encrypted and includes it on every request. When FreshBooks webhooks arrive, ml-connector parses the HMAC-SHA256 signature to verify authenticity, then translates the FreshBooks invoice or bill into the matching X12 format (810 for outbound invoices, 850 for inbound POs). Before writing to Stedi, ml-connector maps the FreshBooks client or vendor to the Stedi Partnership and verifies the trading partner route exists. Every POST to Stedi includes a unique Idempotency-Key header for 24-hour deduplication so concurrent webhook retries do not create duplicate EDI files. When Stedi webhooks arrive with inbound transactions, ml-connector parses the X12 back to JSON, matches the sender to a FreshBooks bill vendor, and creates or updates the bill record. If a FreshBooks webhook fails, ml-connector retries with exponential backoff. If a Stedi request times out (Stedi enforces 5-second timeouts on webhook endpoints), ml-connector backs off and retries, and Stedi's own retry policy handles failures on the Stedi side. Every transaction is logged with full context so replays are possible if needed.

A real-world example

A small wholesale distributor uses FreshBooks for invoicing and accounts payable, and sells to three large retailers who each require orders and invoices to arrive via EDI X12 format. Before the integration, the finance team created each invoice in FreshBooks, then manually exported the data and re-entered it into a separate EDI platform to route X12 files to the retailers, a process that introduced errors and took 30 minutes per day. Inbound purchase orders from the retailers arrived as EDI files that the team had to download, parse, and manually key into FreshBooks as purchase records. With FreshBooks and Stedi connected, each new FreshBooks invoice automatically routes to the matching retailer as an X12 810 file, and inbound EDI purchase orders from the retailers flow back into FreshBooks as bills, eliminating the re-keying step and the separate EDI platform fee.

What you can do

• •Automatically translate FreshBooks invoices to X12 810 EDI format and send them to trading partners via Stedi.
• •Receive inbound X12 purchase orders from trading partners via Stedi and create bills in FreshBooks.
• •Map FreshBooks clients and vendors to Stedi trading partners and validate routing before each transmission.
• •Use Idempotency-Key deduplication to prevent duplicate EDI files when webhooks are retried.
• •Maintain a full audit trail of every invoice and EDI transaction, with the ability to replay failed records.

Questions

What data moves from FreshBooks to Stedi?

FreshBooks invoices are translated to X12 810 EDI format and sent to Stedi for routing to trading partners via SFTP or AS2. FreshBooks bills are translated to X12 850 purchase orders if they represent vendor orders. Client and vendor records are mapped to Stedi trading partners so that each EDI transaction reaches the correct recipient.

How does ml-connector handle Stedi's Idempotency-Key requirement and webhook timeouts?

Every request to Stedi includes a unique Idempotency-Key header to deduplicate writes within 24 hours, so retries do not create duplicate EDI files. Because Stedi enforces a 5-second timeout on webhook endpoints, ml-connector responds within that window and processes EDI transactions asynchronously in a background worker.

What happens to inbound EDI from trading partners?

Stedi parses inbound X12 files and publishes them as webhooks (transaction.processed.v2). ml-connector receives the parsed JSON, matches the sender to a FreshBooks bill vendor, and creates or updates a bill record. This eliminates the manual step of downloading and parsing EDI files.