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 new tax rates for a Xero organisation
Allows you to update tax rates for a Xero organisation

Elements for Tax Rates

Name Name of tax rate
TaxType See Tax Types
TaxComponents See TaxComponents
Status The Status of the Tax Rate e.g. ACTIVE, DELETED
The following element is required only for AU, NZ & UK based organisations.
Note – US and Global versions do not support the ReportTaxType element.
ReportTaxType See ReportTaxTypes
The following elements are only returned on a GET request
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

POST TaxRates

Use this method to create or update a tax rate. 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.

Example for POST Tax Rates

Below is an example of creating a tax rate in the US with the minimum elements required to add a new tax rate of 8.125% for Oakdale, CA

<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 – Update a Tax Rate Status.

An example of changing the status of a tax rate to DELETED. The status can only be set to DELETED when a tax rate is not the default on an account or used on a repeating invoice.

<TaxRates>
  <TaxRate>
    <Name>Sales Tax</Name>
    <Status>DELETED</Status>
  </TaxRate>
</TaxRates>

PUT TaxRates

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


GET TaxRates

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

<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>
   <TaxRate>
     <Name>No GST</Name>
     <TaxType>NONE</TaxType>
     <CanApplyToAssets>true</CanApplyToAssets>
     <CanApplyToEquity>true</CanApplyToEquity>
     <CanApplyToExpenses>true</CanApplyToExpenses>
     <CanApplyToLiabilities>true</CanApplyToLiabilities>
     <CanApplyToRevenue>true</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>
   <TaxRate>
     <Name>Zero Rated</Name>
     <TaxType>ZERORATED</TaxType>
     <CanApplyToAssets>false</CanApplyToAssets>
     <CanApplyToEquity>false</CanApplyToEquity>
     <CanApplyToExpenses>false</CanApplyToExpenses>
     <CanApplyToLiabilities>true</CanApplyToLiabilities>
     <CanApplyToRevenue>true</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>