Export maintenance purchase orders to Xero

In this guide

Connect your own Xero application

Register a Web app in the Xero developer portal. Copy the exact callback URI shown in PreventiveHQ Integrations into the app configuration, then save its client ID and secret. Authorize through Xero and explicitly select the connected organization. The connector requests offline access, invoice/purchase-order access and read-only contacts access.

Create and mark the maintenance purchase ordered

Choose a supplier, receiving location, currency and part quantities in Purchasing. A draft order does not change stock. Mark it ordered once the purchasing decision is made. Printable orders are available for your own supplier handoff. Partial receipts later update inventory without changing the original order quantities.

Create a Xero draft for review

Select the ordered purchase and the supplier contact ID from your Xero organization. PreventiveHQ sends a draft purchase order containing the reference, currency, description, quantities and unit costs. It does not approve the draft or send it to the supplier. Review tax treatment, account coding, delivery details and final totals in Xero.

Retry without changing the original export

The first export freezes its payload and request key. A confirmed export returns the existing Xero ID on repeat requests. If the provider response is uncertain, retry the same order and contact. Changing the target organization or contact on an existing export is rejected so records cannot drift between accounting organizations.

Understand the boundary

This is purchase-order export, not a full two-way accounting ledger. Supplier bills, payments, bank reconciliation, tax filing and stock valuation remain in your accounting process. OAuth access tokens refresh using encrypted rotating refresh tokens. Disconnect removes local credentials; you can also revoke the app in Xero.

Define the handoff between maintenance and accounting

Maintenance purchasing starts with an operational need: a part is required at a location so work can proceed. Accounting needs a controlled record of the supplier commitment and the subsequent financial process. Connecting those activities can reduce repeated entry, but it is important to know which record each system owns and what the integration actually transfers.

AI-generated editorial illustration; not a customer photograph or product screenshot.

PreventiveHQ’s Xero connector exports a maintenance purchase order as a draft purchase order in the selected Xero organization. It does not approve that draft, send it to a supplier, create a supplier bill or pay anyone. This creates a reviewable handoff between the maintenance purchase and the accounting workflow rather than an unattended financial transaction.

Before setup, agree who prepares the maintenance purchase, who checks the supplier identity and who reviews the draft in Xero. A technically successful export can still be wrong for the business if it uses the wrong supplier contact or currency. The first pilot should therefore include both maintenance and accounting staff.

The Xero purchase-order documentation is the provider reference for that API resource. This guide describes the narrower behavior implemented in PreventiveHQ. Review provider account access and developer requirements directly with Xero when setting up your own application.

Prepare a customer-owned Xero application

Register a Web app in the Xero developer portal and use the exact callback URI shown in PreventiveHQ Integrations. The callback address connects the authorization response to the correct application endpoint. Do not substitute a homepage URL or an address copied from another workspace environment.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Save the application’s client ID and secret through the integration settings. Treat the secret as a credential, not as a purchase-order reference or a value to paste into a support conversation. PreventiveHQ stores connection credentials encrypted and uses them for the OAuth authorization and refresh process.

Authorize the connection through Xero using an account that has the appropriate organization access. The connector requests offline_access, accounting.invoices and accounting.contacts.read. These scope names describe provider permissions; their presence does not mean PreventiveHQ implements every accounting feature that those permissions could support.

The application then presents connected organizations for explicit selection. Confirm the organization’s identity before exporting any purchase. Businesses with multiple legal entities or test organizations should not rely on a familiar display name alone. The selected tenant determines where the draft purchase order will be created.

Agree the system of record for each step

Use PreventiveHQ for the maintenance purchase request represented by its purchasing workflow: supplier, receiving location, active parts, ordered quantities, unit costs and receipt progress. Use Xero for the accounting review and subsequent processes that belong there. The connector does not establish a complete two-way ledger between the products.

This division prevents a common assumption: that changing a record in one system automatically changes the corresponding record in the other. The connector exports a defined payload and retains its identity. It does not continuously synchronize every purchase-order edit, receipt or accounting status.

Write a short internal handoff rule before rollout. For example, maintenance prepares and marks the purchase ordered, finance verifies the destination contact, then finance reviews the resulting Xero draft before any supplier communication. Adapt the rule to your actual authority structure rather than treating this example as an automatic approval policy supplied by the application.

Prepare the maintenance purchase carefully

Create the supplier and select the stock location that will receive the parts. Each line references an active part in the workspace. Review quantity units and current supplier pricing before marking the purchase ordered. An existing part cost can help prepare a draft, but it is not evidence that the supplier still offers that price.

Choose the currency deliberately. A numeric unit cost without the correct currency can produce a materially different commitment. PreventiveHQ’s purchase subtotal excludes taxes and freight, and the Xero draft still needs the accounting review appropriate to your business. Do not describe the maintenance subtotal as a final payable amount.

Check the line descriptions for sufficient supplier context. A maintenance team may recognize a short internal part label that a supplier or accountant does not. Preserve the correct part identity and make the description understandable without claiming that the connector maps your complete item catalog or accounting chart automatically.

Mark the purchase ordered when the organization has made that purchasing decision. The export accepts ordered, partially received or received purchases; an uncommitted draft does not qualify for a new export. This status requirement does not replace your organization’s approval rules or prove that a supplier has accepted the order.

Match the supplier contact explicitly

The export requires the Xero contact ID for the supplier in the selected organization. This is an explicit identity mapping, not an automatic fuzzy match on supplier name. A similar name is insufficient when different branches, legal entities or duplicate contacts exist in an accounting system.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Have the accounting owner verify the contact before the first export. Keep the mapping in your operational handoff notes without including credentials. If a supplier has multiple contacts in Xero, decide which one represents the intended purchasing relationship and resolve duplicates through your accounting process.

The contact identifier and organization are retained with the first export. Changing either on an existing export is rejected because the same local purchase should not drift into a different accounting destination on retry. Review the destination carefully before the initial request rather than treating export as a disposable preview.

If a contact is wrong, stop and investigate the existing export state. Do not create a second maintenance purchase solely to conceal the mapping error. The appropriate correction depends on whether a draft was created in Xero and what actions have already occurred there.

Understand the fields sent to Xero

The exported draft includes the purchase reference, currency, line descriptions, quantities and unit costs. It uses the PreventiveHQ purchase number as the purchase-order number and adds a PreventiveHQ reference. The payload is explicitly a draft with exclusive line amounts, leaving final accounting treatment for review.

The date is taken from the local purchase creation date in the implemented export. Do not assume it represents the date of supplier acceptance, the latest receipt or the moment the export button was clicked. If your accounting process requires a different date or additional delivery detail, review the resulting draft in Xero before approval.

The connector does not claim to populate every optional Xero purchase-order field. Tax treatment, account coding, delivery details and final totals need review in the accounting workflow. It also does not export an invoice merely because the authorization scope contains the word invoices.

Compare a first draft line by line with the local purchase. Check supplier identity, organization, currency, quantities, unit costs, descriptions and reference. This is the meaningful acceptance test for the handoff. A returned provider identifier proves that a record was confirmed, not that the business content was correct.

Work through an illustrative export

Suppose a maintenance team orders ten filters at a unit cost of 25.00 and two seals at 18.50 in its selected currency. The maintenance subtotal is 287.00 before taxes and freight: ten multiplied by 25.00, plus two multiplied by 18.50. These figures are an illustrative example, not a supplier quotation.

AI-generated editorial illustration; not a customer photograph or product screenshot.

The purchaser verifies the receiving location and marks the order ordered. The accounting owner confirms the Xero organization and supplier contact ID, then initiates export. Xero receives a draft purchase order containing the reference and two lines. Finance compares the line quantities and unit costs with the maintenance record.

Finance then reviews tax treatment, account coding, delivery information and the final accounting presentation in Xero. The connector has not approved or sent the draft. Any supplier communication follows the organization’s authorized process. This review remains necessary even when the arithmetic in the maintenance purchase is correct.

Later, six filters arrive. The receiving team records that partial delivery in PreventiveHQ. That receipt updates the local inventory workflow; it is not a claim that this connector automatically posts a supplier bill or synchronizes every receipt event into Xero. Keep the receiving and accounting processes coordinated through the agreed handoff.

Retry uncertain exports without changing their meaning

A network request can fail to return a clear response even when the provider has received it. Repeating such a request carelessly can create duplicate records or change the intended transaction. PreventiveHQ addresses this by storing the first export payload and a stable request key before making the provider call.

AI-generated editorial illustration; not a customer photograph or product screenshot.

If Xero confirms the draft, the returned Xero purchase-order ID is retained. A repeated request for the confirmed export returns that existing ID. If the response is uncertain, retry the same order and contact so the stored payload and request key remain consistent. The interface’s error should not be interpreted as proof that no provider-side record could exist.

Changing the organization or contact on an existing export is rejected. The frozen payload also means that retrying is not a general-purpose update operation for a changed local purchase. Understand the existing export state and review the accounting record rather than expecting a retry to replace its original meaning.

When investigating an uncertain result, record the local purchase number, intended organization, non-secret error context and any confirmed Xero identifier. Do not include the client secret or OAuth tokens in the investigation notes. Have the accounting owner reconcile the destination before taking a separate corrective action.

Keep receiving and financial reconciliation distinct

PreventiveHQ records purchase receipts against outstanding quantities and updates stock at the selected receiving location. Partial receipts leave the purchase partially received; full receipt completes the local receiving status. Those operational records help the maintenance team know whether required parts have arrived.

A receipt is not the same as a supplier bill, a payment or a bank reconciliation. The supplier may invoice at a different time, include freight or apply other terms. This connector does not perform three-way matching between an order, receipt and invoice, nor does it calculate the final tax or stock valuation treatment for your accounts.

When preparing a purchasing review, compare open local quantities with the accounting commitments through your agreed process. Do not use a successful draft export as evidence that parts are physically available. Conversely, do not use a local received status as evidence that the supplier has been paid.

The maintenance purchasing guide explains the local receipt workflow in detail. Keeping these distinctions explicit makes the integration easier to trust because each status has a clear operational meaning.

Troubleshoot authorization and destination errors

If authorization fails, confirm the registered application type, client credentials and exact callback URI. Review the provider authorization flow and the user’s access to the intended organization. Do not alter unrelated purchase data to solve an OAuth setup problem.

If organizations cannot be loaded, reconnect or retry after resolving the provider access issue. Select the intended organization explicitly when it becomes available. A previously familiar organization name should still be checked against the legal entity involved in the purchase.

If export is rejected before the provider call, check that the purchase has been marked ordered and that the contact and organization identifiers are valid. If the purchase already has an export, compare its original destination with the attempted destination. The rejection may be protecting an existing record from being redirected.

If Xero does not confirm the draft, retain the same export identity while investigating. Review the accounting-side validation details available to the authorized owner and retry the same order when appropriate. Avoid generating repeated new purchases as a substitute for understanding one uncertain export.

Manage token refresh and disconnection

The connector uses OAuth access tokens and rotating refresh tokens stored with the encrypted connection credentials. It refreshes access when needed and preserves the refreshed token before continuing with a business API call. Users should not need to copy a new short-lived access token into the interface for every purchase export.

Authorization can still require attention if provider access is revoked, the application configuration changes or the connection becomes invalid. Assign an owner who can reconnect deliberately and verify the selected organization afterward. A successful reconnection should be followed by a destination check before the next purchasing handoff.

Disconnecting removes locally stored credentials. Revoke the application in Xero as well when provider-side access should end. These actions do not automatically delete purchase orders already created in Xero or reverse local receipts. Existing business records need their own authorized correction process.

When ownership changes, transfer the application administration responsibility and the handoff runbook through your organization’s access process. Preserve the mapping decisions and export references while keeping credentials out of shared operational documents.

Test a complete purchasing handoff

Use a small, legitimate pilot purchase that the organization is prepared to review. Confirm the local order, supplier mapping, selected organization and resulting Xero draft. Have maintenance and accounting reviewers independently compare the fields they own. This reveals misunderstandings that a connection-status check cannot detect.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Test repeat behavior after a confirmed export and verify that the existing provider identifier is returned. Review what the team should do after an uncertain response without deliberately creating uncontrolled duplicate financial records. Document the escalation owner and the information needed for reconciliation.

Finally, follow a partial receipt through PreventiveHQ and confirm that users understand its separation from accounting approval and payment. The integration is useful when the handoff reduces repeated entry while preserving clear responsibility. Measure that administrative improvement separately from broader claims about purchasing savings.

Questions about the Xero connector

Does the integration send orders or pay suppliers?

No. It creates a Xero draft purchase order for review. Approval, supplier communication, bills and payments remain in the appropriate accounting and purchasing process. A confirmed export should never be described as a confirmed payment.

Can we connect our own Xero developer app?

Yes. The setup uses your Web app’s client ID and secret, the callback URI shown in Integrations and OAuth authorization to your connected organization. Provider account and application requirements still apply.

Does changing a local purchase update the exported draft?

This connector retains the first export payload and identity for reliable retries. It is not a continuous two-way purchase-order editor. Review changes through the responsible maintenance and accounting workflows so the two records remain understandable.