Connecting Xero
Last updated: October 6, 2026
Stackpack supports a read-only integration with Xero that pulls supplier spend into Stackpack. This builds your vendor list automatically and keeps each vendor's spend history current. Stackpack never writes to Xero.
For what Stackpack keeps from your accounting system, and what it does not, see What Stackpack stores from your accounting system.
Authentication
Stackpack connects through Xero's OAuth 2.0 flow and requests only the read scopes it needs: invoices, payments, bank transactions, manual journals, contacts, and organisation settings. You sign in to Xero, choose the organisation to share, and authorize Stackpack. Xero issues Stackpack a token scoped to that organisation; Stackpack never sees your password.
Requirements
A Xero user with the Standard or Adviser role for the organisation. Xero only lets these roles connect apps.
Select exactly one organisation on the Xero consent screen. An authorization covering more than one organisation cannot be used; Stackpack asks you to reconnect and choose a single one.
Each Xero organisation is a separate profile in Stackpack. Connect once per organisation.
Caveats
Stackpack currently operates in USD. Amounts are read as recorded on each Xero document and are not converted, so organisations with non-USD documents will see those amounts summed as-is. Multi-currency support is on our roadmap.
Xero tokens lapse after 60 days without use. Stackpack syncs daily, which keeps the token alive. But if syncing is paused for that long, or the authorizing user loses access to the organisation, the profile must be reconnected.
Xero has no fixed class or department dimension, so Stackpack uses your Tracking Categories. The first tracking category is read as Class and the second as Department. Populating Stackpack Departments from either is enabled by a switch on your account; ask your Stackpack contact to enable it.
Xero Manual Journals carry no contact, so they contribute no vendor spend. Accruals and amortisation booked as manual journals are not visible to Stackpack.
Connecting
During onboarding
On the "Sync with Xero" step, click Connect to Xero.
Sign in to Xero, select one organisation, and click Allow access.
You are returned to Stackpack and the first sync starts immediately.
From Company Settings
Go to Company Settings → Integrations → Xero and click Connect (or Add profile if a profile already exists).
Enter a name for the profile. This is how the connection appears in Stackpack.
Click Connect, sign in to Xero, select one organisation, and allow access.
Reconnecting re-runs the Xero authorization for an existing profile and restores syncing without changing any synced data. Use it when Stackpack reports the profile needs attention.
Disconnecting revokes Stackpack's token with Xero and removes the profile. You can also disconnect from Xero under Settings → Connected Apps. Either path stops syncing.
Sync schedule and window
The first sync runs when you connect. After that, Stackpack syncs automatically once a day.
Stackpack retains spend for the current calendar year plus the two prior calendar years. (During January through March, one additional prior year is retained so year-over-year comparisons remain available.)
Each sync re-reads the months since the previous sync, and the prior quarter is fully refreshed at the start of each new quarter. Late payments, edits, voids, and credit notes are therefore picked up and applied to the correct month.
Xero limits each organisation to 5,000 API calls a day. A very large organisation's first sync may stop at that limit and resume the next day.
What Stackpack reads from Xero
Reference lists: Chart of Accounts, Contacts, Tracking Categories, and the Organisation (for its base currency).
Documents, filtered by document date. Stackpack records spend from the vehicle that moved money (a payment or bank transaction) rather than from the paperwork describing what was owed, which keeps the same money from being counted twice. One entry is recorded per document line, so a bill split across three accounts produces three entries.
Xero document | Included when | Recorded as | Notes |
|---|---|---|---|
Bill (Accounts Payable invoice) with payments | Status is Awaiting Payment or Paid | Bill | One entry per payment, for the amount paid, dated by the payment date and apportioned across the bill's lines. A part-paid bill accrues spend as it is settled. |
Bill with nothing applied | Status is Awaiting Payment | Bill | Recorded in full at the bill date, since the bill is the only evidence of the spend. |
Spend Money bank transaction | Status is Authorised | Expense | Direct spend with no bill behind it. Dated by the transaction date. |
Bill Credit Note with a refund | Status is Awaiting Payment or Paid, and cash was refunded | Vendor Credit | Recorded for the refunded amount, negative, dated by the refund date. |
Prepayment or Overpayment to a supplier | Not voided | Expense, plus accrual entries | The cash out is recorded on the payment date. In the accrual view the amount is deferred on that date and recognised on each date it is applied to a bill. |
The following are read but deliberately not recorded as spend:
Bills settled without cash: a bill with a credit note, prepayment, or overpayment applied and no payment. The settling document is the record of that spend.
Credit notes applied to bills. They move no money; they reduce a future payment, which is recorded on its own.
Draft, Awaiting Approval, Voided, and Deleted documents.
Manual Journals, which have no contact to attribute to.
Customer-side documents: sales invoices, customer credit notes, Receive Money transactions, and customer prepayments or overpayments.
Line-level exclusions. A line is skipped when any of the following is true:
Its document has no date.
Its document has no contact.
Its amount is zero.
Its account is in the Asset, Equity, or Revenue class. Expense and Liability accounts (which cover accounts payable and credit cards) are included. Prepayment and overpayment lines are exempt, since they legitimately post to balance-sheet accounts.
Its account is on the profile's excluded GL account list, if your Stackpack administrator has configured one.
Fields captured per document line
Field | Xero source |
|---|---|
Transaction ID | Document ID, payment or allocation ID where applicable, and line ID |
Date | Payment date for paid bills and refunds; document date otherwise; allocation date for prepayment recognition |
Amount | Line amount, or the line's share of a payment, refund, or allocation. Negative for refunds and prepayment deferrals. |
Currency | Document currency, falling back to the organisation's base currency |
Type | Bill, Expense, Vendor Credit, or Journal Entry (Debit or Credit) |
Accrual | Set for prepayment deferral and recognition entries |
Memo | Reference, document number, and payment reference, then the line description, joined with |
Account category | The account's Type (for example EXPENSE, OVERHEADS, CURRLIAB) |
Account ID and name | The account on the line, matched by account code |
Class ID and name | Option of your first Tracking Category on the line |
Department ID and name | Option of your second Tracking Category on the line |
Location ID and name | Not populated for Xero |
Vendor ID and name | The Contact on the document |
How documents become vendor spend
Stackpack groups the captured lines by vendor, matching on the Xero Contact ID. Within each vendor, lines are grouped by the calendar month of their date. Each vendor then carries a monthly spend time series, one bucket per month, with:
Monthly spend field | Derived from |
|---|---|
Year and month | The line date's calendar month |
Amount | Sum of Bill, Expense, and Vendor Credit line amounts for that month. Refunds reduce the total. |
Transaction count | Number of those lines in that month |
Accrual amount | Prepayment recognition debits, offset by prepayment deferral credits |
Alongside the time series, each vendor records the accounts its lines posted to (each with a line count), the earliest month with spend in the retained window, and the most recent month with spend. When the Department or Class switch is enabled, the vendor also records the tracking options it posted to, and Stackpack keeps a per-department monthly spend series keyed on the second tracking category's option, falling back to the first when the second is not set.
Spend views in Stackpack use Amount by default. If accrual-based spend is enabled for your company, vendors with prepayment activity show Amount + Accrual amount, which spreads a prepayment across the months it was applied in rather than the month it was paid. Vendors without prepayment activity continue to show Amount.
Monthly buckets older than the retention window are dropped on each sync. Buckets inside the window are replaced by the latest sync, so corrections in Xero flow through rather than accumulate.
Frequently asked questions
Q: What does the Xero integration involve, and what information does Stackpack pull from Xero?
A Xero Standard or Adviser user authorizes Stackpack for one organisation. From then on Stackpack reads, once a day, your supplier-spend documents: bills and the payments against them, Spend Money bank transactions, refunded bill credit notes, and supplier prepayments and overpayments. It also reads your Chart of Accounts, Contacts, and Tracking Categories to label those documents. Stackpack keeps the current year plus two prior years and never writes to Xero.
Q: Which specific data points or fields are required for the integration?
Each document needs a date, a Contact, and a non-zero amount, and each line needs an account in the Expense or Liability class. Lines missing any of these are skipped. Tracking categories, references, and line descriptions are optional and enrich the vendor record when present.
Q: Are there any data or configuration prerequisites we should validate before starting the trial?
The connecting user has the Standard or Adviser role and selects a single organisation on the consent screen.
Supplier spend is recorded against Contacts, and contact names are consistent (one Contact per supplier avoids split spend).
Bills you want counted are approved (Awaiting Payment or Paid), not Draft or Awaiting Approval.
Expense accounts are in the Expense class and payable and credit card accounts in the Liability class. Spend posted to Asset, Equity, or Revenue accounts is not read.
If you want Classes or Departments in Stackpack, your first and second Tracking Categories are the ones you want in those roles, and you have asked Stackpack to enable the matching switch.
Your books are in USD. Non-USD documents are summed without conversion.
Q: Why does a bill's spend appear on the payment date rather than the bill date?
Stackpack records spend from payments, so a paid bill lands in the month it was paid, and a part-paid bill lands in pieces as it is settled. A bill with nothing applied yet is recorded in full at the bill date so it is not invisible while awaiting payment.
Q: Why is a credit note not reducing my spend?
A credit note applied to a bill moves no money; it reduces the payment eventually made, which is what Stackpack records. Only credit notes that were actually refunded in cash appear as negative spend.
Q: We use Tracking Categories for regions and departments. How do they map?
Xero allows two active tracking categories. Stackpack reads the first as Class and the second as Department. If the order is not what you want, tell your Stackpack contact during onboarding.
Q: We have several Xero organisations. How do we connect them all?
Connect each organisation as its own profile from Company Settings → Integrations → Xero → Add profile, selecting a single organisation each time on the consent screen.
Q: Can we exclude certain accounts, such as payroll or taxes?
Yes. Your Stackpack administrator can set an excluded GL account list per profile, by account ID or name. Lines posted to those accounts are skipped on the next sync.
Q: Why is a vendor's spend different in Stackpack than in Xero?
The usual causes are draft or awaiting-approval bills, bills settled by credit note or prepayment rather than cash, lines posted to Asset, Equity, or Revenue accounts, accounts on your excluded GL account list, manual journals (never read), and refunds netting against spend. Spend is also dated by the payment date, so a bill dated in one month and paid in the next appears in the payment month.