Xero integration

A how to guide to connect your ToolBox to Xero

Connecting to Xero

Establishing the connection

  1. Open Settings from the left hand menu.

  2. Select the Integrations link under the Organisation heading in the settings navigation bar.

  3. Click the 'Connect Xero' button to open the integration settings.

  4. Click Connect.

  5. Authorise the integration by logging into Xero as an admin user and selecting the organisation to create invoices in.


Overview tab Explains the two configuration options and the method of selection or creation of contacts in Xero to assign to the invoices.

Configuration tab Choose which integration method you prefer: ‘part per line item’ or ‘process per line item’.

Part per line item: Each line in the invoice will be the part name, part quantity, part unit price, and part line total. If there is a minimum charge amount, it will appear as its own line item.

Process per line item: Each line in the invoice will be a quote component: cutting, material types, secondary processes, and any other charges.

Here is the screenshot of the configuration option for Xero:

Log in to Xero, make sure that you use the admin user details, and select the organisation you want to send invoices to.

How the integration works

An invoice is created in Xero at the point of marking a quote as Invoiced in ToolBox:

Warning: if a customer is not assigned to the quote in ToolBox, the invoice will not be created in Xero.

The invoice will be in the draft status is Xero, found in Business > Invoices > Draft.

The contact assigned to the invoice will be the customer/contact assigned to the ToolBox quote.

In Customer Central, each customer can have an account code set by clicking the pencil icon next to their name, or by filling it in during the customer creation form.

If the ToolBox customer has an account code, ToolBox will check for a matching account code in Xero’s contact list.

If there is a match, then that Xero customer is assigned.

If there is no account code or there is no match for the account code, then ToolBox looks for a contact in Xero that has the same name as the customer in ToolBox. If there is a match, that Xero contact is assigned.

If there is no match at all, then ToolBox creates that contact in Xero using the customer name and the email address of the ToolBox contact.

The due date of the invoice will be based on the payment terms setup for the Xero contact (if any), otherwise the default payment terms set in Xero > Settings > Invoice settings > Default settings. If no terms are set for the Xero contact or as the Xero account defaults, then no due date is set for the invoice.

Common reasons for an invoice to fail to be created

If you have marked a ToolBox quote as Invoiced and Xero isn't showing the new invoice after a couple of minutes, something has gone wrong in the integration.

Integration setup requirements

The first thing to check is that your Xero integration is setup and active. Follow the steps above to ensure that:

  • Your ToolBox account is connected to your Xero account; and

  • The 'Part per line item' workflow OR the 'Process per line item' workflow is toggled in the On position (not both).

Quote requirements

  • A customer and contact need to be assigned to the ToolBox quote.

    Xero requires that an invoice has a contact assigned to it. To ensure this requirement is met, your ToolBox quote must have a customer and contact assigned before it is marked as Invoiced.

  • Mark the ToolBox quote as Invoiced to trigger the invoice creation.

    The invoice in Xero won't be created until you mark the ToolBox quote as Invoiced. This generates an invoice number and document in ToolBox and the same number is used as the invoice number in Xero.

Invoice number requirements

  • Ensure the invoice number in ToolBox didn't already exist in Xero. The most common reason for a failed invoice creation in Xero is because the invoice number already existed. Xero requires that all invoices have a unique document number. Check the invoice number in ToolBox for the quote you working with, and see if there was already an invoice in your Xero account with that number. To fix this, check that the 'Next invoice number' in your ToolBox account's organisation settings (Quote and Documents section) is a number that doesn't already exist in your Xero account. Change the prefix or the number to something else if you are expecting another duplicate number error. Duplicate the quote you were working with in ToolBox (from the Quotes screen, or with the Actions > Duplicate button inside the quote) and mark the new quote as Invoiced to trigger the integration workflow again.

If your invoices are still not being created in Xero despite the above checks, please reach out to us at support@tempustools.com for assistance.

Last updated