Xero adapter

Xero is an optional integration (VISION.md). The adapter lives in server/integrations/xero/ and sits behind the integration port (server/integrations/port.js). Core code never imports it.

The adapter connects one Xero organisation to each Flow organisation, copies its contacts and items, and sends issued Flow invoices to Xero as draft invoices. The lab checks and approves them in Xero. It also keeps a copy of the organisation's invoices, credit notes and payments, history included ("The mirror"). Bills are not ported yet.

Turn it on #

Each lab uses its own Xero app. There is no shared Flow Xero app, so no one else holds the lab's Xero sign-in.

In Flow, an owner opens Integrations, then Xero:

1. Create your Xero app at developer.xero.com, My Apps: a Web app, with this installation's address and the redirect URI the screen shows (https://<this installation>/api/xero/oauth/callback, Copy).
2. Paste the client id and the client secret. Choose the mode, and for live type the Xero organisation's exact name.
3. Save and turn Xero on. Flow creates its tables and starts Xero at once. If a setting is missing, the screen says which.
4. Connect to Xero, sign in to Xero and allow access. Flow then copies the history in the background ("The mirror").

The refresh token's key (XERO_TOKEN_KEY) comes from Flow's secrets key (docs/INTEGRATIONS.md, "The secrets key"). A host can instead set FLOW_INTEGRATIONS=xero, XERO_MODE and the settings below; a host setting wins over the screen.

Modes #

XERO_MODE says which Xero the adapter acts on. It has no default (issue #10).

Development and CI use replay or sandbox. They never hold live credentials. Tests use replay only and never call the real Xero API.

Settings #

Errors name a setting, never its value.

Demo #

A Xero Demo Company is the test and demo Xero: fictional data, free, and only its owner's Xero login sees it. Xero resets it 28 days after it was made, and its owner can reset it at any time (My Xero, Reset). It cannot invite other users or send invoices.

Flow connects to it with a Xero Custom Connection (XERO_CONNECTION=custom). Custom Connections are free on the Demo Company only, so Flow allows one only in sandbox mode. There is no browser step and no refresh token: Flow asks Xero for a 30-minute access token with the client id and secret (the client credentials grant). So Flow on localhost, in a cloud session, or on a host that sleeps connects the same way. Connect to Xero on the Xero page connects at once.

One time, the Demo Company's owner:

1. In My Xero, opens Try the Demo Company (Change Country: Australia).
2. In My Apps, presses New app, type Custom connection, with the scopes accounting.contacts accounting.invoices accounting.payments.read accounting.settings.read, and themselves as the authorising user.
3. Presses Connect in Xero's email and picks the Demo Company.
4. Copies the client id and generates the secret into host secrets, never a file: XERO_DEMO_CLIENT_ID and XERO_DEMO_CLIENT_SECRET for the demo script.

scripts/demo/xero-demo.mjs then runs the whole flow on synthetic data: the real Flow on a throwaway database (FLOW_TEST_DATABASE_URL, wiped first), connected to the Demo Company. It makes a new Flow customer, creates it in Xero, reads it back from Xero, and saves evidence.json (with the Xero link to the contact) and screenshots of Flow:

FLOW_TEST_DATABASE_URL=postgres://… XERO_DEMO_CLIENT_ID=… XERO_DEMO_CLIENT_SECRET=… \
  node scripts/demo/xero-demo.mjs --out xero-demo

A reset of the Demo Company can end the Custom Connection; then the owner approves it again from My Apps.

Connect Xero #

Only an owner can connect or disconnect Xero, with a verified owner sign-in (docs/SELF_HOSTING.md, "Sign-in (Clerk)"). Flow connects one Xero organisation to each Flow organisation, and a Xero organisation to at most one Flow organisation.

1. On the Xero app (developer.xero.com, My Apps), add the redirect URI https://<this installation's address>/api/xero/oauth/callback. On Replit that is the app's *.replit.app address. Flow reads the address from FLOW_PUBLIC_ORIGIN (or XERO_REDIRECT_URI); the two must match exactly.
2. POST /api/xero/connect with { "organisationId": "…" } answers with authorizeUrl. Open it in the browser and approve the organisation in Xero.
3. Xero sends the browser back to /api/xero/oauth/callback. Flow checks the one-use state (ten minutes), exchanges the code, and keeps the organisation XERO_TENANT_ID or XERO_TENANT_NAME names. If several are approved and the settings name none, it refuses. In sandbox it refuses an organisation that is not a Demo Company. A refused approval is revoked at Xero.

GET /api/xero/status?organisationId=… (anyone signed in) shows the mode, whether writes are allowed, the redirect URI, the connection and the day's Xero call budget. POST /api/xero/disconnect (owner) revokes the token at Xero and deletes Flow's copy.

The refresh token #

Xero gives a new refresh token on every refresh and the old one stops working, so Flow stores the newest one in xero_connections, encrypted with XERO_TOKEN_KEY (AES-256-GCM) and bound to its Flow organisation. A refresh holds that row's lock and stores the new token in the same transaction, so two refreshes never race. Access tokens stay in memory for their 30 minutes. No token is ever logged or shown.

A connection made in one mode is not used in another: change XERO_MODE and an owner connects again. So does a refresh token that Xero no longer accepts (unused for 60 days, or revoked): Flow answers xero_reconnect_needed. If XERO_TOKEN_KEY changes, the stored token cannot be read and an owner connects again.

Contacts and items #

Flow's own contacts stay in contacts (docs/CONTACTS.md). Xero's contacts are copied into xero_contacts. A sync replaces that copy and does not change Flow's contacts. Flow does not change a Xero contact that already exists, unless Two-way edits is on: then a Flow edit of a linked contact goes to Xero (docs/CONTACTS.md, "Two-way edits"; xero/contact-sync.js). With Add Xero clients on, each Xero client becomes a Flow contact.

When Create missing clients is on, an owner or admin creates the missing Xero contact from a Flow contact (POST /api/xero/contacts with { "organisationId", "contactId" }). Flow writes one Xero contact, stores that copy, and links it (created_by_flow). If Xero already has one active contact of that name, Flow links that one (exact_name) and creates nothing. An archived-only name, or more than one active name, is refused. GET /api/xero/contacts/match?organisationId=…&contactId=… answers whether Link and Create are offered, from the copy, with no Xero call.

When the names differ, or Xero has the name twice, an owner or admin links the Flow contact to the right Xero contact (POST /api/xero/contacts/link with { "organisationId", "contactId", "xeroContactId" }). Flow writes only its identity map (person); Xero is not called. The Xero contact must be active in the copy and not linked to another Flow contact. A link to a Xero contact that is now archived ends first.

POST /api/xero/sync with { "organisationId": "…" } (owner or admin) reads every Xero contact (100 a page) and item (one call) and replaces Flow's copy in xero_contacts and xero_items in one transaction. Records gone from Xero leave the copy. Items with no code are left out, because an invoice line names an item by code. A failed read keeps the copy as it was. Each sync is recorded in xero_sync_runs; GET /api/xero/status shows the last one. Outside replay mode the background worker also syncs each connected organisation once a day (refreshStaleCatalogues in import.js), so the pipeline can link customers (docs/JOB_INVOICE_LINKS.md). A failed read is tried again an hour later, then two, four and so on, at most a day apart. The first failure is reported with log.error; the same failure again is a warning.

GET /api/xero/contacts?organisationId=…&q=…&limit=… (up to 1,000) and GET /api/xero/items?organisationId=… (anyone signed in) list the copy.

For invoice preparation, server/integrations/xero/catalogue.js offers:

A sync and a batch of drafts for one organisation run one at a time (runtime.serial), because they share one call budget.

Draft invoices #

Flow is the store of record; Xero gets a copy (VISION.md). An issued Flow invoice version goes to Xero as one sales invoice (ACCREC). The customer's send mode (docs/INVOICING_RULES.md) decides its status: a draft (DRAFT, the default) that a person approves in Xero, or an approved invoice (AUTHORISED) that Flow then asks Xero to email to the customer.

flowchart TD
  start[Send issued invoice] --> pushed{Pushed before?}
  pushed -- settled --> done[already in Xero: nothing sent]
  pushed -- unknown outcome --> resume{Six minutes since the key was sent?}
  resume -- no --> same[Same request, same key]
  resume -- yes --> look[Look in Xero by reference]
  look -- one match --> reconciled[Record it]
  look -- none --> newkey[Same request, new key]
  pushed -- no --> earlier{Earlier version in Xero, not deleted or voided?}
  earlier -- yes --> refuse[Refuse: change it in Xero first]
  earlier -- no --> check[Contact, items, live reference check]
  check -- same contact, reference and total --> existing[Record the Xero invoice: nothing sent]
  check -- same contact and reference, other total, 90 days --> hold[Hold for a person]
  check -- clear --> store[Store request and key] --> send[POST] --> verify[Read back and compare]

The rules:

• What is sent is the issued document. Flow sends the latest issued version's document (invoice_versions), never live lines. A draft or void invoice is never sent.
• A sent invoice is never changed in place. Flow never updates a Xero invoice's contact, lines, amounts or dates. The one write to an existing Xero invoice is Delete, below, and it sends Status: DELETED only. A revised invoice (version 2) is sent only after the earlier version's Xero invoice is deleted or voided in Xero; Flow checks that live and keeps the earlier record.
• A missing Xero contact. The Flow customer must be linked to one Xero contact, or match exactly one active Xero contact by name. With Create missing clients on, a pending invoice offers Create (docs/CONTACTS.md). With it off, add the client in Xero, then sync. Flow does not change a Xero contact that already exists.
• Each line names its item. A line's itemCode from the issued document becomes the Xero ItemCode; a code Xero does not have stops the draft. Tax types come from XERO_TAX_TYPE_GST and XERO_TAX_TYPE_GST_FREE; amounts are tax-exclusive with each line's amount sent as Flow calculated it.
• Reference and dates. The Xero reference is the invoice's reference, or its number. The date is the issue date; the due date is the invoice's, or XERO_DEFAULT_DUE_DAYS later. With XERO_INVOICE_NUMBER=flow Xero gets Flow's number.
• Duplicates. For an invoice Flow drafted from a job that its complete, fresh copy of Xero showed has no invoice, Flow asks Xero nothing more. Otherwise, before it creates, Flow asks Xero for invoices with the same reference. One for the same contact and total is the same work: Flow records it (existing) and sends nothing. One for the same contact at another total dated within 90 days is held, unless the person sends again with that invoice in allowExistingReference.
• Uncertain outcomes. The request and its Idempotency-Key are stored in xero_invoice_pushes before they leave. If Xero refuses the first request, the record is dropped and the invoice can be sent again once fixed. If the outcome is unknown (timeout, 5xx), the record stays ambiguous. Sending again within six minutes repeats the same request with the same key (Xero keeps keys six minutes); after that Flow looks in Xero by reference, settles on the one matching draft it finds, and sends under a new key only when there is none.
• Read back. After a create Flow reads the draft and compares contact, subtotal, tax, total, line count, reference and date with the document. A difference is recorded as mismatch for a person to check in Xero.
• Email. In the approve_and_email send mode, after Flow reads back an approved invoice that matches, it calls Xero's email action for it once (POST Invoices/{id}/Email). The push records email_state: sent, failed (Xero refused; sending again retries) or unknown (a person checks Xero; Flow does not retry, because a repeat emails twice).
• One at a time. A batch runs on the writes lane, after any sync for the same organisation. A daily-limit 429 stops the batch and says which invoices were not tried.
• Live writes. In live mode nothing is written unless XERO_ALLOW_LIVE_WRITES=on. In sandbox the organisation's class is checked before each batch.

Through the integration port, pushInvoice({ organisationId, invoiceId, pushedBy }) sends one issued invoice and answers as one entry above.

What invoice preparation can rely on #

• previewDrafts(db, runtime, organisationId, invoiceIds) and the preview route cost no Xero calls. A preview state is ready, blocked (with problems), in_xero, ambiguous, dispatching or mismatch. Problem codes: invoice_not_issued, invoice_void, xero_contact_missing, xero_contact_ambiguous, xero_item_missing, and xero_earlier_version_in_xero (shown, not blocking: the push checks Xero live). Warnings: xero_not_synced, xero_sync_stale (over 24 hours).
• A push is safe to repeat: the Flow invoice id and version are the key, and a repeat never makes a second Xero invoice.
• A preview never writes; only push does, and only for issued versions.

Deleting a draft #

Delete on an issued Flow invoice whose Xero copy is still a draft also deletes that Xero draft (deleteInvoice on the integration port, server/integrations/xero/delete-invoice.js). The core stays free of Xero statuses. It calls the port and voids in Flow only after the answer is deleted or gone.

Flow reads the Xero invoice live by its id first (the push, or the Import link). Then:

A timeout or a 5xx leaves Flow unchanged. The next Delete reads Xero again and does not post a second delete when Xero already shows it gone.

The push (xero_invoice_pushes) and the Import link (xero_invoice_links) record who deleted it and when, and the push stores Xero's status. Flow's copy of the invoice takes that status too. The job's ledger state becomes deleted (or voided when Xero had already voided it), and the Flow invoice link is cleared the same way as deleting a draft that was never issued. The issued versions stay. The invoice's History gains a Void line.

Xero migration 0011_xero_invoice_deleted adds deleted_by and deleted_at on the push and the link. It is the Xero adapter's own migration.

The mirror #

Flow keeps a copy of the connected organisation's invoices, credit notes and payments (server/integrations/xero/mirror.js, issue #54), so its reports cover the years before Flow was installed and its records can link to Xero's without spending calls. Xero owns these records. Flow does not edit their amounts or lines. Delete of a draft, above, sets the copy's status so the screen matches, and the next read of Xero replaces that row.

The history import #

Connecting Xero starts the import. Nobody runs a script.

flowchart LR
  connect[Owner connects Xero] --> job[Job xero.import<br/>in background_jobs]
  boot[Flow starts: a connected<br/>organisation with no finished copy] --> job
  job --> slice[Slice: up to 20 pages<br/>of each resource]
  slice -- day budget used --> later[Next slice in 1 hour]
  slice -- page limit --> next[Next slice now]
  later --> slice
  next --> slice
  slice -- all resources done --> done[History complete]
  done -- 15 minutes later --> slice

• The import is a job on the core queue (server/integrations/xero/import.js). One import per organisation is open at a time.
• A Flow that starts with Xero already connected, and with a resource that has no finished pass, queues the import too. So an upgrade imports with no step.
• Connecting another Xero organisation clears the cursors, so its history is read from the start.
• The worker runs outside replay mode. It only reads from Xero. It leaves the reserve share of the day's calls (XERO_MIRROR_RESERVE_FRACTION).
• A failed slice retries with the queue's back-off. After its last attempt it opens a review item (job.dead).

Reading the changes #

The copy is fresh only while its last full read of invoices is less than a day old (mirrorState in lookup.js). A copy that is not fresh proves nothing, so drafts by rule wait and the matcher does not say "no invoice" (issue #131). So the import never ends:

• When every resource is read to its end, the same job is queued again for 15 minutes later (REFRESH_MS). It reads only what changed since each cursor: with few changes, one call per resource.
• The worker keeps one read queued for each connected organisation, so a restart or an upgrade needs no step. While the call guard stops Xero calls, no read is queued. A read that gave up waits for a person (its review item), a restart or the next day.
• A copy that goes out of date is reported once with log.error, and again when it is fresh. health() shows each copy under copies and is not ok while a complete copy is out of date.
• About 192 calls a day (invoices and credit notes, every 15 minutes), inside the reserve the mirror leaves for drafts and people.

POST /api/xero/mirror with { "organisationId": "…", "resources"?: [...] } (owner or admin) reads each resource from its cursor now. GET /api/xero/mirror (anyone signed in) shows the counts and cursors.

flowchart LR
  cursor[Cursor: changed since T, page P] --> call[GET Invoices<br/>If-Modified-Since T<br/>oldest change first]
  call --> store[Upsert the page<br/>and move the cursor<br/>in one transaction]
  store -- full page --> cursor
  store -- short page --> done[Pass done]

• The first read copies the whole history. It has no cursor. 7,000 invoices at 200 a page cost 35 calls.
• Later reads copy changes only. Each read starts from the last change it stored.
• It can stop at any page. Each page and the cursor are stored in one transaction, so a failed call, a restart or a spent budget loses nothing.
• It never skips a record. After a full page the cursor moves to the page's last change time, less one second, so a record that changes during a read is read again. Only when one second holds a full page does the page number move on.
• It keeps calls for drafts and people. It stops when the day's remaining calls fall to XERO_MIRROR_RESERVE_FRACTION of the limit.
• A row changes only when its content does. Each row keeps a hash of what Flow stores; last_changed_at moves only with it.
• References are kept. References and line descriptions are the lab's own data and are kept, unless XERO_KEEP_REFERENCE=off.

Webhooks and the daily check #

The poll is late by up to 15 minutes, and Xero calls polling its second choice. Xero's webhooks tell Flow which record changed within seconds. Xero, Intuit, Shopify and Stripe all say a webhook can be lost, so the poll stays as the safety net, and a daily check proves the copy is complete (issue #45).

flowchart LR
  xero[Xero] -- event: id only --> hook[POST /api/xero/webhooks<br/>check signature<br/>save id, answer 200]
  hook --> inbox[(xero_webhook_events)]
  daily[Daily check<br/>summary of every invoice] -- rows that differ --> inbox
  inbox --> read[Read by id<br/>50 invoices a call]
  read --> copy[(Xero copy)]
  poll[Changes poll<br/>15 min, or 1 h<br/>while webhooks arrive] --> copy
  copy --> compare[Sent invoices<br/>compared again]

• Receive. Xero signs each delivery with the webhook key (x-xero-signature, HMAC-SHA256 of the raw body, base64). A good signature gets 200 with no body; a bad one gets 401; that is also Xero's "intent to receive" test. Without XERO_WEBHOOK_KEY the route answers 404.
• Save, then read. Each event's record id waits in xero_webhook_events, one row per record, so a repeat event costs nothing. The import worker reads waiting invoices by id, 50 a call, into the copy, then compares the sent invoices again. Credit note events read the credit note changes; contact events read contacts and items again, at most once an hour. Other events need no read.
• The poll slows down. While a webhook arrived in the last day, the poll waits an hour (WEBHOOK_REFRESH_MS). If webhooks stop, it goes back to 15 minutes by itself.
• The daily check. Once a day, for a complete copy, one summary read of every invoice (1,000 a call) finds each copy row whose status, money or change time differs from Xero, each invoice the copy lacks, and each live row Xero no longer lists. Those wait in the inbox and are read by id: at most 250 a day. This catches a part payment that did not move Xero's change time, and a lost webhook.
• Calls. Every read goes through the call guard and the governor's sync lane, and leaves the mirror's reserve. A failed read waits 1 minute, then 2, 4 and up to an hour; it is logged once as an error, then as warnings.
• Set it up. On the Xero app's Webhooks page, set the delivery URL to this installation's address plus /api/xero/webhooks, and tick Contacts, Invoices, and Credit notes when Xero offers it. Paste the webhook key into Flow's Xero settings ("Webhook key"), save, then press "Send Intent to receive" in Xero.

Read before draft and send #

Just before an automatic draft pass, and before Send all ready, Flow reads Xero's latest changes into the copy (readChangesFirst, the adapter's readChanges capability). This is once per pass or press, before the first draft or send, so a job someone invoiced in Xero a minute ago is not drafted or sent twice.

• No call while webhooks arrive and none waits in the inbox, or when the copy read invoices and credit notes in the last 10 minutes (READ_FIRST_MS).
• Otherwise Flow reads the waiting inbox ids, then the invoice and credit note changes (at most 5 pages), through the call guard and the sync lane.
• A changed copy runs the matcher before the draft or send, so the job links to its Xero invoice and waits.
• A read that cannot run (not connected, calls stopped, the day's calls kept for people, more changes than one read takes) drafts and sends nothing. The answer says accountingRead: 'waiting' or waiting: N; the next pass tries again.

Sent invoices against the copy #

People change invoices in both places after Flow sends them (server/integrations/xero/reconcile.js, issue #132). The version Flow sent is the merge base: the document both sides agreed on. After each read of the copy that changed an invoice, Flow compares every invoice it sent with Xero's copy of it. No Xero calls.

• Each finding is one review item (invoice.accounting_differs) with both sides. A repeat refreshes it. It only alerts: Flow never writes to Xero or to the Flow invoice to fix it. A person fixes it where they choose.
• The item closes when a later check finds no difference.
• Mark resolved (POST /api/xero/invoices/<id>/recheck, owner or admin) reads Xero's invoice changes first, then checks that one invoice again.
• POST /api/xero/invoices/status (anyone signed in) answers each invoice's Xero status from the copy: not_sent, sending, not_copied, draft, approved, part_paid, paid, voided or deleted, with any finding. The Invoices page shows it as a tag on issued and void invoices, and the invoice shows the differences, Open in Xero and Mark resolved.
• Voiding a sent invoice in Flow warns while Xero still holds it live.
• References and line descriptions are not compared yet.

The billing ledger #

server/integrations/xero/ledger.js answers the billing obligation ledger (server/core/ledger.js) in its own evidence shapes.

• Does Xero hold an invoice for this job? xeroLiveCheck(db, runtime, organisationId) is the liveCheck for draftInvoiceForObligation. It answers { state, accountingRef, accountingUrl, matchedBy, checkedAt }. POST /api/xero/obligations/<id>/check (owner or admin) runs it and records the answer with recordAccountingEvidence.
• Payments. POST /api/xero/payments/sync (owner or admin) reads Xero sales payments changed since the last read (xero_payment_cursors; the first read goes back 90 days) and records each with recordPayment. When payments cover the total, the ledger queues the "paid" write-back. The port's pullPayments({ organisationId, since }) returns the payments in recordPayment's shape with a cursor.

The ledger records a match that is not exact as ambiguous, and any answer but not_found refuses a draft. A Xero error throws, and the ledger refuses the draft. Xero states map to the ledger's: DRAFT and SUBMITTED to drafted, AUTHORISED to authorised (or part_paid once money is paid), PAID to paid, VOIDED to voided, DELETED to deleted. accountingUrl is a Xero deep link for a person.

A payment is recorded only when its Xero invoice ties to one job by flow_invoice or accounting_ref. Flow refreshes that job's Xero state first, so the ledger accepts it. Payments that tie to no job, and deleted payments, are listed in the answer and not recorded. The cursor moves only when no payment failed, so a failed one is read again.

Rate limits and retries #

Every Xero call goes through server/integrations/xero/governor.js, per connected organisation:

• at most 4 calls at once and 55 a minute (Xero allows 5 and 60), and 10,000 a minute across organisations;
• a daily budget that starts at XERO_DAY_LIMIT and then follows Xero's X-DayLimit-Remaining header; a warning is logged once a day at XERO_USAGE_WARNING_FRACTION;
• a 429 is retried once, after the wait Xero's Retry-After and X-Rate-Limit-Problem ask for, never more than a minute;
• a daily-limit 429 opens a circuit: later calls fail at once with xero_rate_limited until Xero's Retry-After passes or the day rolls over;
• a 401 drops the cached access token and tries once more;
• a create carries an Idempotency-Key and a retry sends the same bytes, so Xero returns the first result instead of a second invoice.

Calls count against a lane (writes, sync, reads, other) so the status shows where the day's budget went. The lane, and a 429's X-Rate-Limit-Problem, are stored on the call row. Integrations › Xero reads that row, the governor's day limit, and the copy's own timestamps (webhook, poll, nightly read). It does not call Xero. A call from before the lane column has no lane, and the card does not invent one.

Every call also goes through the call guard (docs/INTEGRATIONS.md, "Outbound calls"), keyed by the Xero organisation, with its state in xero_call_guard and one row per call in xero_calls:

• a token refresh Xero refuses for good (invalid_grant) halts every call until an owner connects Xero again or saves its settings;
• a 401 or 403 that a fresh token does not clear stops only that resource (for example Payments when the connection lacks its scope, #99). The history import skips a stopped resource as refused and reads the rest. After 6 hours one probe call may go (then 12, then 24 hours); a good probe starts the resource again. A connection made before accounting.payments.read was in the default scope needs one Connect again to read payments;
• 5 failed calls in 10 minutes open the circuit (5 minutes, doubling to 6 hours), and 50 failed calls stop calls until the next UTC day;
• a first 401 (an expired access token) is not counted;
• health() answers each organisation's guard state under calls.

Replay fixtures #

A fixture file lists interactions: a request (method, URL, and the query values that must match) and the response Xero would give. A request that no interaction matches fails with xero_replay_no_match, so replay can never reach the real Xero. Fixtures hold synthetic data only (CONTRIBUTING.md): made-up names, example.test addresses and all-zero ids.