FreshBooks and Orderful integration

What moves between them

The main flow runs from FreshBooks to Orderful. When an invoice is created or updated in FreshBooks, ml-connector receives the webhook event, extracts the invoice detail including client, line items, amounts, and due date, translates it into an EDI 810 invoice document, and creates it in Orderful with the correct ISA identifiers and stream mode. The reverse is possible: if trading partners send 855 purchase order acknowledgments back through Orderful, ml-connector can retrieve them via polling and map them back to FreshBooks for reconciliation.

How ml-connector handles it

ml-connector validates every FreshBooks webhook signature using the HMAC-SHA256 header to ensure authenticity. On receipt of an invoice event, it calls FreshBooks to fetch the full invoice detail including line items, client information, and GL posting (if any), then constructs an EDI 810 document with the client's ISA identifiers (which you configure per FreshBooks client) and the stream field matching your environment. It then POSTs the transaction to Orderful with your API key. If Orderful returns an error or the request times out, ml-connector retries with exponential backoff. For inbound documents from trading partners, ml-connector polls Orderful for new acknowledgments and status updates, maps them back to the original FreshBooks invoice for audit and reconciliation, and stores the full EDI payload for traceability.

A real-world example

A small manufacturing distributor uses FreshBooks for accounting and invoices its direct customers. Some of those customers are large retailers that require invoices in EDI 810 format delivered via their EDI network. Before the integration, accounting exported invoices from FreshBooks every day, manually translated them to EDI using a third-party tool, and uploaded them to an EDI VAN or sent them as SFTP. With FreshBooks and Orderful connected, each invoice created in FreshBooks triggers an automatic EDI 810 generation and delivery, the trading partner's acknowledgment flows back into Orderful for status tracking, and the accounting team spends no time on translation or re-keying.

What you can do

• •Automatically create EDI 810 invoices in Orderful when invoices are created or updated in FreshBooks.
• •Map FreshBooks client records to EDI ISA identifiers so each invoice routes to the correct trading partner.
• •Validate FreshBooks webhook signatures with HMAC-SHA256 to ensure authenticity.
• •Poll Orderful for inbound EDI 855 acknowledgments and map them back to FreshBooks invoices for reconciliation.
• •Support both test and live stream modes in Orderful, configurable per customer and environment.

Questions

How does the integration handle FreshBooks' OAuth 2.0 user-delegated authentication?

ml-connector stores your FreshBooks OAuth tokens encrypted and refreshes them when they expire. Since FreshBooks only supports user-delegated grants (not Client Credentials), you authorize once during setup, and ml-connector maintains the session on your behalf so webhooks can be received and data can be fetched when needed.

What happens if a FreshBooks webhook delivery fails or times out?

FreshBooks webhooks have a 10-second timeout. If a webhook times out or returns a non-2xx status, FreshBooks retries it; after persistent failures, FreshBooks disables the callback. ml-connector confirms receipt with a 200 status so FreshBooks marks the delivery healthy and continues sending.

How are FreshBooks clients mapped to Orderful ISA identifiers?

You configure each FreshBooks client with its EDI trading partner ISA identifiers (sender and receiver) during setup. When ml-connector creates an EDI 810 in Orderful, it pulls those identifiers from the client record so the invoice routes to the correct partner network. The stream field is set to test during development and live in production.