Tax rates

Explore the Tax Rates endpoints in Swagger.

View the coverage for tax rates in the Data Coverage Explorer.

Overview

Accounting systems typically store a set of taxes and associated rates within the accounting package. This means that users don't have to look up or remember the rates for each type of tax. For example: Applying the tax "UK sales VAT" to line items of an invoice adds the correct rate of 20%.

Tax components

In some cases, a tax is made up of multiple sub taxes, often called components of the tax. For example: You may have an item that is charged a tax rate called "City import tax (8%)" that has two components:

A city tax of 5%.
An import tax of 3%.

📘
Effective tax rates

Where there are multiple components of a tax, each component may be calculated on the original amount and added together. Alternatively, one tax may be calculated on the sub-total of the original amount plus another tax, which is referred to as compounding. When there is compounding, the effective tax rate is the rate that, if applied to the original amount, would result in the total amount of tax with compounding.

Example:
A tax has two components. Both components have a rate of 10%, and one component is compound. In this case, there is a total tax rate of 20% but an effective tax rate of 21%. Also see Compound tax example.

For QuickBooks Online, Codat doesn't use compound rates. Instead, the calculated effective tax rate for each component is shown. This means that the effective and total rates are the same because the total tax rate is a sum of the component rates.

Data model

Field	Type	Description
id	string	Identifier for the tax rate, unique for the company in the accounting platform.
name	string	Codat-augmented name of the tax rate in the accounting platform.
code	string	Code for the tax rate from the accounting platform.
status	string	Status of the tax rate in the accounting platform. Active - An active tax rate in use by a company. Archived - A tax rate that has been archived or is inactive in the accounting platform. * Unknown - Where the status of the tax rate cannot be determined from the underlying platform.
effectiveTaxRate	decimal	See Effective tax rates description in the Overview.
totalTaxRate	decimal	Total (not compounded) sum of the components of a tax rate.
components		A tax rate can be made up of multiple sub taxes, often called components of the tax. These are shown in the TaxRateComponents array.
modifiedDate	string See date	Date the record was last updated in the Codat system.
sourceModifiedDate	string See date	Date the record was last changed in the accounting system.

Components

A tax rate can be made up of multiple sub taxes, often called components of the tax.

Field	Type	Description
name	string	Name of the tax rate component.
rate	decimal	The rate of the tax rate component, usually a percentage.
isCompound	boolean	See Effective tax rates description in the Overview. For QuickBooks Online the calculated effective tax rate for each component is shown.

Field

Type

Description

name

string

Name of the tax rate component.

rate

decimal

The rate of the tax rate component, usually a percentage.

isCompound

boolean

See Effective tax rates description in the Overview.

For QuickBooks Online the calculated effective tax rate for each component is shown.

Tax rate reference

Data types that reference a tax rate, for example invoice and bill line items, use a taxRateRef that includes the ID and name of the linked tax rate.

Field	Type	Description
id	string	Unique identifier for the tax rate in the accounting platform.
name	string	Name of the tax rate in the accounting platform.

Example data

{
    "results": [
        {
            "id": "6c88aff3-7cb9-4980-a3d3-443e72e02498",
            "name": "ACME Sales Tax (10%)",
            "code": "110",
            "status" : "Active",
            "effectiveTaxRate": 10,
            "totalTaxRate": 10,
            "components": [
              {
                "name": "ACME 10%",
                "rate": 10,
                "isCompound": false
              }
            ]
          },
          {
            "id": "b31871d0-e0f8-4d0e-a464-cdf78bc45396",
            "name": "ACME Sales Tax (20%)",
            "code": "115",
            "status" : "Active",
            "effectiveTaxRate": 20,
            "totalTaxRate": 20,
            "components": [
              {
                "name": "ACME 20%",
                "rate": 20,
                "isCompound": false
              }
            ]
          },
          {
            "id": "a1d971c1-0699-41f6-b547-3f9930f45b5f",
            "name": "ACME Tax Exempt",
            "code": "120",
            "status" : "Archived",
            "effectiveTaxRate": 0,
            "totalTaxRate": 0,
            "components": [
              {
                "name": "ACME 0%",
                "rate": 0,
                "isCompound": false
              }
            ]
          },
          {
            "id": "e9e2db36-4966-4f5c-85a8-e3c297a7dd37",
            "name": "2 component",
            "code": "125",
            "status" : "Active",
            "effectiveTaxRate": 20,
            "totalTaxRate": 20,
            "components": [
              {
                "name": "2 component 10%",
                "rate": 10,
                "isCompound": false
              },
              {
                "name": "2 component 10%",
                "rate": 10,
                "isCompound": false
              }
            ]
          },
          {
            "id": "d606732b-db18-44d7-823b-7f15f42c32ea",
            "name": "2 component compound",
            "code": "130",
            "status" : "Active",
            "effectiveTaxRate": 21,
            "totalTaxRate": 20,
            "components": [
              {
                "name": "compound 10%",
                "rate": 10,
                "isCompound": true
              },
              {
                "name": "non-compound 10%",
                "rate": 10,
                "isCompound": false
              }
            ]
          }
        ],
        "modifiedDate": "2019-03-25T15:44:29.087Z",
        "sourceModifiedDate": "2019-03-25T15:44:29.087Z"
      }
    ],
    "pageNumber": 1,
    "pageSize": 5,
    "totalResults": 5,
    "_links": {
         "current": {
        "href": "/companies/85c10664-b6cc-49dd-b369-0cd1cef69031/data/journalEntries?page=1&pageSize=5"
      },
      "self": {
        "href": "/companies/85c10664-b6cc-49dd-b369-0cd1cef69031/data/journalEntries"
      }
}

Compound tax example

Item amount	$100
GST (5%)	$5
Subtotal	$105
PST (10%)	$10.50
Total	$115.50