Tax Rates


Overview

URL https://api.xero.com/api.xro/2.0/TaxRates
Methods Supported GET, PUT, POST
Description Returns tax rates for a Xero organisation
Allows you to add a new tax rate for a Xero organisation
Allows you to update a tax rate for a Xero organisation

GET TaxRates

Elements for Tax Rates

Name Name of tax rate
TaxType See Tax Types - can only be used on update calls
TaxComponents See TaxComponents
Status See Status Codes
ReportTaxType See ReportTaxTypes
CanApplyToAssets Boolean to describe if tax rate can be used for asset accounts i.e. true,false
CanApplyToEquity Boolean to describe if tax rate can be used for equity accounts i.e. true,false
CanApplyToExpenses Boolean to describe if tax rate can be used for expense accounts i.e. true,false
CanApplyToLiabilities Boolean to describe if tax rate can be used for liability accounts i.e. true,false
CanApplyToRevenue Boolean to describe if tax rate can be used for revenue accounts i.e. true,false
DisplayTaxRate Tax Rate (decimal to 4dp) e.g 12.5000
EffectiveRate Effective Tax Rate (decimal to 4dp) e.g 12.5000
Elements for TaxComponents
Name Name of Tax Component
Rate Tax Rate (up to 4dp)
IsCompound Boolean to describe if Tax rate is compounded.Learn more

Optional parameters for GET TaxRates

TaxType Filter by a Tax Type
Where Filter by an any element (see Filters)
order Order by any element returned (see Order By)

Example response for GET TaxRates

GET https://api.xero.com/api.xro/2.0/TaxRates
<TaxRates>
  <TaxRate>
    <Name>15% GST on Expenses</Name>
    <TaxType>INPUT2</TaxType>
    <CanApplyToAssets>true</CanApplyToAssets>
    <CanApplyToEquity>true</CanApplyToEquity>
    <CanApplyToExpenses>true</CanApplyToExpenses>
    <CanApplyToLiabilities>true</CanApplyToLiabilities>
    <CanApplyToRevenue>false</CanApplyToRevenue>
    <DisplayTaxRate>15.0000</DisplayTaxRate>
    <EffectiveRate>15.0000</EffectiveRate>
    <Status>ACTIVE</Status>
    <TaxComponents>
      <TaxComponent>
        <Name>GST</Name>
        <Rate>15.0000</Rate>
        <IsCompound>false</IsCompound>
      </TaxComponent>
    </TaxComponents>
  </TaxRate>
  <TaxRate>
    <Name>15% GST on Income</Name>
    <TaxType>OUTPUT2</TaxType>
    <CanApplyToAssets>true</CanApplyToAssets>
    <CanApplyToEquity>true</CanApplyToEquity>
    <CanApplyToExpenses>false</CanApplyToExpenses>
    <CanApplyToLiabilities>true</CanApplyToLiabilities>
    <CanApplyToRevenue>true</CanApplyToRevenue>
    <DisplayTaxRate>15.0000</DisplayTaxRate>
    <EffectiveRate>15.0000</EffectiveRate>
    <Status>ACTIVE</Status>
    <TaxComponents>
      <TaxComponent>
        <Name>GST</Name>
        <Rate>15.0000</Rate>
        <IsCompound>false</IsCompound>
      </TaxComponent>
    </TaxComponents>
  </TaxRate>
  <TaxRate>
    <Name>GST on Imports</Name>
    <TaxType>GSTONIMPORTS</TaxType>
    <CanApplyToAssets>false</CanApplyToAssets>
    <CanApplyToEquity>false</CanApplyToEquity>
    <CanApplyToExpenses>false</CanApplyToExpenses>
    <CanApplyToLiabilities>true</CanApplyToLiabilities>
    <CanApplyToRevenue>false</CanApplyToRevenue>
    <DisplayTaxRate>0.0000</DisplayTaxRate>
    <EffectiveRate>0.0000</EffectiveRate>
    <Status>ACTIVE</Status>
    <TaxComponents>
      <TaxComponent>
        <Name>GST</Name>
        <Rate>0.0000</Rate>
        <IsCompound>false</IsCompound>
      </TaxComponent>
    </TaxComponents>
  </TaxRate>
  ...
</TaxRates>

POST TaxRates

Use this method to create or update a tax rate. Only one tax rate can be created or updated per request. Please note that system defined tax rates can't be updated.

All the existing tax components must be supplied when updating a tax rate. If a tax rate has three components, and only two are supplied while updating it, the third component will be deleted.

The following elements can be used in a POST request

Name Name of tax rate
TaxType See Tax Types - can only be used on update calls
TaxComponents See TaxComponents
Status See Status Codes
ReportTaxType See ReportTaxTypes
Elements for TaxComponents
Name Name of Tax Component
Rate Tax Rate (up to 4dp)
IsCompound Boolean to describe if Tax rate is compounded.Learn more

PUT TaxRates

The PUT method is similar to the POST TaxRates method, however you can only create new tax rates with this method.

Example request to create a Tax Rate

POST https://api.xero.com/api.xro/2.0/TaxRates
<TaxRate>
  <Name>Oakdale Sales Tax</Name>
  <TaxComponents>
    <TaxComponent>
      <Name>State Tax</Name>
      <Rate>7.5</Rate>
      <IsCompound>false</IsCompound>
    </TaxComponent>
     <TaxComponent>
      <Name>Local Sales Tax</Name>
      <Rate>0.625</Rate>
      <IsCompound>false</IsCompound>
    </TaxComponent>
  </TaxComponents>
</TaxRate>

Example request to update a Tax Rate Status to DELETED.

POST https://api.xero.com/api.xro/2.0/TaxRates
<TaxRates>
  <TaxRate>
    <Name>Sales Tax</Name>
    <Status>DELETED</Status>
  </TaxRate>
</TaxRates>

Tax Rate Constraints

In order to properly complete tax forms, certain tax rates can only be used with certain account types. This will vary depending on the rate and country. Sending a line item with a tax rate that can't be use with the line's account code will generate the error "The TaxType code 'xxx' cannot be used with account code 'xxx'."

Below is a list of the default rates that Xero organisations start with. Please note that users can edit the names and and create their own rates in Xero so this is only a guide - you'll need to do a GET of tax rates to know for certain what rate can be paired with what account type in the organisation you're connecting to.

Australia

TaxType TaxName Assets Equity Expenses Liabilities Revenue
BASEXCLUDED BAS Excluded true true true true true
EXEMPTCAPITAL GST Free Capital true true true true false
EXEMPTEXPENSES GST Free Expenses true true true true false
EXEMPTEXPORT GST Free Exports true true false true true
EXEMPTOUTPUT GST Free Income true true false true true
CAPEXINPUT GST on Capital true true true true false
GSTONCAPIMPORTS GST on Capital Imports false false false true false
INPUT GST on Expenses true true true true false
GSTONIMPORTS GST on Imports false false false true false
OUTPUT GST on Income true true false true true
INPUTTAXED Input Taxed true true true true true

Global

TaxType TaxName Assets Equity Expenses Liabilities Revenue
GSTONIMPORTS Sales Tax on Imports false false false true false
NONE Tax Exempt true true true true true
OUTPUT Tax on Consulting true true true true true
INPUT Tax on Purchases true true true true true

New Zealand

TaxType TaxName Assets Equity Expenses Liabilities Revenue
INPUT GST on Expenses true true true true true
OUTPUT GST on Income true true false true true
INPUT2 GST on Expenses true true true true false
OUTPUT2 GST on Income true true false true true
GSTONIMPORTS GST on Imports true true false true false
NONE No GST true true true true true
ZERORATED Zero Rated false false false true true

Singapore

TaxType TaxName Assets Equity Expenses Liabilities Revenue
ZERORATEDOUTPUT Zero-Rated Supplies false true false true true
ES33OUTPUT Regulation 33 Exempt Supplies false true false true true
ESN33OUTPUT Non-Regulation 33 Exempt Supplies false true false true true
DSOUTPUT Deemed false true false true true
OSOUTPUT Out–of-Scope Supplies false true false true true
ZERORATEDINPUT Zero-Rated Purchases true true true false false
IMINPUT Imports true true true false false
MEINPUT Imports under a Special Scheme true true true false false
IGDSINPUT Imports under the Import GST Deferment Scheme true true true false false
BLINPUT Disallowed Expenses true true true false false
NRINPUT Purchases from Non-GST Registered Suppliers true true true false false
OPINPUT Out Of Scope Purchases true true true false false
TXN33INPUT Partially Exempt Traders Non-Regulation 33 Exempt true true true false false
TXESSINPUT Partially Exempt Traders Regulation 33 Exempt true true true false false
TXREINPUT Partially Exempt Traders Residual Input tax true true true false false
TXPETINPUT Partially Exempt Traders Standard-Rated Purchases true true true false false
NONE Tax Exempt true true true true true
INPUT Standard-Rated Purchases true true true true true
OUTPUT Standard-Rated Supplies true true true true true

South Africa

TaxType TaxName Assets Equity Expenses Liabilities Revenue
GSTONCAPIMPORTS Capital Goods Imported true true true false false
INPUT2 Change in Use true true true false false
OUTPUT2 Change in use and Export of Second-hand Goods false true false true true
EXEMPTOUTPUT Exempt and Non-Supplies false true false true true
IMINPUT Goods and Services Imported true true true false false
None No VAT true true true true true
INPUT Standard Rate Purchases true true true false false
CAPEXINPUT Standard Rate Purchases - Capital Goods true true true false false
OUTPUT Standard Rate Sales false true false true true
SROUTPUT Standard Rate Sales - Capital Goods false true false true true
ZERORATED Zero rate (Excluding Goods Exported) false true false true true
ZERORATEDOUTPUT Zero Rate (only Exported Goods) false true false true true

United Kingdom

TaxType TaxName Assets Equity Expenses Liabilities Revenue
CAPEXSRINPUT 15% (VAT on Capital Purchases) true false false false false
CAPEXSROUTPUT 15% (VAT on Capital Sales) true false false false false
CAPEXINPUT 17.5% (VAT on Capital Purchases) true false false false false
CAPEXOUTPUT 17.5% (VAT on Capital Sales) true false false false false
CAPEXINPUT2 20% (VAT on Capital Purchases) true false false false false
CAPEXOUTPUT2 20% (VAT on Capital Sales) true false false false false
INPUT2 20% (VAT on Expenses) true true true true false
OUTPUT2 20% (VAT on Income) true true false true true
RRINPUT 5% (VAT on Expenses) true true true true false
RROUTPUT 5% (VAT on Income) true true false true true
ECACQUISITIONS EC Acquisitions (20%) true true true true false
ECZRACQUISITIONS EC Acquisitions (Zero Rated) true true true true false
EXEMPTINPUT Exempt Expenses true true true true false
EXEMPTOUTPUT Exempt Income true true false true true
NONE No VAT true true true true true
REVERSECHARGES Reverse Charge Expenses (20%) true true true true false
GSTONIMPORTS VAT on Imports false false false true false
ECZROUTPUT Zero Rated EC Goods Income true true false true true
ECZROUTPUTSERVICES Zero Rated EC Services true true false true true
ZERORATEDINPUT Zero Rated Expenses true true true true false
ZERORATEDOUTPUT Zero Rated Income true true false true true

United States

TaxType TaxName Assets Equity Expenses Liabilities Revenue
AVALARA Auto Look Up (DO NOT USE) true true true true true
GSTONIMPORTS Sales Tax on Imports false false false true false
NONE Tax Exempt true true true true true
OUTPUT Tax on Sales true true true true true
INPUT Tax on Purchases true true true true true

Note: The Avalara tax rate look up feature does not work for transactions imported through the API. A different rate should be used.