Xero
Xero
What it is
A behind-the-scenes system (the “xero-worker”) keeps Xero and Pipedrive in sync across all our brands. When an invoice is raised, it copies the invoice details onto the matching Pipedrive deal, and it keeps that deal’s invoice status up to date afterwards. Most of this is automatic — but there are a few things staff should understand and a couple of things you must not touch.
flowchart LR
I[Invoice raised in Xero] --> N[Deal title becomes the invoice number]
I --> F[Invoice number, status, due date, pay-now link copied to deal]
W[Xero webhook] --> S[Deal invoice status kept current: Authorised → Paid]What you’ll see happen on a deal
When a deal gets invoiced, the system automatically:
- Renames the deal to the invoice number (e.g.
PER-00123). The old quote title is replaced. - Fills in the invoice fields on the deal: invoice number, status, invoice ID, due date, and the customer “pay now” link.
- Keeps the status current as it changes:
Authorised→Paid(orVoided). This happens via a live update from Xero, so you don’t refresh anything.
Invoice numbers are prefixed by brand: HP- Holland, PM- P&M, PER-
Perspex Online, PLON- Plastic Online, EXP- Export (plus a couple of
special ones).
Two things keep Xero and Pipedrive linked:
- The deal title = the invoice number once invoiced. If you rename it, you break the link back to the invoice.
- The Xero Contact ID on the organisation is the master link between that customer and Xero. Never edit or clear it by hand — every future invoice for that customer depends on it.
What’s automatic vs what staff do
Automatic: raising invoices and numbering them, marking them paid, copying details onto the deal, keeping status current, and a daily reconciliation that catches anything that slipped.
Staff do: create/send/void invoices and apply payments for account and PO customers from the operator panel; create purchase orders; and re-link the Xero connection if it ever gets disconnected.
The old WooCommerce path (being retired)
Older orders (and current Plastic Online WooCommerce orders) came through a separate WooCommerce → Xero bridge that creates draft invoices. It’s legacy — new Perspex Online orders don’t use it. You may still see older deals tagged as coming from WooCommerce.
A quirk: that old bridge can report itself “down” on a health check when it’s actually still working (a stuck item in its retry queue). Not every “down” alert on it is a real outage.
Gotcha: customers can get merged if they share a name
When matching a payment or invoice back to a customer, the system tries email first, then phone, then name. The name step can occasionally merge two different customers who happen to share a name. It’s an actively managed, known issue — there are guards in place (it also checks the billing address for individuals, and ignores short/partial phone numbers) — but if you ever see a deal or invoice attached to the wrong person, that’s likely this. Flag it rather than trying to untangle it yourself.
Common questions
- Why did the deal name change to a code? That code is the invoice number — it’s meant to happen when the deal is invoiced.
- The invoice status looks stale. It updates automatically from Xero; if it’s clearly wrong (e.g. paid in Xero but not on the deal), flag it — the daily catch-up usually fixes it, but a stuck one needs a look.
- A customer’s invoices are going to the wrong contact. That’s set in the PIM, not Xero — see Invoicing.
Who to tell if it breaks
Tell Daniel or flag in #whats-new. A wrong-customer match or a Xero
disconnection is a system issue — escalate, don’t fix it manually.
Derived from: xero-worker and its NOTES, the legacy woo-xero bridge notes, and CLAUDE.md. If this looks wrong, the source changed — update the source and re-generate, don’t just patch this page. See also Invoicing and Pipedrive.