Knowledge Base


Version 7, 2019


Setup & send to Xero

The Xero Export report allows BpAllied to connect directly to your Xero account via the Xero API and transfer Invoices, Payments and Refunds that have been created in Bp Allied into Xero. The transfer of these is dependent on the transfer of basic client and Products and Services information.
On this page:

Before you start:
There is some initial information that needs to be set-up in both BpAllied and Xero prior to the export going ahead. Once this is done, then the transfer is done in the following order:
1.     Clients (known as Contacts in Xero)
2.     Products and Services (known as Items in Xero)
3.     Invoices
4.     Payments
This Xero export is not compatible with customers using the NDIS report export, as each system requires different GST values to be transferred.
If a practice has over 100 practitioners then they can not use the Xero export as the Xero tracking categories are limited to 100 options.
Please also refer to the Xero limitations section for more details on how this API works.

Initial Setup in Bp Allied

1: Xero connection and bank account setup
Set up the Xero account connection in Options > Financial Exports > Xero
Enter in your Xero bank account code in Options > Financial Exports > Xero
2: Allocate a Client ID to all clients
The import sets the Bp Allied Client ID as the Account Number in Xero. Clients without Clients IDs assigned will not be imported.
This step needs to be carried out prior to each import of Sales and Payments under the assumption that your practice continually gets new clients.
3: Update Third Party Billers
Ensure all Third Party Billers have both the Organisation (Last name) and Attention (First name) field filled in. Both fields are required to be able to export to MYOB.
In the Xero Export report in Reports > Exports
Clicking Preview Error Report  will display any that do not meet the appropriate criteria. This report can be printed or saved.
4: Update products and services
The following fields need to be populated in Bp Allied. Any Products or Services without a Category, Accounting Item Code or GST Code assigned will not be imported. If new Products or Services have been entered or prices have been changes then this will need to be imported prior to the export of Sales and Payment information. Item Descriptions can be a maximum length of 35 characters.
How to update the required fields

Bp Allied field

Xero Field

Data Type

Item Code
A unique number to individually identify each product or service. Bp Allied Item Code can not be mapped to this field as Bp Allied does not require it to be a unique number.
How to do this?
Type in a unique number for each line.
Sales Code
The Xero, the Sales Code is the account that sales are recorded against in the Chart of Accounts. For example: this is 200 by default. Multiple accounts can be set up in Bp Allied for different types of income to be tracked against.
How to do this?
Create Product Categories in Data Maintenance > Product Categories based on each sales account required.
In Data Maintenance > Products and Services assign a category to each product from the drop down list
GST Code
Tax Rate
GST Code must also be entered before any sales can be exported. This is the Tax Rate field in Xero that states whether an account is taxable or not. This value is used if there is no GST in the Invoice to set the default GST rate.   If there is GST on the invoice, then this amount is sent to Xero and the GST code set appropriately by the Xero export.
Products attracting GST must be assigned a value called “GST” as this is mapped to the Xero GST on Income account.
How to do this?
In Data Maintenance > Products and Services assign a GST code to each product line.
Item Description
Item Name
Maximum number of characters 35
5: Creation of Tracking Categories
Before you start:
Xero only allows a maximum of two tracking categories. Read more on what to do here.
Also there is a maximum number of options per category of 100. If a practice has over 100 practitioners then they can not use the Xero export.
So that the invoices and payments transferred to Xero can be categorised by Practitioner we have utilised the Xero Tracking Category functionality. This was the only way to enable this categorisation as there is no field in Xero for a Practitioner (or equivalent) that can be set against an Invoice.
ALL Practitioners MUST have a first and last name, otherwise an error will occur with the export. Read more here.
When the initial Client export is created the Practitioner tracking category is created along with category values for each User in BpAllied. This is updated as required each time the Client export is run.
As with the current functionality, any Invoices that include appointments related to multiple practitioners will be attributed to the practitioner related to the first appointment invoiced.
6: Prepend Client ID to Invoice and Payment Numbers
Xero will not allow an invoice or a payment to have a duplicate Invoice Number or Payment Number. There are two situations in BpAllied where these can occur, and hence prepending the Client ID to the Invoice or Payment number has been done to ensure that this number is unique. Read more about that here.

Send Clients to Xero

Clients are called 'Contacts' in Xero. Due to the Xero API not allowing duplicate Contact Names, the BpAllied Client ID is appended to the contact name. Read more about that here and the impact on your Xero Invoice templates.
The fields transferred are:

Bp Allied Field

Xero Field


Client ID
Account Number
First Name + Last Name + Client ID
Contact Name
First Name
Primary Person First Name
Mandatory. Can ONLY include apostrophes and hyphens. Errors will occur if other special characters are in these fields. E.g. brackets or quotes can't be used.
Last Name
Primary Person Last Name
Email Address
Email Address

Send products and services to Xero

Products and services are called 'Items' in Xero. Due to the API requiring that the Item Code field be unique, we require a unique number to be added into the Account Item Code field, as discussed above. However, this is not helpful when view items in the Xero interface, hence the Item Code and Description are concatenated onto this.
The fields transferred are:

Bp Allied Field

Xero Field

Accounting Item Code
Item Code
Item Code + Item Description (max 50 characters)
Item Name
Income Account
Selling Price
Unit Price
GST Code
Tax Rate

Send invoices to Xero

After setting up the clients and products and services above, all the Invoices for the selected period will be able to be sent through to Xero with exception of:
To send Invoices:
When looking in the Transactions grid in the Invoices section, any Invoice, Payment or Refund with an * after the Type letter means that it has been exported to Xero (or MYOB)
What if I have updated or changed an Invoice in BpAllied?
That change will need to be manually replicated within Xero. See details on the Changing Exported Data & Error Messages section.

Send payments to Xero

After sending Invoices, then all the payments for the selected period will be able to be sent through to Xero with exception of:
  • Your Xero Accounts Receivable (system) account code MUST be set to 610. If not, you will get this error.
  • Payments that relate to multiple invoices are split and allocated to the invoice. They are not displayed as the whole payment amount as they are in Bp Allied.
Allocation of payments
As a result of sending the payments as overpayments, at the end of the payments export, the script allocates the payments sent to Xero to the Invoices in Xero. Occasionally a validation error can occur if the Invoice has already been paid, for example if a payment has been manually added to Xero for the invoice. Read about this in the Changing Exported Data & Error Messages page.
To send Payments:
6. When a payment has been successfully exported the XeroGUID is written back into the table to stop it being exported again.
7. Please review the data in Xero

Managing refunds & overpayments

Refunds will get sent to Xero when the payments get processed, however, there is some manual intervention required. There is a reminder in Bp Allied when you go to remove the Invoice from the Payment that the same action must be carried out in Xero.
If the refund is for the full amount:
If the refund is for a partial amount, i.e. the invoice has been overpaid