FreshBooks and Tipalti integration

What moves between them

Bills and bill_vendors flow from FreshBooks into Tipalti. When a bill is created or updated in FreshBooks, ml-connector pushes the bill details and its bill_vendor into Tipalti as an invoice and payee (if new). Bill status changes and payment records flow from FreshBooks webhooks into Tipalti payment batches and payment status updates. Chart of accounts from FreshBooks is mapped to Tipalti GL accounts so bill line items allocate to the correct cost centers. Payments created in Tipalti are reflected back in FreshBooks bill_payments so the bill status stays synchronized. The sync runs in near-real-time via FreshBooks webhooks, with scheduled polling as a fallback for any webhook delivery lag.

How ml-connector handles it

ml-connector stores both the FreshBooks OAuth token and Tipalti API credentials (payer_name and api_key for SOAP, or client credentials for REST) encrypted at rest. It authenticates to FreshBooks using the stored OAuth token and listens for bill.create, bill.update, bill_vendor.create, and bill_vendor.update webhook events. For each webhook event, it transforms the FreshBooks bill and bill_vendor data into Tipalti Invoices and Payees using the payee's tax code and custom fields to preserve compliance metadata. It routes SOAP calls (Payee creation and Invoice submission) through the SOAP endpoint with HMAC-SHA256 signing and REST calls (GL mapping queries) through the REST endpoint with OAuth 2.0. Tipalti's single IPN endpoint receives all event types; ml-connector filters by event type and maps payee_details_changed back to FreshBooks bill_vendor updates, and payment_submitted back to FreshBooks bill_payments. Failed webhook deliveries are retried with exponential backoff, and the full audit trail allows any record to be replayed if a downstream write fails. FreshBooks status fields are read-only, so ml-connector never writes invoice status back to FreshBooks - only payment records.

A real-world example

A mid-sized services company uses FreshBooks to track client invoicing and vendor bills across three divisions. They receive hundreds of supplier invoices weekly in FreshBooks and previously exported bill reports, uploaded them manually to Tipalti, and spent hours chasing discrepancies when payees went out of compliance or payment status diverged between systems. With FreshBooks and Tipalti connected, each bill received in FreshBooks automatically flows into Tipalti with the correct payee and GL account, and the company's accounts payable team can focus on approval and payment strategy rather than data entry. Vendor compliance documents stay synchronized, payment status is always current in FreshBooks, and month-end reconciliation is simplified because bills and payments align across both systems.

What you can do

• •Sync FreshBooks bills and bill_vendors into Tipalti invoices and payees, preserving bill amounts and vendor details.
• •Map FreshBooks chart of accounts to Tipalti GL accounts so bills allocate to the correct cost centers and expense categories.
• •Authenticate FreshBooks via OAuth 2.0 delegation and Tipalti via HMAC-SHA256 (SOAP) and OAuth 2.0 (REST), handling both API families.
• •Receive FreshBooks bill and payment webhooks in real time, verify signatures using HMAC-SHA256, and sync changes into Tipalti payment batches and payee records.
• •Maintain a full audit trail and replay failed syncs so every bill reaches Tipalti even if a webhook is delayed or a network call times out.

Questions

Which direction do bills flow between FreshBooks and Tipalti?

Bills flow from FreshBooks into Tipalti. When you create or update a bill in FreshBooks, ml-connector syncs it to Tipalti as an invoice assigned to the matching payee. Payment records flow back from Tipalti into FreshBooks so your bill status stays synchronized. Chart of accounts and GL mapping go both directions.

Does ml-connector handle both SOAP and REST for Tipalti?

Yes. ml-connector uses SOAP endpoints for payee and invoice operations (with HMAC-SHA256 signature auth) and REST endpoints for GL account queries and custom field operations (with OAuth 2.0). It routes each call to the correct endpoint and uses the correct authentication scheme for that family.

What happens if a FreshBooks webhook is delayed or times out?

ml-connector retries failed webhook deliveries with exponential backoff. It also maintains a full audit trail of every sync attempt, so you can replay any bill if a downstream call to Tipalti fails. This ensures no bill is lost even if delivery takes several minutes.