Connecting FreshBooks to HubSpot

Architecture

How FreshBooks and HubSpot actually connect

Two systems that know nothing about each other. Everything below exists to give them one shared reference.

1. Step 1

   FreshBooks holds the truth

   An invoice sent is a claim; an invoice paid is revenue. On thirty-day terms those are different months, and reporting the first as a conversion books income you have not received and may not.

2. Step 2

   HubSpot needs a click to match

   HubSpot needs to resolve the incoming data to an existing contact or create one. Without an email or a hubspotutk it creates duplicates, and duplicate contacts break every report built on top of them.

3. Step 3

   The identifier is the bridge

   The contact identity — email, or the hubspotutk cookie, captured at the visit and carried into the FreshBooks invoice. Without it there is nothing to join on and no tool fixes that.

4. Step 4

   The event source decides reliability

   Send invoices at the point of payment, at the amount received after any processing fee.

5. Step 5

   Deduplication at the destination

   HubSpot deduplicates contacts on email address. Events and property updates against the same contact are idempotent by design, but a second contact created for the same person is not detected, and merging them afterwards is manual work.

Diagnose it honestly

Working vs. broken, side by side

Both states look identical from the HubSpot dashboard, which is why this runs for months before anyone notices.

Diagnostic sequence

Diagnostic order

Each step rules out a class of cause. Run them in order and the last one usually has a single explanation standing.

1. 1

   Count invoices carrying the contact identity — email, or the hubspotutk cookie

   The ceiling on everything else. Do this before debugging anything downstream.

2. 2

   Follow one real conversion end to end

   From the ad click through FreshBooks and into HubSpot.

3. 3

   Measure your average days-to-payment and your write-off rate

   Two numbers. Together they tell you how far your reported revenue sits from your bank balance.

4. 4

   Search for the test contact by email after sending

   One record or two? Then check whether the properties landed on the contact or only on the form submission — they are different things and only the first is usable.

5. 5

   Read the match rate, not the success message

   HubSpot shows the contact record and its timeline. A successful API response means HubSpot accepted the call, not that it resolved to the right contact — open the record and look.

Source-of-truth validation

How it gets proven

Against FreshBooks's own records, not against either platform's dashboard.

• The contact identity — email, or the hubspotutk cookie confirmed present on a live invoice.
• A real conversion followed from click through FreshBooks to HubSpot.
• One contact record confirmed, not two, with the property visible on the contact rather than only on the submission.
• Payments received reconciled against imported conversions over a window longer than your payment terms.
• Reconciled over a fully closed window, matched per record rather than on totals.
• Re-checked 30 days later.

Straight talk

When you don't need this

Worth reading before paying anyone, including us.

• If HubSpot already reports conversions that reconcile against FreshBooks's records within a few percent, this join is working and there is nothing to buy.
• Measure identifier coverage yourself first — pull your last hundred invoices and count how many carry the contact identity — email, or the hubspotutk cookie. Ten minutes, free, and it tells you whether any of this is worth doing.
• If you take payment upfront, issue and payment coincide and this whole distinction disappears.
• HubSpot's native form and tracking code already handle the straightforward cases well. This is worth building when the conversion happens somewhere HubSpot's code cannot see.