How to integrate with FreshBooks: Two identifiers, two date filters

Every FreshBooks call needs one of two identifiers, and which one is not a matter of taste. Accounting resources are reached at /accounting/account/{accountId}/, while time tracking and projects are reached at /timetracking/business/{businessId}/.

FreshBooks explains why rather than leaving you to infer it: “For historical reasons, FreshBooks has shifted from an account concept to a business concept, but many resources still make use of accountIds.” The migration happened, the old addressing stayed, and both are live.

Both values come back from a single call to /me, inside business_memberships. Each membership has an id of its own and a nested business object, and the business object carries the account id and the business id you actually want.

That nesting is the first trap, and the documentation flags it: “Be careful not to mistake the business’s id for the id of the business_membership object itself.” Two of the three ids in that fragment are plausible and one is correct.

If that split still sounds like a distinction someone invented, FreshBooks settles it from a different direction. Every webhook it delivers carries both values, and the reason it gives is the model itself: “Because some FreshBooks resources use account and others business (See Identity Model), both the account_id and business_id are provided.” A vendor that shipped one identifier under two names would have no reason to put both in every notification.

Which objects a connection reaches, field by field, is on the FreshBooks API page. What the rest of this piece is about is what the identifier split decides after you have resolved it, because the answer turns out not to be limited to routing.

Ask both halves of FreshBooks what changed since a moment and you get two different answers, because they accept two different kinds of moment. The accounting side takes a date. The project side takes a timestamp.

On accounting resources the between-style filters carry a caveat in FreshBooks’ own words: “A special note about Betweens applied to date-time columns like ‘updated’: these generally only have day-level granularity, and take the input form YYYY-MM-DD.”

On the project side the same idea is a full timestamp. FreshBooks documents updated_since on time entries as a value that “must be in ISO 8601 format”, and its own example carries seconds.

The practical difference is the size of the smallest question you can ask. A sync that runs every fifteen minutes can ask the project side for the last fifteen minutes. On the accounting side the narrowest window available is today, and today gets larger all day.

This is the part of the seam that no layer removes. Resolving the identifiers is genuine work and it can be done once, behind an interface. Inventing a timestamp that the accounting side never recorded is a different kind of request, and nobody can serve it.

So the design decision lands on your side either way. Either your accounting pass reaches back a whole day and you accept re-reading records you already have, or it reaches back further and you accept more of them.

The seam shows up twice more on the same documentation page, and both times it is a change of syntax rather than a change of capability. Sorting is written one way for accounting endpoints and another for project-like ones.

FreshBooks states the split directly: “The form of the sort differs slightly between /accounting endpoints and project-like endpoints.” Accounting takes a suffix, ?sort=field_name_asc or ?sort=field_name_desc. Project-like endpoints take a leading minus, ?sort=field_name against ?sort=-field_name.

Searching splits the same way. Accounting resources take bracketed parameters that need url-encoding, in the form ?search[key]=value. Project-like resources take plain query parameters, as in ?complete=true or ?billed=true.

None of this is difficult on its own. It is difficult to hold, because a helper that builds a sort or a filter is exactly the kind of code you write once and reuse everywhere, and here the same helper is wrong on half the surface.

FreshBooks does send native events, which puts it in a minority of the systems we support. Eight resources are wired through us, and they carry three verbs: created, updated and deleted.

A subscription is narrow and it is per customer. Our create call takes one resource and one eventType per subscription, so the inventory you operate is a grid of resources against verbs, multiplied by every connected account.

FreshBooks’ own event table is wider than the routed set. It lists fifteen nouns, including project and time_entry, so events exist on both sides of the seam even though the routed eight are all accounting-side resources.

It also has a fourth verb. sendByEmail exists on invoices and estimates, and an invoice being emailed to a client is a real moment in a receivable. It has no counterpart in a vocabulary of created, updated and deleted.

Delivery has three edges worth encoding before the first customer, and FreshBooks documents all three. There is no speed commitment at all: “delivery could range from a few seconds to several minutes.”

The second edge is the one that catches people. Anything other than a 2xx counts as a failure, and FreshBooks names the case you would not think of: “including 3xx HTTP redirection codes”. An endpoint that answers a redirect to its canonical host has been failing silently the whole time.

The third is a ten second timeout, with the remedy stated in the same paragraph: “consider deferring app processing until after a response to the webhook has been sent.” Repeated failures drop the message, and a long run of them can have the webhook disabled until you resend the verification token.

Every callback carries an X-FreshBooks-Hmac-SHA256 header, and verifying it is where a correct implementation still fails. The digest is not taken over the bytes you received.

The payload arrives form-urlencoded, as query-style parameters. The signature is described as an HMAC over “a UTF-8 encoded json string of the parameters using the verifier key”. So you re-encode the parameters as JSON, and the exact text of that JSON is the input.

Two details decide whether your digest matches. FreshBooks casts every value to a string first, so the numeric ids are quoted. And the serialisation carries whitespace, which the documentation spells out because it has to.

The signing secret is never issued as one. When you register a callback, FreshBooks posts a verification code to the URL and you send it back to confirm ownership. That same code is then the signing key: “it will be used as the secret to calculate signatures used to verify webhooks are from FreshBooks”.

So the value you might treat as a one-time handshake token is the long-lived secret for every event that follows. Storing it is not optional, and it belongs wherever your other signing keys live rather than in a log line about onboarding. How failures of this kind surface once they are normalised is on the unified error handling page.

FreshBooks caps a page at 100 records and does not tell you when it has done so. The documentation uses the word itself: “per_page is silently capped at 100”.

Its own example is unambiguous. A request written as ?per_page=2000 is annotated “will only return 100 invoices”. There is no error, no warning and no header saying the request was modified.

That makes the failure a correctness problem rather than a performance one. A sync that asks for everything and reads what comes back is complete in testing, where the customer has forty invoices, and quietly wrong in production, where they have four thousand.

The second thing a collection call will not give you by default is the related data. In FreshBooks’ words, some relations “require additional calls for us to full out”, and a request has to name them explicitly.

An invoice read without ?include[]=lines returns the header and no line items, which is the second version of the same silent gap: a response that is shaped correctly and incomplete. Multiple includes can be combined in one call.

FreshBooks runs ordinary OAuth 2.0 with the authorization code flow, and one rule inside it is not ordinary. Refresh tokens rotate, and only one of them exists per user per application at any moment.

The documentation is precise about all three parts: “Refresh Tokens live forever, but are one-time-use, and only one Refresh Token can be alive at any time per user per application … all old Refresh Tokens immediately become invalid.”

The asymmetry underneath it is what makes this a concurrency problem rather than a storage problem. Bearer tokens do not behave the same way: “you could have several valid Bearer Tokens at any given point in time.”

So two workers refreshing the same customer at the same time both succeed at getting a bearer token, and only one of them holds a usable refresh token afterwards. The other holds a dead one, and the recovery path is the customer authorising your application again by hand. Refreshes belong behind a per-customer lock.

Scopes have a related property that costs more the later you meet it. They cannot be widened in place: “It’s not possible to remove scopes from an existing access token. The only way to reduce or add consented scopes is to revoke the token and start with the app authorization flow again.”

A scope you did not request at onboarding is a scope you obtain by sending an existing customer back through consent. The scope grammar is entity:object:action across 22 objects, with two action classes, where write covers creating, editing, archiving and deleting together.

Most of the seam is absorbable, and the parts that are not divide cleanly. Four things stop being yours:

• The identifier routing. Both values are resolved during the connection and stored per tenant, so no call site has to know whether the resource it wants is addressed by account or by business.
• The two query grammars. One sort form and one filter form reach your code, rather than a suffix on one half of the surface and a minus sign on the other.
• Paging and includes. The silent cap and the missing line items are the same class of bug, and both are handled before a response is normalised into the common data model.
• Token rotation and its race. A single-use refresh token per user per application is a locking problem, and it is solved once here instead of in every integration.

Three things do not move, and two of them are decisions rather than work:

• The resolution of the accounting delta. A day is the smallest window FreshBooks records on that side. No interface can turn a date into a change timestamp, so how far each pass reaches back, and how much re-reading you accept, stays a choice you make.
• Your receiver. The ten second budget, the queue behind it and the signature check are yours, because they run on your infrastructure. Answer first and process afterwards, and remember that a redirect counts as a failure.
• Which permissions you ask for. Scopes cannot be widened without sending a customer back through consent, so the list you request at onboarding is a decision about the product you intend to build, not a setting.

One note on the objects themselves. Customers and suppliers are supported for reading and writing today, and most of the remaining catalogue is marked on demand, which means available on request rather than unavailable. If bills or credit notes matter to your product, ask for the read at the same time as the event, because the two are separate requests.