FreshBooks and Avalara integration

What moves between them

The main flow runs from FreshBooks into Avalara. ml-connector reads FreshBooks invoices and posts them to AvaTax as SalesInvoice transactions for jurisdictional tax calculation, and reads FreshBooks AP bills and posts them as PurchaseInvoice transactions for self-assessed use tax. The calculated tax amounts and line totals come back synchronously and ml-connector writes them onto the matching FreshBooks invoice and bill line items. FreshBooks clients flow the same direction as AvaTax customers so exemption certificates resolve correctly, and FreshBooks items align with AvaTax tax codes so each line is classified. Voided or deleted FreshBooks invoices are voided in AvaTax. AvaTax holds no ledger or vendor master, so no accounting records ever flow back into FreshBooks.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the FreshBooks side it runs the OAuth 2.0 Authorization Code grant, refreshes the access token when a call returns 401, and because each refresh rotates the refresh token it persists the new one immediately to avoid locking itself out; it also resolves the account ID and business ID from the identity endpoint so every accounting path is built correctly. On the Avalara side it sends the Base64 account-ID-and-license-key Basic auth header on each request and selects the sandbox or production base URL to match the credentials, since sandbox keys are rejected in production. FreshBooks invoices created via the API begin as Draft and are not in accounting reports until marked Sent, so ml-connector tracks invoice status and submits the right transaction at the right point. It uses the FreshBooks invoice number as the AvaTax transaction code: an uncommitted code updates in place on retry, and CreateOrAdjustTransaction keeps the post fully idempotent so a re-read invoice is never double-taxed. FreshBooks webhook latency is not guaranteed, so reconciliation runs by polling on a schedule, paging 100 records at a time, while a webhook can serve as an early trigger. Addresses are validated through the AvaTax resolve call before calculation, since a bad address fails the tax lookup. Both sides return HTTP 429 under throttling, so ml-connector backs off with jitter and retries, and every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A twelve-person design and consulting studio bills clients across several states through FreshBooks and buys equipment and software from out-of-state suppliers. Before the integration, the bookkeeper looked up sales tax rates by hand for each client invoice and guessed at use tax on supplier bills, which produced wrong tax on invoices and a use-tax exposure nobody could quantify at filing time. With FreshBooks and Avalara connected, each invoice is sent to AvaTax for the exact rate at the client's address and the figure is written back before the invoice goes out, and each AP bill is posted as a PurchaseInvoice so use tax is self-assessed correctly. The manual rate lookups are gone and the studio enters tax season with defensible numbers.

What you can do

• •Calculate jurisdiction-accurate sales tax on FreshBooks invoices through AvaTax and write the result back onto the invoice.
• •Post FreshBooks AP bills to AvaTax as PurchaseInvoice transactions so use tax is self-assessed correctly.
• •Map FreshBooks clients to AvaTax customers and FreshBooks items to AvaTax tax codes so exemptions and taxability resolve.
• •Bridge FreshBooks rotating OAuth refresh tokens and the Avalara account-and-license-key Basic auth header.
• •Poll on a schedule with document-code idempotency, address validation, retries, and a full audit trail on every record.

Questions

Which direction does data move between FreshBooks and Avalara?

The main flow is FreshBooks into Avalara. Invoices and AP bills move from FreshBooks to AvaTax for tax calculation, and the calculated tax is written back onto the FreshBooks document. AvaTax has no GL accounts, vendors, or payments of its own, so no accounting records ever flow back into FreshBooks.

How does the integration avoid taxing the same FreshBooks invoice twice?

ml-connector uses the FreshBooks invoice number as the AvaTax transaction code, which AvaTax treats as its idempotency key. An uncommitted transaction with the same code updates in place, and using CreateOrAdjustTransaction makes the post idempotent regardless of commit state. A FreshBooks invoice that is re-read during a poll therefore updates its existing AvaTax transaction rather than creating a duplicate.

Does FreshBooks push invoices, or does ml-connector poll for them?

Polling is the default. FreshBooks can send HMAC-signed webhooks, but its own docs state delivery latency is not guaranteed and can run to several minutes, which is not safe for tax-critical work. ml-connector reconciles by polling on a schedule, paging 100 records at a time, and can still take a webhook as an early trigger where one is enabled.