Skip to content

Put Xero documents on the right job

Match imported Xero invoices and quotes to an ONYX1 job, review suggestions, and understand the approval queue.

For owners and office staffLast reviewed
On this pageBefore you start

When Xero sends an invoice or quote into ONYX1, the document carries its customer and Xero number, and ONYX1 shows it under that Xero number. ONYX1 puts it on a job automatically only when the match is clear. You can review the remaining invoices and link them yourself.

Supplier bills use the same owner and admin queue, the Xero invoices tab under Approvals. They are costs, never sales revenue. A bill contributes to job costs only after it is linked to a job and its Xero account code is turned on as Job cost in Settings → Xero.

Before you start

  • An owner or admin must turn on inbound Xero sync for invoices or quotes in Settings → Xero. Supplier bills follow the inbound Invoices direction.
  • Owners and admins can use the Xero invoices tab under Approvals. It lists invoices needing a job, bills needing a job and job reconciliation gaps. Other business roles can use the Link to job control for documents their normal sales rights allow them to link.

Automatic matching

ONYX1 checks the Xero reference and line descriptions for an ONYX1 job number, such as JOB-0016, for the same customer. It also follows an invoice reference to a Xero quote that is already linked to a job. If neither is present, one completed or ready-to-invoice job with no sent or paid invoice can be chosen automatically for that customer.

The match never uses an amount or a customer name on its own. If two jobs could fit, the document stays unlinked for a person to decide. The reason for an automatic match is recorded in the activity history.

Automatic matching leaves archived jobs out. If a Xero reference names an archived job, the invoice or quote stays unlinked for review.

The Xero invoice suggestions show up to three jobs for the matched customer, with open and recently updated jobs first. The search box under Suggested jobs covers every job in your workspace, of every status including archived, and shows up to 20 results at a time: jobs for the invoice's customer first, then open jobs, then the most recently updated. Each result shows the job's customer and status, and archived jobs are marked Archived. Use those labels to confirm the right job.

An owner or admin can match an unlinked Xero invoice to an archived job when the invoice and job have the same customer. This does not restore the job or change the invoice's status. For a quote or a locally raised invoice, an owner or admin must select Restore job on the archived job's page before linking it. While a job is archived, ONYX1 will not let anyone unlink or move a document already on it.

Supplier bills

ONYX1 allocates a supplier bill automatically only when the evidence identifies one job:

  • The ONYX1 job number appears in the bill reference or a line description.
  • A Xero tracking option maps to the job.
  • The bill references a purchase order raised in ONYX1 for the job.

If the evidence is missing, conflicting or matches more than one job, the bill stays unlinked. The queue shows Bill needs a job with suggestions. Select Match to job, Overhead (not job cost) or Not for a job.

Match an invoice in the queue

  1. An owner or admin opens Xero invoices under Approvals, or selects the Xero queue card on the home screen.
  2. Review the Xero number, customer, ex-GST amount, status, date and reference.
  3. To find another job, enter at least two characters in the search box. Search by job number, job title, customer name, site name or site address. Clear the field to return to the suggestions.
  4. Select Match to job beside the right job. Suggestions are not automatic links. If the job belongs to a different customer record, review the confirmation, which names both customers, and continue only when they are the same real customer. The invoice keeps its existing Xero customer.
  5. If the invoice is a retainer, deposit or sundry sale, select Not for a job and enter a short reason.

The queue also shows Job not reconciled when a mapped job-cost line on a sent or paid invoice has no matching recorded cost. Select Link bill for a suggested Xero supplier bill, Add cost to add the missing amount and description from the invoice line, or Not a cost for this job and give a reason. Once the gap is covered or marked, the item leaves the open queue and the action is recorded in the activity history.

For an invoice whose customer ONYX1 cannot confidently identify, the queue shows the Xero contact's name and Customer to confirm. Type part of the customer's name into Search customers or scroll the full list, then select Match customer. After matching the customer, choose a job as described above.

If ONYX1 created a customer record for that Xero contact and you have renamed it to the real customer's name, choose that customer in the list and select Match customer to confirm it. A customer whose name still starts with "Xero contact awaiting customer match" is left out of the list and cannot be confirmed. To rename it, open it from Customers, select Edit, change Business / customer name and select Save changes. Or choose the real customer instead.

For a quote awaiting a customer match, open it from Quotes in Sales and select More actions, then Confirm the customer. If no eligible customer is available, select Create the customer first to open the new-customer form. The same menu offers Not for a job if the quote should not be attached to a job.

The queue includes unmatched invoices and supplier bills pulled in during the last 60 days. Older invoices remain available from their invoice page. Open reconciliation gaps stay in the queue until they are resolved or marked. A linked invoice is listed in the job's Invoices card with its status. Once it is sent or paid, it counts towards Invoiced at Xero's amount. If the job is Completed or Ready to invoice, the link can move it forward to Invoiced. It never moves a job backwards or changes whether the job is archived.

On an invoice that came from Xero, Last updated from Xero in Details shows the New Zealand date and time ONYX1 last applied a change to that invoice from Xero. The time does not move when ONYX1 checks and finds nothing new. Invoices raised in ONYX1 do not show this line, and neither does a Xero invoice that has no sync time recorded yet. Only owners, admins, dispatchers and office staff see this line, whether the invoice is opened from the Sales list or on its own page.

On a quote, select Link to job. On a locally raised invoice, select the link icon, whose tooltip is Link to job. In the Link to a job window, choose the job under Choose a job and select Link. For a Xero quote, review the confirmation if the job belongs to another customer record. You can link the quote while its customer is still waiting to be matched; it remains in that state. Linking does not resolve, rename, merge or reassign the customer record; the quote keeps its existing Xero customer. Manual linking and unlinking remain available under the usual business permissions when inbound quote sync is off. Owners, admins, dispatchers and office users can make this link. To move the document later, open the same window (for a quote, from its full page), select Unlink, then link the other job. A voided invoice's job link is frozen. On the job's money page (Open Money on its Overview), select Link a Xero invoice under Money summary, choose an imported invoice for that customer and select Link. The Approvals matching action is for owners and admins. A regular Link to job control on an invoice and Link a Xero invoice on a job's Money page use the usual invoice management permissions.

Quotes that are not on a job are tracked by the Not on a job count on the Quotes list. A quote is not placed in the invoice approval queue, but it has the same link and Not for a job actions.

If something goes wrong

  • Xero invoices is missing: check that inbound invoice sync is on and the Xero connection is active and confirmed.
  • The document is on the wrong job: open the Link to a job window, select Unlink, then link the correct job. The link and unlink are recorded in the activity history.
  • A quote or locally raised invoice cannot be linked to an archived job: ask an owner or admin to select Restore job on the archived job's page, then try again. An unlinked Xero invoice can be matched directly to an archived job with the same customer. A document already on an archived job cannot be unlinked or moved until the job is restored.
  • The queue does not show an older invoice: the queue is limited to the last 60 days. Open the invoice page to link it manually.
  • Supplier bills are not being pulled: check that the Invoices direction includes Xero → ONYX1 and that the connection has been reconnected if Settings → Xero asks for it.
  • A job cost is not included: check that the bill is linked to the job and its account code is set to On in the Job cost column in Settings → Xero.