FreshBooks and Anaplan integration

What moves between them

The main flow runs from FreshBooks into Anaplan. ml-connector reads FreshBooks invoices, payments, expenses, and bills and loads the amounts into the matching Anaplan modules as actuals against the right period and account, while clients, bill vendors, and the chart of accounts are loaded into Anaplan lists so every figure resolves to an existing member. The load runs through a named Anaplan import action created by a model builder, on a schedule that matches your planning cycle. Plan and forecast values calculated in Anaplan can be exported and read back, but FreshBooks has no budget object to receive them, so ml-connector treats those exports as planning reads and does not write plan figures 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 with its rotating refresh token before expiry, and resolves the accountId and businessId from the identity endpoint so accounting and time-tracking paths are built correctly. On the Anaplan side it obtains a basic, certificate, or OAuth token, reuses it within the 35-minute window rather than minting one per call, and targets the lowercase-hex workspace id and uppercase-hex model id. Loading uses Anaplan's asynchronous pattern: upload the actuals file in chunks, start the model builder's named import action, then poll the task id until the state is complete, since a 200 on the start call does not mean the data is in. FreshBooks chart of accounts and clients are mapped to Anaplan list members first, so every imported amount lands on a valid dimension. Anaplan locks the model during an import, so ml-connector serializes loads against the same model and never overlaps them. FreshBooks has no idempotency header and can return a 409 on a colliding invoice number, so ml-connector dedupes on the FreshBooks record id and a BullMQ jobId before each load, and Anaplan imports overwrite to the same file id so a re-run does not double-count. FreshBooks webhooks can trigger a refresh as records change, but because Anaplan cannot be pushed to and FreshBooks webhook latency is not guaranteed, a scheduled poll is the reliable trigger. Anaplan limits the tenant to 600 requests per minute and FreshBooks throttles short bursts, both returning HTTP 429, so ml-connector applies exponential backoff with jitter. Every record carries a full audit trail and can be replayed if a load fails.

A real-world example

A 40-person creative agency bills clients and tracks contractor costs in FreshBooks, and its finance lead builds the annual budget and rolling forecast in Anaplan. Before the integration, she exported invoice, payment, and expense reports from FreshBooks each month and pasted the totals into the Anaplan actuals module by hand, which meant budget-versus-actual reviews ran a week behind and a mistyped figure could throw off a whole department's variance. With FreshBooks and Anaplan connected, each month's revenue and spend loads into the actuals module automatically, allocated to the right client and account, and the chart of accounts stays aligned as a list. Variance reports are current, the manual paste step is gone, and the forecast is built on figures that match the books.

What you can do

• •Load FreshBooks invoices, payments, expenses, and bills into Anaplan modules as actuals against the correct period and account.
• •Keep Anaplan lists aligned with the FreshBooks chart of accounts, clients, and bill vendors so every figure lands on a valid member.
• •Run loads through a model builder's named Anaplan import action using the asynchronous upload, start, and poll pattern.
• •Bridge FreshBooks OAuth 2.0 token refresh and the short-lived Anaplan auth token without manual intervention.
• •Poll on a schedule with id and jobId dedup, 429 backoff, and a full audit trail on every record.

Questions

Which direction does data move between FreshBooks and Anaplan?

The main flow is FreshBooks into Anaplan. Invoices, payments, expenses, and bills move from FreshBooks into Anaplan modules as actuals, and clients, bill vendors, and the chart of accounts feed Anaplan lists. Anaplan is a planning platform with no invoice or ledger object, so FreshBooks stays the system of record and ml-connector does not write plan figures back into FreshBooks.

Does Anaplan store invoices and accounts the way FreshBooks does?

No. Anaplan holds data as members of lists and cells in modules inside a workspace and model, not as named invoice, vendor, or account objects. ml-connector maps the FreshBooks chart of accounts and clients to Anaplan list members and loads the amounts into the modules and line items a model builder has configured, so the structures must already exist in the customer's model.

How does the integration deal with Anaplan having no webhooks?

Anaplan has no outbound webhooks and cannot be pushed to, so loading is always pull and poll. ml-connector reads FreshBooks on a schedule, starts the named Anaplan import action, and polls the returned task id until the task state is complete before treating the load as done. FreshBooks webhooks can prompt an earlier refresh, but because their delivery latency is not guaranteed the scheduled poll is the dependable trigger.