Correct tax reporting is vital for businesses. The right rate has to be applied to the right line item to make sure the business is in compliance with their local tax authorities. Apps using the Xero API can make their client's lives simpler by automatically importing data, but if the wrong rate is used then that simplicity can quickly cause headaches. Here are some important things to know about taxes when using the Xero API.
The API's use of defaults is very limited. It won't use Contact defaults, Inventory Item defaults, Invoice defaults, or Financial Settings Defaults.
If TaxType isn't specified then Xero will use the default tax rate on the Chart of Accounts account that the line item is coded to. All other defaults such as from Contacts or Inventory Items are disregarded.
Invoices, Credit Notes, and Purchase Orders will be TaxExclusive by default if LineAmountTypes isn't specified. Receipts and Bank Transactions (including Prepayments and Overpayments) will be Tax Inclusive by default, and Manual Journals will be No Tax by default.
Since each line can have it's own rate, each line's tax is calculated and rounded separately.
Tax rates can be 4 decimal places, but after calculation the tax amount is rounded to 2 decimal places.
1 * 10.00 * .07865 = .7685 which is then rounded to two decimal places for tax of .77.
As each line is calculated and rounded separately, this can cause the Xero calculated tax amount to differ from systems that calculate on a per invoice basis.
Tax for each line 4.545 which rounds to 4.55. The tax from each line is added together for a total tax on the invoice of 9.10. If this were calculated on a per invoice basis the tax total would have been 9.09.
Tax Exclusive invoices add the tax to the line amount; a UnitAmount of 10.00 at a 10% tax rate will have a line amount of 10.00 and a tax amount of 1.00.
Tax Inclusive invoices include the tax in the line amount; a UnitAmount of 10.00 at a 10% tax rate will have a line amount of 10.00 and a tax amount of 0.91.
The Tax Inclusive tax amount is calculated by adding the tax rate to 1 and dividing the rounded line total by the rate, rounding to two decimal places, then subtracting this amount from the original line amount (line total being unit price times quantity reduced by discount).
Line Total less Discount = 1.5 * 10.95 - (1.5*10.95*.1) rounded to two places = 14.78.
Invoices, Credit Notes, and Purchase Orders will be TaxExclusive by default if LineAmountTypes isn't specified. Receipts and Bank Transactions (including Prepayments and Overpayments) will be Tax Inclusive by default.
Tax Inclusive invoices show as Tax Exclusive on the view screen in Xero once approved. The invoice is still Inclusive and shows that way through the API, but shows exclusive in the UI to make the true impact of the invoice easier to see once it's approved.
Use the TaxType element to specify tax rates - you can't use the Name field.
Tax rates are sometimes limited to only being used by certain account types (i.e. EXEMPTEXPENSES can't be used with Revenue accounts). A GET of TaxRates will show what account types the rate can be used with. More details on tax rate constraints can be found on the Tax rates page.
Part 1: How tax is calculated and the difference between tax inclusive and tax exclusive invoices.
Part 2: Assigning tax rates, how to choose tax rates and how tax defaults work.