FreshBooks and AvidXchange integration

What moves between them

The outbound flow runs from FreshBooks into AvidXchange. Bill vendors are pushed first so payments route correctly, then AP bills with their line items and GL coding are submitted as batches for approval and payment. The FreshBooks chart of accounts is also pushed across so AP staff can code invoices to valid accounts. The inbound flow runs the other way: ml-connector polls AvidXchange for settled payment records, including check number, ACH trace, or virtual card detail, and writes them back into FreshBooks as bill payments against the matching bill. GL accounts are read-only in AvidXchange, so financial coding is never written back into FreshBooks. Cadence follows your AP schedule, typically every 15 to 30 minutes for payment status.

How ml-connector handles it

ml-connector stores both credential sets encrypted, refreshes the FreshBooks OAuth token when a call returns 401, and saves the rotated refresh token each time since FreshBooks allows only one active refresh token per user. It records the FreshBooks account ID and business ID per customer and presents the AvidSuite company and user tokens on every AvidConnect request. Vendors sync first because a missing vendor in AvidXchange means a payment failure, and FreshBooks vendor IDs and GL accounts are mapped to the values AvidXchange expects. FreshBooks has no purchase orders, so two-way and three-way PO matching in AvidXchange is left unused and bills are submitted on their own. Because neither side offers reliable webhooks for this flow, ml-connector polls: FreshBooks on offset pages of 100, AvidXchange on a fixed interval for payment status. Supplying your own bill number keeps creates idempotent and avoids 409 conflicts, throttling returns HTTP 429 and is retried with backoff, and FreshBooks soft-deletes are read from the vis_state flag rather than HTTP DELETE.

A real-world example

A 60-person property maintenance firm runs FreshBooks for its books and pays a long list of subcontractors and material suppliers every month. Before the integration, a bookkeeper entered each vendor bill in FreshBooks, then manually keyed the same bills into AvidXchange for approval routing and payment, and afterward typed the check and ACH details back into FreshBooks once AvidPay had paid. With FreshBooks and AvidXchange connected, approved bills flow into AvidXchange for payment automatically, settled payment detail returns to FreshBooks the same day, and the duplicate entry and the after-the-fact reconciliation both disappear.

What you can do

• •Push FreshBooks bill vendors into AvidXchange before bills so payments route to the right payee.
• •Submit FreshBooks AP bills with line items and GL coding into AvidXchange for approval and payment.
• •Send the FreshBooks chart of accounts to AvidXchange so AP staff code invoices to valid accounts.
• •Write settled check, ACH, and virtual card detail from AvidXchange back into FreshBooks as bill payments.
• •Bridge FreshBooks OAuth refresh tokens and AvidSuite token auth, polling on a schedule with retries and a full audit trail.

Questions

Which direction does data move between FreshBooks and AvidXchange?

Vendors, AP bills, and GL codes move from FreshBooks into AvidXchange so invoices can be coded, approved, and paid. Settled payment detail moves the other way, from AvidXchange back into FreshBooks as bill payments. GL accounts are read-only in AvidXchange, so coding is never written back into FreshBooks.

Does AvidXchange send webhooks when a payment is made?

No. AvidXchange has no public webhook system, so ml-connector polls the payment data on a schedule, typically every 15 to 30 minutes, to detect newly settled payments. Once AvidPay executes a payment, the check number, ACH trace, or virtual card detail is read back and written into FreshBooks against the matching bill.

FreshBooks has no purchase orders, so how are bills handled?

Bills are submitted to AvidXchange on their own, without a PO reference. AvidXchange supports two-way and three-way PO matching for systems that have purchase orders, but since FreshBooks does not, that matching is left unused. Each bill is still tied to a vendor, so ml-connector syncs the vendor first and then submits the bill for approval and payment.