Xero may calculate line item or document totals in ways that are slightly different to other applications. Neither approach is necessarily incorrect, just slightly different. This guide documents possible scenarios and ways to handle them via the API.
Xero calculates tax on a per line basis, rounding to two decimal places, and then sums the tax totals of each line to calculate the total invoice tax. Other systems may total lines and then calculate the tax amount, which can lead to a slight variance.
Invoice line 1: Product A @ $25.06, tax at 15%: $3.76 line total: $28.82
Invoice line 2: Product B @ $25.61, tax at 15%: $3.84 line total: $29.45
Invoice line 3: Product C @ $25.63, tax at 15%: $3.84 line total: $29.47
Xero totals: Subtotal: $76.30, Tax: $11.44
Xero document total: $87.74
Another system total: Subtotal: $76.30 + Tax @ 15%: 11.45
This can be illustrated below in Xero as the approach is the equivalent of just having one line in Xero:
By default, the API accepts unit prices (UnitAmount) to two decimals places. If you require greater precision, you can opt-in to 4 decimal places by adding the querystring parameter unitdp=4 to your request.
Example requests that opt in to 4 decimal places:
GET an individual invoice - https://api.xero.com/api.xro/2.0/Invoices?page=1&unitdp=4
GET invoices with paging - https://api.xero.com/api.xro/2.0/Invoices/INV-1002&unitdp=4
PUT & POST invoices - https://api.xero.com/api.xro/2.0/Invoices?unitdp=4
PUT & POST items - https://api.xero.com/api.xro/2.0/Items?unitdp=4
The parameter is supported on all endpoints that include line items (invoices, credit notes, bank transactions and receipts). It also applies to the UnitPrice elements on the Items endpoint. All summary values such as Total, LineAmount etc will remain at two decimal places only.
<LineItems> <LineItem> <Description>1000 x Product A @ $0.061171</Description> <Quantity>1</Quantity> <UnitAmount>61.17</UnitAmount> <AccountCode>200</AccountCode> </LineItem> </LineItems>
To ensure you can resolve any rounding issues, you will need to know when they occur. There are two approaches you can take:
If possible, you should add a rounding line to adjust the total to reflect the source system:
<LineItems> <LineItem> <Description>Rounding adjustment: document total $87.75</Description> <Quantity>1</Quantity> <UnitAmount>-0.01</UnitAmount> <AccountCode>860</AccountCode> </LineItem> </LineItems>
Every Xero organisation will have a rounding account, but you should ensure the account code is correct by making a GET Accounts API call at setup/configuration stage to ensure it is either the default value above, or if the user has changed it to another code, it can be found by the following element within the <Account/> element:
With the Invoices endpoint, you can now use the
<LineItems> <LineItem> <Description>My own calculation</Description> <Quantity>7</Quantity> <UnitAmount>48.7</UnitAmount> <TaxAmount>34.10</TaxAmount> <AccountCode>200</AccountCode> </LineItem> </LineItems>Limitations