API Docs & Tools Blog Help
Using QuickBooks Online API for automated sales tax - Intuit Developer Community Blog

December 11, 2017 | admin

Using QuickBooks Online API for automated sales tax

As of November 10, 2017, all new US QuickBooks Online companies manage sales tax calculations via an automated sales tax (AST) engine. Sales tax is computed automatically on the sales transaction based upon the shipping address and the location of the company rather assigning sales tax manually. Read more about how QuickBooks Online implements automated sales tax here.

Here are a couple of things to keep in mind when creating transactions using the QuickBooks Online API:

  • The AST engine assigns the appropriate tax code to sales transaction objects and automatically calculates the tax amount.
  • Whenever an explicit tax amount is sent in the transaction request the AST engine honors the amount and prorates it across tax rates in the AST-assigned tax code.

Automated sales tax at a glance

Customer default tax code No longer available or visible. Customer.DefaultTaxCodeRef populated with company’s default tax code as defined by AST.
Company default tax code Set via AST based on the tax agency. TaxCode object created by AST.
Company default tax agency AST sets the default tax agency. Subsequent ones can be added manually. TaxAgency object created by AST.
Create operation available for TaxCode objects No. Can create and assign on transactions but will be overridden by AST. Create operation exists for backward compatibility with existing apps and can be queried.


How does the automated sales tax engine calculate taxes?

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.

For the complete list of factors that go into an automated sales tax calculation, refer here.

If a QuickBooks Online company is using automated sales tax, will it still be possible to use the TaxService API to create new TaxCode and TaxRate objects?

Yes, creating TaxCode, TaxRate, and TaxAgency objects is still possible for backward compatibility to support existing apps. They can be accessed by the API but are not visible in the UI.

The app can include a user or API created tax code in the transaction request payload but AST overrides the code with its recommendation.

When will automated sales tax be enabled on my QuickBooks Online company?

Migration will happen over the course of next year. Companies created after November 10, 2017 are already enabled.

If a third-party app is creating a sales transaction, how does the app present the correct sales tax to the end user before it has been sent to QuickBooks Online?

At the moment, the app cannot present the AST-recommended sales tax to the user until the transaction is first saved to the QuickBooks Online company. This capability will be available in V4 of the API. The following process is recommended for apps implementing V3 of the API:

  1. Create a TaxCode object via API using the Taxservice resource that serves as a proxy, named Sales Tax Code, with an arbitrary percentage like 5%. This is not visible on the QBO Sales Tax screen, but can still be queried via API.
  2. Associate this proxy TaxCode object to all transactions that are posted to QuickBooks Online.
  3. QuickBooks Online services swaps out the proxy TaxCode for the AST-recommended TaxCode object.
  4. Thereafter, when the transaction is read back, the right sales tax is returned.

Are TaxCode objects still available to attach to transactions?

An app can still attach a TaxCode object to a transaction, but the automated tax service replaces an incorrect TaxCode object with one that is correct for the transaction.

How does an app determine if a company is automated tax service enabled?

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.
  • If false, automated sales tax is enabled for the company but the company doesn’t have sales tax set up.
  • If not present in response payload, the company is not enabled for automated sales tax.

Is automated sales tax supported in sandbox companies?

Not at the moment. We are working on adding support.

Which QuickBooks Online locales are affected?

US locales, only.

Considerations for existing integrations

Use case Tax objects used in the transaction request payload Pre-AST behavior AST behavior
Specifying sales tax TxnTaxDetail.TxnTaxCodeRef Tax amount calculated based on associated tax rates in the tax code. Ignore TaxCode passed in and calculate tax based on AST-assigned tax code.

TxnTaxDetail.TxnTaxCodeRef in response payload is changed to AST-recommended tax code.

Overriding sales tax TxnTaxDetail.TxnTaxCodeRef
Prorates supplied tax amount across associated tax rates in the tax code. TxnTaxDetail.TotalTax amount is honored. Supplied tax amount is prorated across associated tax rates in the AST-assigned tax code. TxnTaxDetail.TxnTaxCodeRef in response payload is changed to AST-assigned tax code.


View all
Load more comments