Manage sales tax for US locales

This topic provides information about integrating your app with the QuickBooks 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 TAX and 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. 

Workflows

ConceptsAfter reading this tutorial, you will be familiar with the following concepts:
  • General sales tax support provided by QuickBooks Online for US locales.
  • Relationship of tax rate and tax code concepts between the QuickBooks API and QuickBooks Online UI.
  • How to create sales tax codes for your area.
  • How sales tax information is surfaced in transactions.
Prerequisites
  • Experience with the following:
    • JSON request and response payloads.
    • The general mechanics of constructing QuickBooks API request payloads and making REST API calls.
    • The role sales tax has in running a business and has in accounting.
  • Data
    • Sandbox or another QuickBooks Online company populated with a chart of accounts, customers, vendors, and invoices. The examples in this tutorial use the sandbox company.
Resources
  • TaxCode, TaxRate, TaxAgency, TxnTaxDetail element in transactions
Learn more
  • View the TaxCode reference here and TaxAgency here.

The tax model at a glance

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

Tax ItemResourceDescription
Tax groupTaxCode

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.

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 codesTaxCode

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 rateTaxRateDefines tax rate of an individual tax agency.  Use the TaxService endpoint to create a TaxRate object.
Tax agencyTaxAgencyDefines display names for individual tax agencies supported by your QuickBooks Online company file. Use the TaxAgency endpoint, itself, to create and maintain tax agencies.

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.TotalTax attribute 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.
  • 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.
Note

The QuickBooks Online 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.

Click to see code.
{
    "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.

Click to see code.
{
  "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.

  • 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.

Input UnitPrice
(input with 8 places)

Saved UnitPrice
​(rounded to 7 places)
Line.AmountSaved Line.Amount
(rounded to 2 places)

Calculated
Sales Tax
(where tax rate = 12%)

 37.3749999937.375000037.3750000
(intermediate calculation)
37.38 4  4.49
 
  37.37499999
(input directly)
37.374.48
 

UnitPriceRounding.png

Overriding Sales Tax

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

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.

Click to see code.
{
    "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. 

Click to see code.
{
  "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:

  • 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. 
Click to see the Tucson TaxCode object.
{
  "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.
Click to see the TAX pseudo TaxCode object.
    "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 shows how the TaxCode object, Tucson,  is referenced in an Invoice.

File:0100_Accounting/0300_Developer_Guides/Global_tax_model/US_sales_tax_integrations/USTxnTaxDetail.png

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

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.  

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:

Click to see code.
{
  "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. 

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. As shipped, a US sandbox company is pre-populated with these tax agencies:

Click to see code.
{
  "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. 

USTaxAgency.png

 Got Questions? Get Answers in our developer forums.