Tax Classification API Overview

As part of the Automated Sales Tax (AST) feature, you can map a new or existing item to a specific tax category. This information is used to determine the tax code correctly and calculate the sales tax accurately. Users are already able to do this via UI, and we’re happy to share that now you can do this using the APIs as well.

To assign a category via the UI:

1. Create an item (Inventory, Non-inventory or Service)
2. Mark ‘Is Taxable’ as true
3. Select a category from the ‘Sales tax category’ dropdown
4. Select a sub-category from the ‘What you sell’ dropdown

To assign a category via the APIs, you can use the new TaxClassification service. This enhancement is enabled from minor version 34 onwards.

Example:
Create an item called ‘ABC Notebook’ and assign it to the category ‘Retail’ & sub-category ‘School and educational instructional material’. At a high level, the steps are as follows:

1. Read all tax classification for level 1.
2. Get the id for category ‘Retail’
3. Read the classification based on parent id
4. Get the id for ‘School and educational instructional material’
5. Set the value in the create item request

1. Read all tax classification records for level 1

Operation: GET /v3/company/<companyid>/taxclassification?level=1&minorversion=34

Response:

{
   "QueryResponse": {
      "TaxClassification": [
         {
            "Id": "V1-00190000",
            "Code": "V1-00190000",
            "Name": "Products transferred electronically",
            "Description": "Products transferred electronically",
            "Level": "1",
            "ApplicableTo": "Service"
         },
         {
            "Id": "V1-00120000",
            "Code": "V1-00120000",
            "Name": "Retail",
            "Description": "Retail",
            "Level": "1",
            "ApplicableTo": [
               "Inventory",
               "NonInventory",
               "Service"
            ]
         },
         {
            "Id": "V1-00200000",
            "Code": "V1-00200000",
            "Name": "Sales of Software",
            "Description": "Sales of Software",
            "Level": "1",
            "ApplicableTo": [
               "Inventory",
               "NonInventory",
               "Service"
            ]
         }
      ] …… 
   }
}

2.     Get the id for category ‘Retail’

From the above response, the ID for ‘Retail’ is “V1-00120000”

3.     Read the classification based on parent id

Operation: GET /v3/company/<companyid>/taxclassification?parentId=V1-00120000&minorversion=34

Response:

{
   "QueryResponse": {
      "TaxClassification": [
         {
            "Id": "EUC-09050301-V1-00120000",
            "Code": "EUC-09050301",
            "Name": "Hats (not including formal hats)",
            "Description": "Clothing Accessories - Hats (not including formal hats)",
            "Level": "2",
            "ParentRef": {
               "name": "Retail",
               "value": "V1-00120000"
            },
            "ApplicableTo": [
               "Inventory",
               "NonInventory"
            ]
         },
         {
            "Id": "EUC-09040104-V1-00120000",
            "Code": "EUC-09040104",
            "Name": "School computer supplies",
            "Description": "School supplies - Computer supplied",
            "Level": "2",
            "ParentRef": {
               "name": "Retail",
               "value": "V1-00120000"
            },
            "ApplicableTo": [
               "Inventory",
               "NonInventory"
            ]
         },
         {
            "Id": "EUC-09040101-V1-00120000",
            "Code": "EUC-09040101",
            "Name": "School and educational instructional materials",
            "Description": "School supplies - Educational instructional materials",
            "Level": "2",
            "ParentRef": {
               "name": "Retail",
               "value": "V1-00120000"
            },
            "ApplicableTo": [
               "Inventory",
               "NonInventory"
            ]
         }
      ] …… 
   }
}

4. Get the id for ‘School and educational instructional material’

From the response above, the ID is “EUC-09040101-V1-00120000”

5.     Use this ID in the creation of an item.

Operation: POST /v3/company/<companyid>/item?minorversion=34

Request:

{
  "Name": "ABC Notebook",
  "IncomeAccountRef": {
    "value": "79",
    "name": "Sales of Product Income"
  },
  "ExpenseAccountRef": {
    "value": "80",
    "name": "Cost of Goods Sold"
  },
  "AssetAccountRef": {
    "value": "81",
    "name": "Inventory Asset"
  },
  "TaxClassificationRef" : {
    "value": "EUC-09040101-V1-00120000",
    "name": "School and educational instructional material"
  },
  "Type": "Inventory",
  "TrackQtyOnHand": true,
  "QtyOnHand": 10,
  "InvStartDate": "2018-12-10"
}

The item is now assigned a taxclassification through the API. In addition to the above, we also provide APIs to read all taxclassifications and read a taxclassification by ID. You can find more information about the TaxClassification object and all the API operations in our API Reference docs.  Have comments or questions? Share them on our developer forums!