Xero Integration

Use Xero Integration to connect a NexWave Company to Xero, push invoices and credit notes, and pull supported payments back into NexWave.

This guide is for finance administrators who maintain the connection, account mappings, tax mappings, bank mappings, and sync review process. It covers setup, verification, recovery, and the checks to run after the connection is live. The setup below applies to connector version 1.1.0.

Before you start

Confirm these items before you connect a Company to Xero:

• You can sign in to the correct Xero organisation and authorise connected apps.

• You have permission in NexWave to manage Xero Connection, invoices, Payment Entries, accounts, tax templates, and Modes of Payment.

• The NexWave Company and the Xero organisation use the same base currency.

• The NexWave Company, chart of accounts, tax templates, company Bank Accounts, bank or cash ledger accounts, and Modes of Payment are already set up.

• You know which NexWave account should map to each Xero account used on invoices, payments, discounts, charges, and rounding.

• You know which tax templates and tax accounts should map to the Xero tax rates used for sales and purchases.

• You know which Xero bank accounts should create or match NexWave Payment Entries.

• One NexWave user will own the connection and can reconnect it when consent must be renewed.

• A System Manager is available to manage the connection and check payment-pull recovery settings. These screens require that role by default.

If you are setting up a production connection, complete the mapping review with the finance team before you enable payment pull.

What the integration does

The Xero Integration keeps key accounting transactions aligned between NexWave and Xero:

• Submitted Sales Invoices, Purchase Invoices, and credit notes are pushed from NexWave to Xero.

• Cancelled invoices are voided in Xero where the matching Xero invoice can still be voided.

• Contacts are created in Xero when an invoice is pushed and the matching contact does not already exist.

• Supported payments against one invoice in Xero can be pulled back into NexWave as Payment Entries. Import does not wait for bank reconciliation in Xero.

• Existing submitted NexWave Payment Entries can be matched when they refer to one invoice, have no existing Xero Payment ID, and match the allocation and bank settlement within the matching tolerances. Their Posting Date can be up to three days before or after the Xero payment date. An unallocated advance needs manual review.

• Exceptions and pull-cycle results are recorded in Xero Sync Log for review.

The integration does not pull invoices created directly in Xero into NexWave. NexWave should remain the source for invoices that need to be managed in NexWave.

Xero integration overview: invoice push, payment import, and payment deletion

Open the NexWave Xero workspace

System Managers can open NexWave Xero from the workspace sidebar. The workspace keeps the connection, transactions, and setup lists together. Each linked list keeps its normal permissions.

NexWave Xero workspace with Quick Access and the three setup and transaction groups

The example contains earlier test logs. Use the error and review shortcuts to inspect the records behind each count.

Create or open the Xero Connection

1. In NexWave Xero, open Xero Connections.

2. Create a new connection, or open the existing connection for the Company.

3. Set Company when you create the connection.

4. Select the correct Connected App.

5. Leave Enabled unticked until the connection and mappings are ready.

6. Save the document.

Use one Xero Connection for each Company. If the Company already has a connection, open that record. Company remains visible as a read-only link after saving. You cannot reassign a saved connection to another Company; create a separate connection instead.

Saved connection showing Company, Connected App, Connected User, Xero Organisation, and OAuth Status

This saved example connects a demo NexWave Company to Demo Company (NZ). Check the organisation and currency for your own connection. Ask NexWave Support to review an organisation change before you use it for existing transactions.

Connect NexWave to Xero

1. Open the Xero action group.

2. Click Connect to Xero.

3. Sign in to Xero and authorise access to the correct organisation.

4. Return to NexWave and click Fetch Tenant ID.

5. If more than one organisation is available, choose the correct value in Select Organisation, then click Connect. When names are the same, check the organisation ID shown with each choice.

6. Save the connection.

7. Confirm that OAuth Status shows Connected.

8. Confirm that Connected User and Xero Organisation are correct.

9. Click Test Connection.

10. In the result, confirm that Organisation and Base Currency match the intended Company.

If the test fails, read the error and follow the connection-recovery steps below. Do not complete mappings against the wrong Xero organisation. Fetch Tenant ID remains available when an organisation is already saved, so you can check the current authorised choices.

Successful Xero connection test showing Demo Company NZ, country NZ, and base currency NZD

In this demo result, Organisation is Demo Company (NZ) and Base Currency is NZD. Check both values before continuing with mappings.

Fetch and map Xero accounts

1. In the Xero action group, click Fetch Chart of Accounts.

2. Review the rows in Xero Accounts.

3. For each account used by invoices, payments, discounts, charges, write-offs, or rounding, set NexWave Account.

4. Check Account Code, Account Name, and Account Type before you save.

5. Save the connection.

NexWave first uses an account mapping that you set. Without an explicit mapping, it compares the NexWave account's Account Number with Account Code in the fetched Xero Accounts. If neither route finds a match, the invoice sync fails and records the cause for review. It does not choose a general default account. Correct the mapping or account number before retrying.

Use the same finance review process that you use for normal chart of accounts changes. A wrong mapping can send invoice lines, charges, or payment values to the wrong ledger account in Xero.

Expanded sales account mapping showing Xero account code 200 and the selected NexWave sales ledger account

This row maps the selected NexWave Account to Xero Account Code 200. Compare Account Name and Account Type before using the mapping.

Fetch and map Xero tax rates

1. Click Fetch Tax Rates.

2. Review Sales Tax Mappings and Purchase Tax Mappings separately.

3. For each mapped tax rate, set the relevant Tax Account.

4. Set Item Tax Template where item-level tax selection is used.

5. Set Tax Template where invoice-level tax templates are used.

6. Save the connection.

An Item Tax Template on a line takes priority. If the line has no item template, NexWave uses the invoice's Sales Taxes and Charges Template or Purchase Taxes and Charges Template selection through the mapped Tax Template. You do not need to repeat the normal invoice tax template on every line. Use an item template where a line needs different tax treatment. If neither template resolves the tax type, NexWave checks the invoice's first tax account against Tax Account. Once tax mappings are configured, an explicit item template without a matching mapping fails the sync instead of falling back to the invoice template.

The same Xero Tax Type can appear on several rows when those rows map different NexWave tax templates to the same Xero rate. Review the templates on each row before treating it as an unwanted duplicate.

Test the GST, exempt, and zero-rated combinations that the Company will use. If a tax rate is not used by the Company, leave it unmapped until it is needed.

Expanded sales tax mapping with OUTPUT2 and both item and invoice tax templates

The sales example maps both an Item Tax Template and an invoice-level Tax Template to OUTPUT2. A normal invoice line can use the invoice template without its own item template.

Expanded purchase tax mapping with INPUT2 and both item and invoice tax templates

Review purchase mappings separately. This purchase example uses INPUT2 for GST on expenses, with the relevant item and invoice templates.

Fetch and map bank accounts

Payment pull needs bank mappings so each Xero payment uses the correct NexWave settlement account. Complete this section before you enable Pull Payments from Xero. Invoice push alone does not require bank mappings.

1. Click Fetch Bank Accounts in the Xero action group.

2. Set Default Mode of Payment once for the connection. It is used for imported payments unless a row has an override.

3. In Xero Bank Accounts, open each row and check Xero Account Code, Xero Account Name, and Xero Currency.

4. Select the corresponding NexWave Bank Account. It must be an enabled company Bank Account for the connection's Company, with an enabled bank ledger account linked to it. Do not select a customer or supplier Bank Account.

5. Check GL Account and GL Account Currency. They are filled from the selected Bank Account and are read-only while that Bank Account is selected. The ledger currency must match Xero Currency.

6. Leave Mode of Payment Override blank to use the connection default. Select an enabled Mode of Payment there only when that bank needs a different method.

7. Save the connection.

Saved Xero bank mappings with Default Mode of Payment and the payment import setting

This saved example uses a connection default. A row can use its own override without changing the default for the other banks.

Expanded bank mapping row showing the selected company Bank Account, derived GL Account and currency, and optional Mode of Payment Override

In this row, the Bank Account supplies the ledger account and NZD currency. The empty override uses Default Mode of Payment.

For a cash account or a bank without a Bank Account record, leave NexWave Bank Account blank and select an enabled, non-group Bank or Cash account in GL Account. Check the currency and provide a Mode of Payment through the connection default or the row override.

Every fetched row must resolve to a valid settlement account and Mode of Payment before payment pull can be enabled. You can save incomplete fetched mappings while payment pull is off. Fetching the same banks again retains their Bank Account selections, GL-only selections, and payment-method overrides.

The selected bank and ledger account serve both customer receipts and supplier payments. New imported Payment Entries retain the selected company Bank Account. Their Account Paid To or Account Paid From uses the mapped ledger account, according to the payment direction. A GL-only mapping has no Bank Account record to store.

Enable the connection and payment pull

Enable the connection only after the account and tax mappings are ready. Enable payment pull only after the bank mappings are also ready.

1. Open the Xero Connection.

2. Tick Enabled.

3. Confirm that every row in Xero Bank Accounts has a valid NexWave Bank Account or GL-only mapping, matching currency, and an effective Mode of Payment from the default or row override.

4. Tick Pull Payments from Xero when Xero will own the supported payment flow.

5. Save the connection.

NexWave checks the bank mappings when you save. If a required mapping is missing, complete the mapping before you enable payment pull. You can still untick Pull Payments from Xero or Enabled when a bank mapping is invalid or Xero authorisation is unavailable.

The first pull requests payments changed in Xero since payment pull was enabled. This uses the time of the change in Xero, not the payment date. An older payment changed after that time can therefore be imported. Review existing payments and agree the cutover with the finance team. The connector does not import all payment history.

Once a local Payment Entry is matched to a Xero payment, deletion of that payment in Xero can cancel the linked NexWave Payment Entry. This applies to both imported and matched local entries. Confirm that the finance team accepts this payment ownership before you enable the flow.

Verify invoice and credit note push

Use a test NexWave Company connected to a Xero test or demo organisation for invoice, credit note, cancellation, and payment-deletion tests. Confirm the test organisation with Test Connection before you submit sample transactions. For the production pilot, use approved business transactions.

1. Submit a Sales Invoice or Purchase Invoice in NexWave.

2. Open the invoice and check Xero Sync Status.

3. In Xero, confirm that the invoice was created in the correct organisation.

4. Check the invoice number, contact, account, tax, total, and currency in both systems.

5. If the Company uses rounding or separate charges, confirm that the final payable total agrees.

6. Repeat the check with a credit note and an invoice cancellation before you expand the pilot.

Matching Xero invoice showing its invoice number and Paid status

The same demo Sales Invoice appears as Paid in Xero.

Matching Xero invoice contact, issue date, due date, and full invoice number

Xero invoice subtotal, GST, total, payment, and zero amount due

The invoice number and customer agree with the NexWave example. Xero shows a subtotal of NZD 420, GST of NZD 63, and a total of NZD 483. Its recorded payment is NZD 483 and Amount due is zero.

For Sales Invoices, confirm that the customer purchase order reference appears correctly where it is used. For Purchase Invoices, confirm that the supplier invoice number appears correctly where it is used.

For a credit note that should reduce the original invoice balance, also confirm its allocation in Xero. A Synced status confirms creation, but does not prove that allocation succeeded. Read the credit note comments. If allocation failed, review the existing credit note with the finance team and complete the allocation in Xero as needed.

Check the connection saved on an invoice

After a successful invoice or credit-note sync, open its Xero section. The following read-only values identify where that transaction was sent:

These values apply to Sales Invoices and Purchase Invoices, including credit notes. Later connection changes do not replace the saved transaction identity. Retries, cancellation, linked credits, and payment matching check that identity before using the remote transaction. If access to the original organisation is missing, review the error instead of using the connection's replacement organisation.

Amending an invoice starts a new document without copying the original Xero identity. Older synced invoices can have no saved Xero Connection or Xero Organisation ID. They require review before further remote operations; do not fill those values from the current connection without evidence.

Older demo invoice showing its Xero Invoice ID and Synced status

This older demo invoice has a Xero Invoice ID and a Synced status. Its Xero Connection and Xero Organisation ID are empty. Empty read-only fields can be hidden on an older record. New successful syncs store all four values in the table above.

On a Purchase Invoice, Is Opening Entry remains in More Info > Accounting Details, outside the Xero section. Collapsing Xero does not hide the accounting fields.

Purchase Invoice More Info showing Is Opening Entry in Accounting Details while Xero is collapsed

The accounting setting remains visible in this example while the separate Xero section is collapsed.

Recover a queued or failed invoice

Use the invoice status and saved Xero identity to select the safe recovery action.

Invoice sync and recovery: status and Xero ID conditions for retry

After a retry, refresh the invoice and confirm the final Xero Sync Status. Then check that there is one matching invoice or credit note in Xero.

Verify payment pull

After payment pull is enabled, verify the first payment with a simple single-invoice payment.

1. Record a payment against one invoice in the Xero test organisation. Complete bank reconciliation according to the agreed process, but do not use it as a condition for payment import.

2. Wait for the next hourly payment pull cycle.

3. In NexWave, open the invoice and confirm that a Payment Entry was created or matched.

4. Check that the Payment Entry is submitted and linked to the correct invoice. Check Mode of Payment, Company Bank Account for a Bank Account mapping, and Account Paid To or Account Paid From for the settlement account.

5. Review Xero Payment ID, Xero Sync Status, and Xero Pull Log on the Payment Entry where those fields are visible.

6. Review the invoice outstanding amount, customer or supplier ledger, and ageing report.

Payment import and deletion: created entries, matched entries, exceptions, and cancellation

Example customer receipt

These are existing demo imports. They show the settlement accounts, full invoice allocations, and Xero payment fields. The Company Bank Account link is empty on these older entries. New imports that use a Bank Account mapping also store that link.

Imported customer receipt showing Receive payment type, payment method, bank settlement account, and NZD 483 paid amount

Here Payment Type is Receive. Account Paid From is the customer receivables account, and Account Paid To is the bank ledger account.

Expanded customer receipt reference showing the full sales invoice number, NZD 483 allocation, and zero outstanding amount

Open the reference row to see the full invoice number. The NZD 483 allocation agrees with the invoice total, and the remaining outstanding amount is zero.

Customer receipt Xero section showing payment ID, Pulled status, pull log link, and Xero Pull source

Xero Payment ID identifies the remote payment. Xero Sync Status is Pulled, Xero Payment Source is Xero Pull, and Xero Pull Log opens the corresponding import log.

Example supplier payment

Imported supplier payment showing Pay payment type, payment method, bank settlement account, and NZD 759 paid amount

For Payment Type Pay, the direction is reversed: Account Paid From is the bank ledger account and Account Paid To is the supplier payables account.

Expanded supplier payment reference showing the full purchase invoice number, NZD 759 allocation, and zero outstanding amount

Check the Purchase Invoice reference and supplier invoice number. This example allocates the full NZD 759 and leaves no outstanding balance.

Supplier payment Xero section showing payment ID, Pulled status, pull log link, and Xero Pull source

Use the supplier payment's own Xero Payment ID and Xero Pull Log when checking its import or a later payment deletion.

Supported payments and ownership

Record supported payments in Xero for this flow. Locally created Payment Entries are not sent to Xero. A repeated pull keeps one Payment Entry for each imported payment.

The current automated flow supports payments that settle one invoice. Batch payments, multi-invoice payments, overpayments, prepayments, credit note offsets, and bank-fee deductions need manual handling. A bank-fee mismatch can appear as an error rather than a specific manual-review reason. Read the error details. Do not create a second local payment to compensate for an import delay.

Payments between two different foreign currencies are not supported. For supported foreign-currency settlements, check the invoice allocation, bank amount, exchange difference, and remaining invoice balance. Some settlements require the Company's Exchange Gain / Loss Account and Default Cost Center to be set.

Review Xero Sync Log

From NexWave Xero, use Sync Errors and Manual Review for the filtered review lists, or open Sync Logs for all results. Xero Sync Log is the main review screen for sync issues.

Recommended filters:

• Xero Connection: use this when multiple Companies are connected.

• Status: review Error and Manual Review first.

• Operation: select the part of the flow that failed.

• Reference DocType and Reference Name: use these when you know the invoice or Payment Entry.

Xero Sync Log list filtered to Error and narrowed to one historical demo entry

This example filters Status to Error and narrows ID to one historical demo entry. Open the record to read the complete operation, connection, and error details.

For a payment-pull cycle, check Operation for Pull Cycle Start, Pull Cycle Complete, or Pull Cycle Failed. A completed scheduler dispatch does not prove that a payment was imported. Confirm the Payment Entry and invoice balance as well.

Fields that usually explain the issue:

• Manual Review Reason

• Error Message

• Payload

• Request Data

• Response Data

Use the log to understand the failed operation before you make corrections in either system. Keep tokens, credentials, and private record details out of shared evidence.

Historical Pull Cycle Failed log showing Error status, connection, and the authentication recovery message

This historical Pull Cycle Failed record says that Xero authorisation was unavailable. Error Message directs the operator to reconnect. The successful connection-test example earlier in this guide shows the later result. Keep the error log as part of the sync history.

Handle payment pull exceptions

Some Xero payments are intentionally not automated because they need a finance decision.

Most manual-review cases need an operator decision. Do not assume that the next cycle will process them automatically. A missing bank mapping and some settlement errors retain the pull position and can retry after correction.

Recover a failed pull cycle or connection

Do not change the pull cursor to force a rerun. If a pull cycle remains failed after you correct the cause and the retry time passes, ask NexWave Support to review the connection, cycle time, status, and error summary.

Xero connection action menu showing Reconnect to Xero, Fetch Tenant ID, and Test Connection

Open Xero on the connection to find Reconnect to Xero, Fetch Tenant ID, and Test Connection. This menu is from a connected record; the available actions depend on its saved state. Invoice Retry Xero Sync and Retry Xero Void actions also depend on the invoice state described in the recovery table.

Reconnect or change the authorised organisation

After reconnecting an enabled connection, save the Xero Connection. NexWave checks the saved organisation against the organisations currently authorised by Xero. It retains an authorised selection. If its old ID is no longer authorised and exactly one authorised organisation has the same name, saving refreshes the organisation ID. For an unrelated or ambiguous replacement, use Fetch Tenant ID and select the intended organisation explicitly. If Enabled is unticked, use Fetch Tenant ID to check and select the organisation; saving a disabled connection skips the automatic authorisation check.

A changed organisation pauses payment pull, clears the old bank mappings, and resets the old payment import position and retry delay. If an import is already running, wait for it to finish before changing the organisation.

After an organisation change:

1. Use Test Connection and confirm the organisation and base currency.

2. Fetch and review the chart of accounts and sales and purchase tax mappings.

3. Use Fetch Bank Accounts and complete the new bank mappings.

4. Review the payment cutover with the finance team, then enable Pull Payments from Xero again when ready.

Keep earlier invoices and Payment Entries as historical records. A replacement organisation does not transfer those transactions or their Xero IDs. Do not retry an old invoice against the replacement organisation.

Customers, suppliers, and items

Customer and supplier contacts are handled when an invoice is pushed. NexWave first reuses a Xero Contact Mapping for that party and organisation. For an unmapped party, it can verify a previously stored contact ID or match by email in that organisation before creating a contact. Keep customer and supplier email details correct and review ambiguous contact setup with the finance team.

Use Contact Mappings in the workspace to inspect those links. Later edits to a NexWave customer or supplier do not automatically update its Xero contact. This is not a bulk contact synchronisation process.

Customer contact mapping showing Party Type, Party, Xero Tenant ID, and Xero Contact ID

The example links one customer to a Xero Tenant ID and Xero Contact ID. The tenant is the Xero organisation. Check the party and organisation when reviewing a contact link; do not copy a contact ID to a different organisation.

Items are sent as invoice lines with their descriptions, quantities, amounts, accounts, and taxes. NexWave does not create or maintain the Xero item catalogue or synchronise stock quantities. Maintain item and stock records in NexWave.

Operating checks after go-live

Run these checks during the first week after you enable the connection:

• First Sales Invoice push.

• First Purchase Invoice push.

• First credit note push.

• First invoice cancellation.

• First single-invoice payment pull.

• First matched local payment.

• First payment deletion, if this is part of the process.

• First foreign-currency invoice, if the Company uses foreign-currency transactions.

• First sync error or manual-review item.

• A later payment-pull cycle, to confirm that it creates no duplicate and keeps completed deletion results unchanged.

For each check, compare NexWave and Xero totals, tax, currency, account treatment, and payment status. Start with one organisation and a small controlled volume. Validate multiple organisations or large payment batches separately before you expand the rollout.

Troubleshooting

Related documentation

• Integrations

• Accounting

• Accounts Receivable

• Accounts Payable

• Sales Order to Despatch, Invoice & Payment Process

• Record and Review a Supplier Invoice

• Reconcile Bank Transactions in the Bank Rec Workspace

• Run a Payment Run