HubSpot + Sage Intacct integration

Sage Intacct turns up where a finance team has outgrown a single set of books. Several legal entities, shared customers, consolidated reporting, and a controller who can explain exactly why each of those exists. That is the audience, and it changes what a HubSpot integration is for.

These are not the questions a small business asks: less “has this customer paid”, more “which of our entities does this customer transact with, and what is the group exposure”. A seller opening an account in HubSpot wants to see the relationship, not one entity’s slice of it. Service wants to know before a renewal call that the group is ninety days overdue somewhere, even if their own entity is current.

That makes the mapping decision the expensive part. Finance genuinely does think of the customer as several records, one per entity, because that is how the ledger works. Sales genuinely does think of it as one account, because that is how the relationship works. A build that ignores the disagreement produces either a portal full of near duplicate companies or a single company record whose numbers do not tie to anything finance can reconcile. Settling it is a conversation with the controller and the sales leader in the same room, and it belongs at the start of the project rather than the middle.

Five objects carry it. Customers become HubSpot companies, contacts become HubSpot contacts, invoices and payments land as custom objects, and items become products.

Contacts deserve a warning. In Intacct a contact is a shared record that can be attached to a customer, a vendor and an employee, which is not how HubSpot thinks about a contact at all. We match on email, keep the Intacct contact name as a tie breaker, and accept that one Intacct contact can legitimately relate to several HubSpot companies. That is a difference between two data models, not a mess to be tidied up.

Keys are the record identifiers finance already uses: the customer id, the invoice record number, the payment record number, the item id. Every write goes into a custom HubSpot property so the match survives a rename. Payments associate to the invoice they settle rather than to the customer, which is what lets a part payment spread across three invoices resolve correctly instead of landing wherever the read happened to reach first.

A scheduled read on a watermark, with events as an accelerator rather than a foundation. The service holds an OAuth 2.0 client, reads each object with a page cursor, and writes into HubSpot as batch upserts keyed on the Intacct identifier, followed by a separate association pass. The checkpoint is per object, so a failure in one feed does not reload the others.

Sage documents outbound webhooks and platform triggers on the REST API but does not publish the list of objects they cover, so coverage varies and we confirm it object by object during discovery. Where an object is covered we subscribe and shorten the latency. We never let events be the only path, because a run that depends on a delivered event cannot tell a quiet system from a broken one.

Behind both sits the XML gateway, session based and still carrying objects the REST API has not reached. The service treats it as a second reader against the same mapping, not as a second integration.

This one turns on the entity structure. A single entity Intacct company with a short field list is a reasonable fit for one of the marketplace connectors: a packaged mapping, a vendor on the hook for the runtime, nobody of yours on call. That is a real option and we say so.

Once several entities are in play the packaged route runs out of room, because the decision it cannot make for you is how a group customer should appear in the portal. A service we build can carry entity as a property, aggregate group exposure, and keep the numbers tying back to what finance reconciles. The route we avoid is per-task automation, which prices against invoice and payment volume, the two highest counts and the two lowest value records in the system.

1. Scope. We settle the entity question first, with the controller and the sales leader present, then the object list and the direction of each one.
2. Architect. We fix the keys, the watermark per object, which API carries each object, and how entity is represented in HubSpot.
3. Build. The service is written against a test company with a portal allowlist in place from the first commit, and reads before it writes.
4. Validate. We reconcile customer counts and aged balances per entity against a saved Intacct report, and walk the differences with finance.
5. Operate. Cutover is a credential swap. After that we watch each object’s run history, keep replay and reconciliation endpoints available, and revisit the mapping when a new entity is added.