FreshBooks and Basware integration

What moves between them

Master data moves from FreshBooks into Basware. ml-connector reads FreshBooks bill vendors and chart-of-accounts records and imports them into Basware as vendors and GL accounts so the coding panel only offers valid options. Approved supplier invoices move the other way: ml-connector reads Basware AccountingDocuments that are coded and approved, then creates AP bills in FreshBooks against the matching vendor, with line and coding detail mapped to FreshBooks fields. When a bill is later paid in FreshBooks, ml-connector confirms the payment back to Basware. Master data syncs on a schedule, while approved invoices can be triggered by a Basware webhook or polled.

How ml-connector handles it

ml-connector stores both credential sets encrypted and bridges two different OAuth flows: it requests a fresh FreshBooks authorization-code token when a call returns 401 and reuses the stored refresh token, while requesting a new Basware client-credentials token before the one-hour expiry. It selects the correct Basware regional base URL from the customer setting and reads the FreshBooks accountId from the identity endpoint so accounting paths resolve. Each Basware AccountingDocument maps to a FreshBooks bill, and because a FreshBooks bill always requires a vendorid, the vendor is created or matched first. Two real edge cases are handled directly: Basware silently skips an unchanged import, so the connector changes a tracked field when a record genuinely needs to reprocess, and FreshBooks deletes are soft deletes via vis_state rather than HTTP DELETE. Rate-limit responses on either side trigger exponential backoff, and every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A 40-person specialty engineering firm keeps its books in FreshBooks but receives a growing pile of supplier invoices that two staff code and approve by email before re-typing each one into FreshBooks as a bill. They adopt Basware to capture and route invoices, but without a link the vendor list and GL accounts drift between the two systems and approved invoices still get re-keyed by hand. With FreshBooks and Basware connected, the FreshBooks vendor and chart-of-accounts data feeds the Basware coding panel, and each approved invoice lands in FreshBooks as a bill against the right vendor. The re-keying step disappears and the two systems stop disagreeing on who the active vendors are.

What you can do

• •Import FreshBooks bill vendors and chart-of-accounts records into Basware so invoice coding uses valid accounts.
• •Read coded and approved Basware AccountingDocuments and create matching AP bills in FreshBooks.
• •Confirm payment back to Basware once a bill is marked paid in FreshBooks.
• •Bridge the FreshBooks user-delegated token and the Basware client-credentials token, and select the correct regional URL.
• •Run on a schedule or a Basware webhook, with backoff, retries, and a full audit trail on every record.

Questions

Which direction does data move between FreshBooks and Basware?

Vendors and GL accounts move from FreshBooks into Basware so the coding panel has valid options. Approved supplier invoices move from Basware into FreshBooks as AP bills against the matching vendor. When a bill is paid in FreshBooks, ml-connector confirms that payment back to Basware, since Basware does not initiate payments itself.

How does the integration handle the two different sign-in methods?

FreshBooks uses an OAuth 2.0 authorization-code token tied to a specific user, while Basware uses OAuth 2.0 client credentials with tokens that expire after about an hour. ml-connector stores both sets encrypted, refreshes the FreshBooks token on a 401 using the stored refresh token, and requests a new Basware token before expiry. It also selects the correct Basware regional base URL for the customer.

Why might an invoice not reprocess when I expect it to?

Basware applies delta filtering and silently skips records that are identical to the last version it received, so a re-sent but unchanged record is not an error and is not reprocessed. ml-connector changes a tracked field when a record genuinely needs to run again. FreshBooks deletes are also soft deletes via vis_state rather than a hard DELETE, so removed records may still be queryable.