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.




22 responses to “Using QuickBooks Online API for automated sales tax”

  1. sachin Avatar

    Is there any way to getting “Same as billing address” in API side ,this feature is In Quickbooks UI side but not in API docs?

    1. nimisha Avatar

      This isn’t supported by Customer entity via QBO API.

  2. nimisha Avatar

    Developer please note that sending TxnTaxDetail.TxnTaxCodeRef is mandatory to show your intent of applying the AST(automated sales tax) to the Txn.

  3. Dan Avatar

    We appreciate the effort that went into creating the Automatic Sales Tax calculation, and we know it will make life easier for a lot of users, but you should know that this creates a serious problem for construction businesses.

    It is technically not possible for Automatic Sales Tax calculation to accurately calculate taxes for construction businesses because, in some locations, tax is calculated based on the type of cost: materials, labor, equipment, subcontractor, etc. QuickBooks does not have a way to do this.

    The complicated calculation of sales tax for construction is one of the reasons our construction specific estimating and invoice app is needed. Everything has been fine until now because the QB API allows our app to calculate and overwrite the taxes calculated in QB. This still works until the user opens the transaction in the QB UI; at that point QB re-calculates and overrides the tax that was written by our app.

    This is not just a problem for our app; it is a problem for all construction business users. We humbly request that you add a QuickBooks setting that will allow users to turn Automatic Sales Tax calculation off.

    1. Priyadarshini Avatar

      Dan – Thank you for your feedback! The expected behavior is that when an app sends the tax amount and tax code, we honor the tax amount but override the tax code in the UI. Opening the transaction in the UI should not trigger a recalculation or override – this is a bug and the team is working on a fix for this. We will let you know once the fix is in place. Recalculation will happen only when certain fields on the transaction are updated through the UI, for eg: amount, quantity, shipping address, etc. Would that be an acceptable solution?

      1. Priyadarshini Avatar

        We have now rolled out the fix to not trigger recalculation when the transaction is opened in the QBO UI. Could you please let me know if you are still seeing issues. Thanks!

  4. Virginijus Avatar

    I think this is very important for most of third-party app creators and users.
    Your provided workaround will not work in case when we create work order on third-party system and only later invoicing it – taxes should match on work order and invoice.
    So the main and only question is – When we can expect API V4 released?

    1. Priyadarshini Avatar

      Thanks for your comment. We are aware of this use case and we are currently working on a design that will help you address this concern. When we have an updated design, can I reach out to you for a quick review so we can ensure that it addresses your concern? We are diligently working on making our v4 APIs available, we will share the timelines through the blog as we get closer to the release.

      1. Tom Avatar

        Are there any updates on v4 API? I have not seen any posts in the blog regarding this. Thanks

      2. jessicah@gtsservices.com Avatar

        When will the v4 APIs be available. I’m having to advise new clients that they cannot use QuickBooks until this is addressed. It leaves them with a very poor impression of both applications.

  5. Dx1 Avatar

    We have inventory items that are taxed at the buyers location and others that are taxed at the sellers location, how can i have both of these on an invoice and get the correct tax amount to be shown

    1. Priyadarshini Avatar

      Thanks for your question. In our current design, we do not provide the app with the option of specifying which address should be used for calculating tax. Our tax engine determines whether the source/destination address should be used. Right now, it might be best for you to specify the tax amount based on your existing logic and we will honor that amount in the UI. In the next rev of our APIs (v4), we will try to provide this capability through our APIs, so the app can leverage our tax engine more effectively.

  6. Tom Avatar

    The process of using a Proxy does not seem to work for me. Can you please tell what I am doing wrong or point me to more resources?

    Here is my tax code created:
    {“Name”=>”Sales Tax Code”, “Description”=>”Sales Tax Code”, “Active”=>true, “Taxable”=>true, “TaxGroup”=>true, “SalesTaxRateList”=> {“TaxRateDetail”=> [{“TaxRateRef”=>{“value”=>”10”, “name”=>”Sales Tax Code”}, “TaxTypeApplicable”=>”TaxOnAmount”, “TaxOrder”=>0}]}, “PurchaseTaxRateList”=>{“TaxRateDetail”=>[]}, “domain”=>”QBO”, “sparse”=>false, “Id”=>”6”, “SyncToken”=>”0”, “MetaData”=> {“CreateTime”=>”2018-02-01T21:55:29-08:00”, “LastUpdatedTime”=>”2018-02-01T21:55:29-08:00”}}]

    I am sending this to create a salesreceipt
    “TxnTaxDetail”=>{“TxnTaxCodeRef”=>{“value”=>6}, “TotalTax”=>3.92}

    and the response is “TxnTaxDetail”=>{“TxnTaxCodeRef”=>{“value”=>”2”} which is {“Name”=>”Out of scope”, “Description”=>”Out of scope”

    When I look at Sales tax link on Salesreceipt created with api, it says “Amount we recommend” is $0.00.

    If I manually enter an order with same customer, it displays how the tax was created with the correct tax.


  7. Christine Avatar

    We do not want to be forced to use automatic sales tax calculation in QuickBooks–this function should be optional for each account to decide for themselves and turn on or off. It’s taken a long time and many hours of accountant consultation for us to get our sales tax to calculate accurately and we’ll be very upset if this work gets undone. We still want access to see and control the tax rates, as we have now.

    1. mneyman@yesco.com Avatar

      We’ve been down this road Christine as well with our company. We’ve argued until we were blue in the face. They won’t have it as an option…extremely frustrating move by intuit.

  8. David Avatar

    When are we going to have access to the updated documentation of the API v4? We need to do the corresponding changes in our app in order to it can handle correctly these companies using the AST engine.
    We need to know how we can calculate the right tax amount for a sale prior to it is completed in our app and then sent to QBO.

    1. Priya Avatar

      We do not have an ETA for the v4 Sales tax APIs yet. We are currently working on the v4 API design and we will keep you posted on the timelines. I will update the blog here once we are closer to release.

  9. Bryan Avatar

    This AST may work for some but not all, when companies are integrating a 3’rd party apps and need to control the sales tax on our end. This implementation AST seems a little incomplete, limited in functionality and premature right now.

    Setting that aside, how do we workaround the AST so that we set the sales tax on our end prior to creating the invoice via API?

  10. Maximiliano Avatar

    Hi, we are re-writing our integration, and we found this improvement. We had customers on the UK, US and AUS that probably are going to use Quickbooks.
    I was wondering how to handle properly this subject, in order to avoid future problems with our mutual customers.


  11. admin Avatar

    “We need to know how we can calculate the right tax amount for a sale prior to it is completed in our app and then sent to QBO” Me too. Any updates when that might be available?

    1. admin Avatar

      I too am wondering this.

      1.  Avatar

        Where is it!

Leave a Reply

Your email address will not be published. Required fields are marked *