Tax and the Xero API


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.

Tax Defaults

  • 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.

Tax and Rounding

  • 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.

  • Example: Qty 1, Unit Price 10.00, Tax Rate 7.685
    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.

  • Example: two line items, each with Qty 1, Unit Price 45.45, Tax Rate 10.00
    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 Inclusive vs Tax Exclusive

  • 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).

  • Example: Qty 1.5, Unit Price 10.95, Discount 10%, with 10% tax rate
    Line Total less Discount = 1.5 * 10.95 - (1.5*10.95*.1) rounded to two places = 14.78.
    Rounded Line Total Less Tax = 14.78/1.1 rounded to two places = 13.44
    Tax Amount = 14.78 - 13.44 = 1.34

  • 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.
  • View Screen:

    Edit Screen:

Assigning a Tax Rate

  • Use the TaxType element to specify tax rates - you can’t use the Name field.

  • 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.

  • 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.

Tax Tutorials

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.