Xero Accounting

Use this guide to connect Samurai CMMS to Xero, keep suppliers and accounts in sync, and send approved purchase orders to Xero.

Who should use this guide? Administrators or finance users responsible for maintaining the Xero connection and purchase order workflow.

Before you start

  • You need access to Settings > Integrations in Samurai CMMS.
  • You need a Xero developer app with a Client ID and Client Secret.
  • You need permission in Xero to authorise access to the target organisation.
  • Have your preferred Xero purchase account ready. Samurai uses this account code on purchase order line items sent to Xero.

1. Configure Xero integration

  1. In Samurai CMMS, open Settings > Integrations.
  2. Find the Xero integration card. The status badge shows whether Xero is disconnected, configured, connected, or requires reconnection.
  3. Select Configure.
  4. Copy the OAuth Redirect URI shown in the Configure Xero window.
  5. In your Xero developer app, add that redirect URI to the app's OAuth redirect URI list and save the app.
  6. Back in Samurai CMMS, enter the Xero Client ID and Xero Client Secret.
  7. Select a Default Xero purchase account code if purchase accounts are already available.
    • If the list is empty, save the credentials first, connect to Xero, sync accounts, then return to Configure and select the account.
  8. Select Save.
  9. Select Connect to Xero or Reconnect Xero.
  10. Complete the Xero authorisation flow, choose the correct Xero organisation, and allow access.
  11. After returning to Samurai CMMS, confirm that the Xero card shows Connected and the expected organisation name.

Maintenance notes

  • Use Configure any time you need to update the Client ID or default purchase account.
  • When updating an existing connection, leave Xero Client Secret blank to keep the saved secret. The saved secret is not displayed.
  • If the status shows Reconnect required, select Reconnect Xero and complete the Xero authorisation flow again.
  • Use Disconnect only when you intentionally want to stop syncing with Xero. Disconnecting prevents supplier/account syncs and purchase order sends until the integration is connected again.

2. Sync Suppliers

Supplier sync imports Xero supplier contacts into Samurai CMMS and links them to local supplier records where possible.

  1. Open Settings > Integrations.
  2. Confirm the Xero status is Connected.
  3. Select Sync Suppliers.
  4. Wait for the success message. It reports how many suppliers were created, updated, matched by tax number, matched by name, archived, or skipped.

You can also run supplier sync from the Suppliers page by selecting Sync Xero Suppliers when Xero is connected.

Important: When Xero is connected, suppliers are managed in Xero. Create and edit supplier details in Xero, then run supplier sync in Samurai CMMS. Xero-managed suppliers are locked from manual editing in Samurai .

Good practice

  • Run supplier sync after creating or changing suppliers in Xero.
  • Keep supplier tax numbers and names consistent in Xero to improve automatic matching.
  • Check the sync summary for skipped or archived records and review those suppliers in Xero if the counts look unexpected.

3. Sync accounts

Account sync imports the Xero chart of accounts used by Samurai CMMS for purchase order line items and the default purchase account selector.

  1. Open Settings > Integrations.
  2. Confirm the Xero status is Connected.
  3. Select Sync Accounts.
  4. Wait for the success message. It reports how many accounts were created, updated, or archived.
  5. Select Configure.
  6. Choose the Default Xero purchase account code that should be used on purchase order line items.
  7. Select Save.

When Xero is connected, Samurai account records are synchronised from Xero and cannot be edited manually in Samurai CMMS. Make account changes in Xero, then run Sync Accounts again.

4. Send purchase orders to Xero

Samurai CMMS sends purchase orders to Xero when a purchase order is approved. Purchase orders must be valid before they can be sent.

Requirements before sending

  • Xero must be connected.
  • A default Xero purchase account code must be configured.
  • The purchase order must be approved.
  • The supplier on the purchase order must be linked to a Xero contact. Run supplier sync if the supplier is missing or not linked.
  • The purchase order must have at least one valid line item with a description and quantity greater than zero.

Sending workflow

  1. Create or open a purchase order in Samurai CMMS.
  2. Select a supplier synced from Xero.
  3. Add line items with descriptions, quantities, unit prices, and tax rates.
  4. Approve the purchase order.
  5. Samurai CMMS automatically attempts to create the purchase order in Xero.
  6. Review the Xero status column in the purchase order list or the Xero Integration panel inside the purchase order details.

Purchase order sync statuses

Status Meaning What to do
Not Sent The purchase order has not been sent to Xero. Approve the purchase order, or retry after correcting setup issues.
Pending Samurai CMMS has started the Xero send process. Wait briefly and refresh if needed.
Sent Xero accepted the purchase order. No action required. The Xero purchase order number is shown when available.
Failed Xero did not accept the purchase order or the local validation failed. Read the displayed error, correct the issue, then select Retry Xero Sync.
Skipped The purchase order was not sent by the integration. Review the purchase order and integration setup before trying again.

Troubleshooting

Connection fails after Xero login

Confirm the OAuth Redirect URI in Samurai CMMS exactly matches the redirect URI saved in the Xero developer app. Then reconnect from Settings > Integrations > Xero.

Status shows Reconnect required

Select Reconnect Xero and authorise the Xero organisation again. This is usually required when Xero access has expired, been revoked, or needs fresh consent.

No purchase accounts appear in Configure Xero

Connect to Xero first, run Sync Accounts, then reopen Configure. If the list is still empty, verify that active purchase accounts exist in Xero.

Purchase order fails: Supplier is not linked to Xero

Create or update the supplier contact in Xero, then run Sync Suppliers. Reopen the purchase order, confirm the supplier is a Xero-synced supplier, and retry the Xero sync.

Purchase order fails: Xero purchase account is not configured

Run Sync Accounts, open Configure, choose the Default Xero purchase account code, save, and retry the purchase order sync.

Xero validation error on purchase order

Review the error shown in the purchase order Xero status. Common causes include invalid supplier data, invalid tax configuration, missing line descriptions, or account codes that Xero does not accept for purchase orders. Correct the data in Xero or Samurai CMMS as appropriate, then retry.

Support checklist

If you need help, capture the following details before contacting support:

  • Xero connection status shown on the integration card.
  • The affected supplier name or purchase order number.
  • The Xero sync status and error message shown in Samurai CMMS.
  • The approximate date and time of the failed sync attempt.
  • Whether supplier sync and account sync have been run recently.