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

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.

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

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

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 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 rateTaxRate

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 agencyTaxAgency

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.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.
  • For companies using automated sales tax, sales tax is calculated based on the AST-assigned tax code. Any other TaxCode reference passed in with the request is overridden with an AST-assigned TaxCode object.
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.

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

For companies using automated sales tax, TxnTaxDetail.TotalTax amount is honored. Supplied tax amount is prorated across associated tax rates in the AST-assigned tax code. TxnTaxDetail.TxnTaxCodeRef passed in with the request is overridden with an 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.

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. 
     For companies using automated sales tax, QuickBooks Online automatically creates the appropriate tax code objects when sales tax is configured. 

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.  

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. 

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. 

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:

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

Learn more

View the TaxCode reference here and TaxAgency here.


Did you find this page helpful?
Your feedback helps us make our docs better. Please let us know if this page helped you, or if it needs improvement.

 Got Questions? Get Answers in our developer forums.