HubSpot + Xero integration

Xero is built for small businesses and the accountants and bookkeepers who work with them, so the person closest to the ledger may well sit at an accounting practice rather than inside the company. Sales lives in HubSpot. The questions that cross between the two are small and constant: did the customer pay the deposit, which invoice is overdue, was the second stage ever billed. Each one becomes an email to whoever keeps the books, and a wait.

HubSpot’s own Xero app goes further than showing invoices in the portal. Its two-way invoice sync is meant for small businesses that run their billing from HubSpot: a deal or a quote becomes a HubSpot invoice, the invoice lands in Xero, and payments recorded against it come back. For a team that bills from its CRM, that is most of the integration, and it installs rather than builds.

What decides the rest is the record model. A Xero contact is the party you invoice, often a whole business with up to five contact persons, and the app pairs it with a HubSpot contact on email. A business that sells to companies, reports on accounts, or quotes in Xero rather than in HubSpot eventually needs a company keyed on the Xero identifier instead, and that is where a build starts.

HubSpot’s app already moves four of the five objects in the table: contacts, items, invoices and payments. Quotes are the gap, and the listing says so.

Keys are Xero’s own identifiers. Xero tells developers to reference contacts by ContactID rather than by name, warning that contact names may stop being unique, so a build stores ContactID and InvoiceID in custom HubSpot properties. Where HubSpot creates the Xero contact, the build writes the HubSpot record ID into ContactNumber, a field only the API can set and Xero shows as the contact code, so a retry finds the contact instead of making a second one.

The invoice feed needs one filter. Xero’s invoices endpoint returns sales invoices and supplier bills alike, telling them apart by type, and a bill’s number is not unique. A HubSpot sync reads sales invoices only and keys on InvoiceID. Payments key on their own ID and associate to the invoice they settle, so a part payment lands on the right document.

HubSpot’s app is a data sync. It indexes both sides, then detects changes from HubSpot within a few minutes and changes from Xero every 30 minutes, with a Sync now button when that is too slow. Xero needs an invoice’s contact and products to exist first, so the syncs are switched on in order: contacts, then products, then invoices.

When a build takes over part of the work, its shape is a webhook queue. Xero posts events for contacts and invoices, signed with an HMAC-SHA256 hash in the x-xero-signature header. The endpoint checks the signature, answers inside five seconds, and queues the resource IDs. A worker reads them back in batches through the IDs filter, upserts HubSpot on ContactID and InvoiceID, then runs a separate association pass, so a replay changes nothing.

Payments, items and quotes raise no events, so a nightly sweep reads them with If-Modified-Since. The service renews its 30-minute access token with a refresh token that lasts up to 60 days, and saves the new pair every time.

The question that decides this one is which system raises the invoice. If HubSpot does, through quotes, deals or subscriptions, HubSpot’s own app is built for that flow, and it is where we start. It handles six currencies, CAD and USD among them, and it does not import tax rates for multi-tenant Xero accounts, so check both before you commit.

A custom API integration earns its cost when the model has to change rather than the flow: Xero contacts kept as HubSpot companies, quotes in the pipeline, balances on the account, or a workflow that fires when a payment lands. Xero also lists a Xero Connector of its own, which lets HubSpot’s AI assistant and agents look up and create Xero records on request; it answers prompts rather than keeping records in step. The route we steer away from is a per-task automation platform, because payments, items and quotes raise no events and have to be polled.

1. Scope. We confirm which system raises invoices, whether contacts or companies carry the account, and whether your currencies and tax setup fit the app. Budget 4 to 8 hours of discovery and 8 to 24 of setup.
2. Architect. We agree the sync direction and the conflict winner per object, the custom mappings Data Hub allows, and the trigger that would send the work to a build.
3. Build. We install the app, switch on the contact sync, then products, then invoices and payments, and wire the HubSpot workflows that use them.
4. Validate. We rehearse against Xero’s demo company, then reconcile contact, invoice and payment counts against Xero reports.
5. Operate. We watch failing records on the sync tab, fix SKU and email mismatches at the source, and move to a build when the app runs out of room.