Xero, QuickBooks and NetSuite APIs, compared.

Xero's chart is a flat list: no parent field, no grouping object. The grouping in Xero's own reports comes from account type. QBO nests five levels deep in FullyQualifiedName; NetSuite nests arbitrarily.

Do — Render a flat list gracefully, with type as the only grouping. No chart-of-accounts view may assume parents exist.

A client who is also a subcontractor is one Contact in Xero and two unlinked records in QBO, each with its own id and balance. DisplayName is unique across customers, vendors and employees, so the two cannot even share a name — the vendor is typically 'Acme Ltd (V)'. Nothing in the API says they are the same party, so any total-exposure figure has to reunite them.

Do — Model a Party with role flags and a list of source refs. Merge is an explicit action showing both balances; auto-merge on a matching tax identifier, never on a name.

There is no Status field on a QBO Invoice: open, paid, part-paid and overdue are computed from Balance, TotalAmt and DueDate. A voided invoice keeps its record and zeroes its amounts, so counts over-report while sums do not.

Do — Derive it in one function at normalisation, store it, and mark it derived. Never present it as the source's own.

GET /Invoices returns ACCREC and ACCPAY documents together. An aging table fed from that endpoint without a Type filter shows payables as receivables, with plausible-looking numbers and the wrong sign on the balance sheet.

Do — Every Xero invoice read carries a Type filter. Make it a required parameter in the adapter's function signature so it cannot be forgotten.

A vendor invoice you will pay later is a Bill. A card swipe is a Purchase, which posts no accounts payable and does not appear in any Bill query. Companies that run most spend on cards can have the majority of their expenses invisible to a Bill-only integration.

Do — Every spend aggregate reads Bill and Purchase — in Xero, Invoice ACCPAY and BankTransaction SPEND. Name the metric for what it contains.

Xero's SUBMITTED status is a flag any user can set. QBO's API has no approval concept whatsoever. NetSuite has server-enforced multi-step routing that your write may enter and not clear — a successful API call does not mean an approved bill.

Do — Approval state is ours for Xero and QBO, mirrored from NetSuite. Write-back is capability-gated and hidden where the capability is false.

Only NetSuite models goods receipt as a record and reconciles quantity and price across PO, receipt and bill. QBO offers a link between a bill and a purchase order, with no receipt and no variance; Xero's API exposes no bill-to-PO link at all, only a purchase order whose Status has moved to BILLED.

Do — The match component computes the variance itself for QBO, from whatever quantities the linked documents carry, and labels it as our calculation rather than the ledger's. For Xero there is no link to compute from: any PO-to-bill pairing is ours, proposed and confirmed by the user.

Settling five invoices with one bank receipt is one payment with five allocations on QBO and NetSuite, and five Payment records on Xero. Xero accepts them in one call — PUT /Payments takes an array, and BatchPayments settles many invoices at once — but with summarizeErrors=false each item succeeds or fails on its own. Three of five succeed and the ledger holds a half-applied receipt that reconciles to nothing.

Do — Write Xero payments through a job with a stable idempotency key, and check the result of every allocation in the response. The payment is not 'recorded' until every allocation succeeds; show a partial state honestly when it does not.

Xero splits it into Overpayment (the customer paid too much against an invoice) and Prepayment (they paid before an invoice existed), each with its own endpoint. Neither appears in /Invoices. An AR figure built from invoice balances alone disagrees with Xero's own aging report by exactly the unapplied amount.

Do — Fetch both endpoints, model them as documents with no lines, and give unapplied cash its own row in the aging table. Tie to the ledger's aging report and surface any variance.

It emits the actual general ledger — every posting from invoices, payments, bills, bank transactions and manual journals — as immutable, sequentially numbered records. Paginate by offset on JournalNumber and you have an append-only, gapless, perfectly replayable ledger feed.

Do — Anything that reconciles or re-derives statements builds on /Journals, not on /Invoices. Store the highest JournalNumber seen as the sync cursor; it never goes backwards. Since 2 March 2026 Xero reserves the endpoint for apps on its Advanced partner tier that have passed a security assessment and had the use case approved — so make hasGlFeed a capability you discover, and keep a reconstruct-from-documents fallback for apps without it.

From 2 March 2026 the Journals endpoint is available only from the Advanced tier of Xero's developer pricing, and only after an initial and annual security assessment and use-case approval. ManualJournals stays open on every tier, but it holds only the journals people typed — not the postings that invoices, payments and bank transactions generate.

Do — Treat Journals access as a per-app capability, not a property of Xero. Without it, statements are reconstructed from documents and tied to the Reports endpoints, exactly as on QBO, and the provenance label says so.

There is no way to ask QBO for postings. Your three options are the Reports API (correct totals, presentation-shaped rows, no stable ids), reconstructing postings from every transaction entity (you then own the correctness of Intuit's tax and FX posting rules, forever), or mirroring entities via change data capture and deriving statements from the mirror.

Do — Reports API for tie-out, an entity mirror for detail. Display which one produced the number; the two will occasionally disagree.

Under automated sales tax you cannot create tax rates through the API, and the tax on a transaction is computed by Intuit from the addresses on it. Amounts you send may be silently replaced. Outside the US, GlobalTaxCalculation and explicit tax codes behave the way Xero's do.

Do — Expose canCreateTaxRates as a capability. The tax UI is read-mostly where it is false, and the write path does not promise a tax amount it cannot guarantee.

A custom segment creates a field whose key is defined by the customer — cseg_product, cseg_channel, cseg_whatever. Two NetSuite accounts have different dimension schemas. No type literal in your code can name them.

Do — Fetch the customsegment metadata at connection time, store it as a Dimension[], and drive every filter, group-by and column from that list.

A client who wants department and project and location on Xero cannot have all three. There is no plan, no setting and no workaround inside Xero's tracking model.

Do — Say so, rather than offering a control that cannot be saved. A third dimension lives in our system, applied at the reporting layer and marked as ours.

Xero and QBO have cut-off dates — two in Xero, whose effect on an API write depends on the connected user's role. There is no object that says 'August 2026 is closed', no state, no history of when it closed, and no per-module or per-entity granularity. Everything a close checklist needs to track exists nowhere in the source.

Do — Period state is owned by our system, with the ledger's lock date as one input signal. The close checklist writes to us; the lock date is a check we run against them.

There is no endpoint for change history and no actor on any record. If a bookkeeper edits an invoice in QuickBooks, you will see a new LastUpdatedTime and nothing else — not what changed, not who changed it, not what it was before.

Do — Keep a before-and-after for every change we make and snapshot watched fields on every sync, so a diff can be reconstructed. Present it as our record, not the ledger's.

Header, section and summary rows are interleaved with data rows, nesting depth carries meaning, and identity is inconsistent. Parsing is possible; drilling from a parsed row back to the transactions behind it generally is not.

Do — Build interactive statements from ledger data. Use the report endpoint on a schedule, assert equality, and surface a variance when it appears.

A group on Xero or QBO is n disconnected tenants. You own the entity tree, the intercompany elimination and the currency translation. On NetSuite all three exist already, and ignoring them produces double-counted intercompany revenue.

Do — Own the entity tree in your schema. Map NetSuite subsidiaries into it rather than adopting them as the tree, so a mixed group — two Xero orgs plus a NetSuite subsidiary, which is common — still has a coherent parent.

GET /record/v1/invoice returns a page of { id, links } objects. Fetching 5,000 invoices that way is 5,001 calls against a concurrency limit in the single digits. This is not an optimisation problem; it is the difference between a sync that finishes and one that does not.

Do — Use SuiteQL for every bulk read. Reserve the REST record service for single-record reads and for writes.

Xero never truly deletes — it flips a status, so a delta sync sees it. QBO surfaces deletes only through change data capture, which looks back 30 days at most, so a poll-only integration — or one that was offline for a month — accumulates ghost records forever. NetSuite hard-deletes and the record simply stops existing.

Do — Poll for changes, but reconcile the id set periodically: fetch all ids for a window and mark anything missing as gone. Without that pass, aging reports quietly include documents that no longer exist.

POST an Invoice with only the fields you meant to change and every line on it disappears. The call succeeds. The invoice is now empty and the customer's balance has moved.

Do — Read the current record, mutate it, write the whole thing back with the current SyncToken — or use sparse updates and accept their narrower semantics. A SyncToken mismatch is a real user-visible outcome, not a retryable error: someone else changed the record.

A user event script, a workflow condition, a mandatory custom field or a subsidiary restriction can reject a payload that is structurally perfect. The error text often names an internal field id and nothing else.

Do — Surface the raw NetSuite error to the operator, not a rewritten message. Keep the payload alongside it so support can reproduce. Never retry a rejection automatically.

The substitutes are a user event SuiteScript that calls out on save — which puts your endpoint's availability in the path of the customer's ability to save a record — or scheduled polling on lastmodifieddate.

Do — Poll by default. Offer the script only where the customer's own team maintains it, and never let a callout block a save.