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:

• At the line level—the taxable status of each line is noted as either TAX or NON. TaxCode objects in this context are referred to as pseudo tax codes.
• At the transaction level—the overall rate to use for all taxable lines. TaxCode objects in this context are referred to as tax groups.

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.

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.

• If true, automated sales tax is enabled for the company and sales tax is set up (Preferences.TaxPrefs.UsingSalesTax=true).
• If false, automated sales tax is enabled for the company but the company doesn’t have sales tax set up (Preferences.TaxPrefs.UsingSalesTax=false).
• If not present in response payload, the company is not enabled for automated sales tax.

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

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

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:

• For each sales item line subject to sales tax, set its SalesItemLineDetail.TaxCodeRef.value attribute to TAX. Note, the maximum number of line items for a taxable transaction is 750.
• To trigger sales tax calculation, specify the tax rate you want QuickBooks to apply at transaction create or update time via the TxnTaxDetail.TxnTaxCodeRef attribute . This is a reference to a predefined TaxCode object.
• Using the minor version 70 or later, the TxnTaxDetail.TxnTaxCodeRef passed in with the request is honored. Prior minor versions will calculate sales tax based on the AST-assigned tax code, for companies using automated sales tax.

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"
   }
}

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"
}

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.

• UnitPrice fields have a precision of seven decimal places.
• Line.Amount fields have a precision of two decimal places.
• If first non-significant figure is >=5, the last significant figure is rounded up. Otherwise, it it rounded down.

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.

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

• Your value via the TxnTaxDetail.TotalTax attribute
• The tax code via the TxnTaxDetail.TxnTaxCodeRef attribute

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.

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"
   }
}

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"
}

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:

• A tax group (TaxCode.TaxGroup=true) that combines one or more tax rate components, as applicable to the sales tax. For example, the sales tax for Tucson is a tax group composed of two TaxRate components: AZ Sales tax and Tucson City tax. A US sandbox company is pre-populated with several TaxCode objects. | For companies using automated sales tax, QuickBooks Online automatically creates the appropriate tax code objects when sales tax is configured.

 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"
}

• TAX and NON pseudo tax codes (TaxCode.TaxGroup=false) that are used as a flag on individual sales line items of a transaction to denote the taxable status of the line. The image below shows an Invoice line marked as taxable and its corresponding reference in an Invoice object.

 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"
   }
}

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.

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

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

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.

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.

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.

View the TaxCode reference here and TaxAgency here.