What does an accounts-receivable invoice look like in each API? Three payloads, one journal. Xero posts a line to an account; QuickBooks posts it to an item that points at an account; NetSuite posts it to an item sublist with a segment set. And QuickBooks has no status field at all.
Xero
GET /Invoices?where=Type=="ACCREC"
Shared with bills — the filter is mandatory
QBO
SELECT * FROM Invoice
Its own entity
NetSuite
SuiteQL: FROM transaction WHERE type='CustInvc'
REST /record/v1/invoice for single records
Read across a row. Where a cell is absent, the concept has nowhere to live in that system — which is a design constraint, not a gap to paper over.
A difference stated without a response is trivia. Each of these carries the handling.
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.
You cannot post a QBO invoice line directly to an income account — the line references an Item, and the item carries the account. Creating invoices from a source that only knows accounts means resolving or creating a service item per account, and that item then lives in the customer's product list permanently.
Do — Maintain a small, explicitly named set of integration items rather than creating one per account on the fly. Show the user which item a line will use before the first write.
Xero always puts tracking on the line. QBO puts Department on the header and Class on either, depending on a company preference. NetSuite allows both and lets the line override the header.
Do — Fan header values down to every line at normalisation and record that you did, so an edit UI does not write per-line values back to a system that cannot store them.
Stacked rather than tabbed — a reader comparing two shapes should not have to hold one of them in memory.
Xero — account-based line, tracking on the line
{
"Type": "ACCREC",
"Contact": { "ContactID": "0c1f…" },
"Date": "2026-09-07",
"DueDate": "2026-10-07",
"LineAmountTypes": "Exclusive",
"LineItems": [{
"Description": "Consulting",
"Quantity": 1,
"UnitAmount": 1000,
"AccountCode": "200",
"TaxType": "OUTPUT2",
"Tracking": [{ "Name": "Department", "Option": "R&D" }]
}]
}QBO (non-US) — item-based line, numeric tax code, department on the header
{
"CustomerRef": { "value": "58" },
"TxnDate": "2026-09-07",
"DueDate": "2026-10-07",
"GlobalTaxCalculation": "TaxExcluded",
"DepartmentRef": { "value": "3" },
"Line": [{
"DetailType": "SalesItemLineDetail",
"Amount": 1000,
"SalesItemLineDetail": {
"ItemRef": { "value": "12" },
"Qty": 1,
"UnitPrice": 1000,
"TaxCodeRef": { "value": "8" }
}
}]
}NetSuite — item sublist, segments per line, subsidiary on the header
{
"entity": { "id": "58" },
"trandate": "2026-09-07",
"duedate": "2026-10-07",
"subsidiary": { "id": "2" },
"item": { "items": [{
"item": { "id": "12" },
"quantity": 1,
"rate": 1000,
"taxcode": { "id": "5" },
"department": { "id": "7" },
"cseg_product": { "id": "3" }
}] }
}type LedgerDocument = {
id: string;
type: "sales_invoice" | "purchase_bill" | "sales_credit" | "purchase_credit"
| "cash_sale" | "cash_purchase" | "journal";
number?: string;
party?: Party;
issueDate: string; // calendar date, no time, no zone
dueDate?: string;
currency: string;
exchangeRate?: string;
total: Money;
totalBase?: Money; // from the source — never recomputed as amount × rate
outstanding: Money;
/** Ours. Derived where the source has none. */
status: "draft" | "awaiting_approval" | "open" | "part_paid" | "paid" | "voided" | "voided_or_zero" | "deleted";
statusIsDerived: boolean;
sourceStatus?: string; // theirs, for the tooltip
lines: DocumentLine[];
allocations: Allocation[];
periodId?: string;
source: SourceRef;
};
/** QBO status is computed, never read. One function, one place. */
function qboInvoiceStatus(inv: QboInvoice, today: string): DocumentStatus {
if (inv.PrivateNote?.startsWith("Voided")) return "voided"; // voided invoices keep TotalAmt 0
if (inv.TotalAmt === 0 && inv.Balance === 0) return "voided_or_zero"; // a legitimate $0 invoice looks the same
if (inv.Balance === 0) return "paid";
if (Number(inv.Balance) < Number(inv.TotalAmt)) return "part_paid";
if (inv.DueDate && inv.DueDate < today) return "open"; // overdue is a view, not a status
return "open";
}The payoff. Every difference above that reaches the surface, and what the component does about it.
The normalised object above is what the components read. These are the surfaces it feeds, the words for the concepts in it, and the document that explains the accounting.
Compared acrossXero docsQuickBooks Online docsNetSuite docs