Manage sales tax for US locales

This topic provides information about integrating your app with the QuickBooks Online API sales tax model for US editions of QuickBooks. For non-US sales tax integrations, click here.

Sales transactions such as Invoices, PurchaseOrders, and SalesReceipts use TaxCode objects to specify sales tax as follows:

TaxRate and TaxAgency objects, while not used directly in transactions, are used in TaxCode definitions.

To follow along, you’ll need a sandbox or another QuickBooks company populated with a chart of accounts, customers, vendors, and invoices. The examples in this tutorial use the sandbox company.

Automated sales tax

US QuickBooks Online companies created after November 10, 2017 manage sales tax calculations via an automated sales tax (AST) engine. Sales tax is determined based on the source and destination address. The source address is the company’s legal address as available in the company settings. The destination address is the shipping address provided on the sales transaction. If a shipping address is not provided, the company address is considered as the destination address. The ability to customize the source address based on location of a given transaction is not supported.

To determine if the QuickBooks Online company uses automated sales tax, query the Preferences.TaxPrefs.PartnerTaxEnabled attribute, available with minor version 3.

Special note is made in subsequent sections below where automated sales tax comes into play.

Note

Note

Sandbox companies currently do not support the automated sales tax engine.

The tax model at a glance

The table below summarizes the resources comprising in the US sales tax model.

Tax Item Resource Description
Tax group TaxCode Defines a tax code reference comprised of one or more tax rates. For example, the tax code Tucson is comprised of AZ State tax tax rate and Tucson City tax rate.Use the TaxService endpoint to create a TaxCode object. For companies using automated sales tax, a TaxCode object is automatically created by the QuickBooks Online service based on the company’s location. Apps can create TaxCode objects and assign them to sales transactions but will be overridden by AST-assigned tax codes. Sales Transaction entities: Used in sales transaction object’s TxnTaxDetail element to define the sales tax rate for the entire sales transaction. Customer entity: Used in the Customer object’s DefaultTaxCodeRef element to define the default TaxCode object to apply to transactions for this customer.
Pseudo tax codes TaxCode Indicates whether an individual line of a transaction is taxable. Possible values are TAX and NON. Used in a transaction line’s TaxCodeRef element. The QuickBooks company file comes prepopulated with TAX and NON pseudo tax codes; you cannot create additional pseudo codes.
Tax rate TaxRate Defines tax rate of an individual tax agency. Use the TaxService endpoint to create a TaxRate object. For companies using automated sales tax, TaxRate objects are created by the AST engine.
Tax agency TaxAgency Defines display names for individual tax agencies supported by your QuickBooks company file. Use the TaxAgency endpoint, itself, to create and maintain tax agencies. AST sets the default tax agency. Subsequent ones can be added manually via the QuickBooks Online UI.
Specifying sales tax

When creating or updating sales transactions, QuickBooks Online automatically calculates sales tax on your behalf and returns the amount in the TxnTaxDetail.TotalTaxattribute of the transaction. For the US tax model, amounts in transaction lines are always tax exclusive; as such, the GlobalTaxCalculation attribute is not supported for US-locale transactions. Specifying it generates an exception.

To trigger automatic sales tax calculation, set the following:

Note

Note

The QuickBooks company must be enabled to use sales tax.

  • Sales tax is not always enabled—enable its use from the Sales Tax center on the QuickBooks Online UI. You cannot enable it via the QuickBooks Online API.
  • With the QuickBooks Online API, check to see if sales tax is enabled by checking the Preferences.TaxPrefs.UsingSalesTax attribute is set to true.
Sample create request

In the Invoice create request below, sales tax is calculated on your behalf using the rate defined by the Tucson tax code. Note that the sales item line has SalesItemLineDetail.TaxCodeRef.value attribute set to TAX.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
   "Line": [{
      "Amount": 100.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
         "ItemRef": {
            "value": "8",
            "name": "Lighting"
         },
         "TaxCodeRef": {
            "value": "TAX"
         }
      }
   }],
   "TxnTaxDetail": {
      "TxnTaxCodeRef": {
         "value": "3",
         "name": "Tucson"
      }
   },
   "CustomerRef": {
     "value": "1"
   }
}
Sample response

Here is the corresponding response from the above request. A transaction tax of $9.10 is calculated by QuickBooks Online and returned in TxnTaxDetail.TotalTax. In addition, the response contains a TxnTaxDetail.TaxLine attribute detailing how the sales tax breaks down into its constituent parts, based on the the Tucson TaxCode definition. Some content has been omitted in order to showcase sales tax attributes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
   "Invoice": {
...
   "Line": [
      {
         "Id": "1",
         "LineNum": 1,
         "Amount": 100.0,
         "DetailType": "SalesItemLineDetail",
         "SalesItemLineDetail": {
          "ItemRef": {
             "value": "8",
             "name": "Lighting"
          },
          "TaxCodeRef": {
             "value": "TAX"
          }
         }
         },
         {
         "Amount": 100.0,
         "DetailType": "SubTotalLineDetail",
         "SubTotalLineDetail": {}
         }
         ],
         "TxnTaxDetail": {
         "TxnTaxCodeRef": {
         "value": "3"
         },
         "TotalTax": 9.1,
         "TaxLine": [
         {
          "Amount": 7.1,
          "DetailType": "TaxLineDetail",
          "TaxLineDetail": {
             "TaxRateRef": {
                "value": "1"
             },
             "PercentBased": true,
             "TaxPercent": 7.1,
             "NetAmountTaxable": 100.0
          }
         },
         {
            "Amount": 2.0,
            "DetailType": "TaxLineDetail",
            "TaxLineDetail": {
             "TaxRateRef": {
                "value": "2"
             },
             "PercentBased": true,
             "TaxPercent": 2,
             "NetAmountTaxable": 100.0
            }
         }
      ]
   },
   "CustomerRef": {
     "value": "1",
     "name": "Amy's Bird Sanctuary"
   },
...
   "time": "2015-08-14T14:40:35.722-07:00"
}
Rounding rules for sales tax calculation

QuickBooks Online calculates sales tax based on the total of taxable Line.Amount attributes in the transaction. A Line.Amount is calculated automatically from the UnitPrice value passed in with the line, if present. If a UnitPrice is not present, QuickBooks Online uses the value of Line.Amount directly. If both UnitPrice and Line.Amount are passed in, the value in Line.Amount is discarded and the calculated value is used instead.

The rounding precision for sales tax calculations is designed for two decimal place precision in QuickBooks Online. When inputting numbers into the UI or the API, you need to take this rounding into account. Tax is applied to the Line.Amount fields after whatever rounding was necessary to get them to two decimal places. As such, if you are entering numbers based on UnitPrice, then you need to be aware that your number can potentially be rounded twice before tax is applied.

The table below contrasts the effects of rounding on the final stored value of Line.Amount and corresponding sales tax on that amount.

Input UnitPrice| (input with 8 places)
Saved UnitPrice | (rounded to 7 places)
Line.Amount

Saved Line.Amount
(rounded to 2 places)
Calculated Tax
(where tax rate = 12%)
37.37499999 37.3750000 37.3750000 (calculated) 37.38 4.49
    37.37499999 (input directly) 37.37 4.48
../../../_images/UnitPriceRounding.png
Overriding Sales Tax

To override automatic sales tax calculation, supply the following at create time:

For companies using automated sales tax, TxnTaxDetail.TotalTax amount is honored. Supplied tax amount is prorated across associated tax rates in the tax code. Provided that the minor version used is 70 or later, the TxnTaxDetail.TxnTaxCodeRef passed in with the request will also be honored. Prior minor versions will prorate tax amounts based on the AST-assigned tax code.

Sample request

In the sample create request below, $9.50 is explicitly defined via the TxnTaxDetail.TotalTax attribute, thus suppressing QuickBooks Online automatic sales tax calculation. Note that the sales item line has SalesItemLineDetail.TaxCodeRef.value attribute set to TAX.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
   "Line": [{
      "Amount": 100.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
         "ItemRef": {
            "value": "8",
            "name": "Lighting"
         },
         "TaxCodeRef": {
            "value": "TAX"
         }
      }
      }],
      "TxnTaxDetail": {
      "TxnTaxCodeRef": {
         "value": "3",
         "name": "Tucson"
      },
      "TotalTax": 9.5
   },
   "CustomerRef": {
      "value": "1"
   }
}
Sample response

Here is the corresponding response from the above request. The specified transaction sales tax of $9.50 is reflected in TxnTaxDetail.TotalTax. In addition, the response contains a TxnTaxDetail.TaxLine attribute detailing how the sales tax breaks down into its constituent parts, based on the the Tucson TaxCode definition. Some content has been omitted in order to showcase sales tax attributes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
   "Invoice": {
...
   "Line": [
     {
        "Id": "1",
        "LineNum": 1,
        "Amount": 100.0,
        "DetailType": "SalesItemLineDetail",
        "SalesItemLineDetail": {
          "ItemRef": {
             "value": "8",
             "name": "Lighting"
          },
          "TaxCodeRef": {
             "value": "TAX"
          }
        }
     },
     {
        "Amount": 100.0,
        "DetailType": "SubTotalLineDetail",
        "SubTotalLineDetail": {}
     }
   ],
   "TxnTaxDetail": {
     "TxnTaxCodeRef": {
        "value": "3"
     },
     "TotalTax": 9.5,
     "TaxLine": [
        {
          "Amount": 7.41,
          "DetailType": "TaxLineDetail",
          "TaxLineDetail": {
             "TaxRateRef": {
                "value": "1"
             },
             "PercentBased": true,
             "TaxPercent": 7.1,
             "NetAmountTaxable": 100.0
          }
        },
        {
          "Amount": 2.09,
          "DetailType": "TaxLineDetail",
          "TaxLineDetail": {
             "TaxRateRef": {
                "value": "2"
             },
             "PercentBased": true,
             "TaxPercent": 2,
             "NetAmountTaxable": 100.0
          }
        }
     ]
   },
   "CustomerRef": {
     "value": "1",
     "name": "Amy's Bird Sanctuary"
   },
...
   "time": "2015-08-14T15:10:17.38-07:00"
}
Working with tax codes

Use a TaxCode object anywhere throughout the data model where it is required to specify the sales tax of a sales transaction.

There are two kinds of TaxCode objects:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
   "TaxCode": {
     "Name": "Tucson",
     "Description": "Tucson",
     "Active": true,
     "Taxable": true,
     "TaxGroup": true,
     "SalesTaxRateList": {
        "TaxRateDetail": [
           {
             "TaxRateRef": {
                "value": "1",
                "name": "AZ State tax"
             },
             "TaxTypeApplicable": "TaxOnAmount",
             "TaxOrder": 0
           },
           {
             "TaxRateRef": {
                "value": "2",
                "name": "Tucson City"
             },
             "TaxTypeApplicable": "TaxOnAmount",
             "TaxOrder": 0
           }
        ]
     },
     "PurchaseTaxRateList": {
        "TaxRateDetail": []
     },
     "domain": "QBO",
     "sparse": false,
     "Id": "3",
     "SyncToken": "0",
     "MetaData": {
        "CreateTime": "2015-07-08T12:17:04-07:00",
        "LastUpdatedTime": "2015-07-08T12:17:04-07:00"
     }
   },
   "time": "2015-08-18T15:59:55.113-07:00"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
"TaxCode": {
   {
     "Name": "TAX",
     "Description": "TAX",
     "Taxable": true,
     "TaxGroup": false,
     "Id": "TAX",
     "MetaData": {
         "CreateTime": "2015-05-22T01:37:33-07:00",
         "LastUpdatedTime": "2015-05-22T01:37:33-07:00"
   }
}
How sales transactions use TaxCode

The image below is from a QuickBooks company with automated sales tax enabled and shows how the TaxCode object, CA-Santa Clara-Santa Clara, is referenced in an invoice.

../../../_images/ASTInvoice.jpg

The image below is from a company without automated sales tax enabled and shows how the TaxCode object, Tucson, is referenced in an Invoice.

../../../_images/USTxnTaxDetail.png

The image below shows how the pseudo tax code, TAX, is referenced in an Invoice.

../../../_images/USPseudoTaxCode.png
How name lists use TaxCode

In the US tax model, Customer objects specify their default TaxCode to use in transactions via the DefaultTaxCodeRef attribute.

For companies using automated sales tax, Customer.DefaultTaxCodeRef is populated with company’s default tax code as defined by AST and is not visible from QuickBooks Online UI.

../../../_images/USTaxCodeList.png
Working with tax rates

A tax rate specifies the amount of tax imposed by a given tax agency and a TaxRate entity to defines the mapping of a TaxAgency to its tax. It is not used directly in transaction or list objects, but is a building block used in creating higher level tax code definitions. Create TaxRate objects with the TaxService entity. As shipped, a US Sandbox company is pre-populated with the following tax rates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    "QueryResponse": {
        "TaxRate": [
        {
            "Name": "AZ State tax",
            "Description": "Sales Tax",
            "RateValue": 7.1,
            "AgencyRef": {
            "value": "1"
            }
        },
        {
            "Name": "California",
            "Description": "Sales Tax",
            "Active": true,
            "RateValue": 8,
            "AgencyRef": {
            "value": "2"
            }
        },
        {
            "Name": "Tucson City",
            "Description": "Sales Tax",
            "Active": true,
            "RateValue": 2,
            "AgencyRef": {
            "value": "1"
            }
        }
        ],
        "startPosition": 1,
        "maxResults": 3,
        "totalCount": 3
    },
    "time": "2015-08-04T14:50:42.278-07:00"
}

The image below shows how this entity relates to the Sales Tax Center in the QuickBooks UI.

../../../_images/USTaxRate.png
Working with tax agencies

A tax agency is associated with a tax rate and is the authority that collects those taxes. It is defined in the data model with the TaxAgency entity. It is not used directly in transaction or list objects, but is a building block used to create higher level tax rate definitions.

For companies using automated sales tax, QuickBooks Online automatically creates the appropriate tax agencies when sales tax is configured.

As shipped, a US sandbox company is pre-populated with these tax agencies:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
   "QueryResponse": {
     "TaxAgency": [
        {
           "Id": "1",
           "DisplayName": "Arizona Dept. of Revenue"
        },
        {
           "Id": "2",
           "DisplayName": "Board of Equalization"
        }
     ],
     "startPosition": 1,
     "maxResults": 2,
     "totalCount": 2
   },
   "time": "2015-08-04T14:22:49.954-07:00"
}

The image below shows how this entity relates to the Sales Tax Center in the QuickBooks Online UI.

../../../_images/USTaxAgency.png
Learn More

View the TaxCode reference here and TaxAgency here.