In order to better support our U.S. QuickBooks Online customers, a Hybrid Sales Tax experience has been introduced in QuickBooks that will allow customers to take advantage of AST (Automated Sales Tax) features, but still retain the key functionality from Classic Sales Tax experience. Using the new hybrid sales tax model, customers who are switching from the classic sales tax experience can now map their classic sales tax codes against U.S. sales tax agencies available under AST.
With the latest API release, we are pleased to announce support for Hybrid Sales Tax using the API as well.
What changes will customers see in Hybrid experience?
After customers have been migrated to Hybrid Sales Tax, they will be required to complete the setup flow and map their classic (manual) tax codes to the AST agencies. This is the same experience today with migrating from Classic/Manual sales tax to AST with the added benefit that going forward, these user-defined classic tax codes will be usable within the AST experience.
With the Hybrid Sales tax experience, customers will not only have the ability to add agencies using AST, but will also be able to enter custom rates.
On the Invoice screen, customers will now see an option that allows them to specify whether sales tax should be calculated based on Location (using AST engine based on location of sale/shipping address) or using custom tax rates (using the tax rates manually created by you or the small business owner).
Customers can create manual rates from the Sales tax settings page as well as from the sales transactions page.
How does this impact app developers?
Since Hybrid experience will be rolled out eventually to all of our U.S. based customers by the end of 2020, apps can now make sure they support hybrid experience.
Follow the instructions below to understand how to send requests for Hybrid experience.
Use case 1: Sending an invoice requesting QuickBooks to apply tax as per AST rules.
In this scenario, we’ll send an Invoice request and let QuickBooks Automated Sales Tax engine determine the total tax amount and tax codes based on location (ShipFrom/ShipTo) information. In the sample below, QuickBooks AST engine determined a 9% tax based on the location information.
Request JSON
Response JSON (Truncated to show only tax breakdown information). AST determined the $9 tax amount split as 1% + 1.75% + 6.25% tax codes for that location.
Invoice on UI
Use case 2: Sending an invoice by overriding the Tax Amount – QuickBooks will honor the amount but will apply the AST tax codes internally.
In this scenario, we’ll send an Invoice request and ask QuickBooks AST engine to use the total tax amount of $12 sent in the request. QuickBooks AST engine will apply the total amount of $12 and internally map it to the AST tax codes based on location adjusting the tax percentages..
Request JSON
Response JSON (Truncated to show only tax breakdown information). The $12 tax amount sent in the request is honored and split as 1.33% + 2.34% + 8.33% tax codes for that location.
Invoice on UI
Use case 3: Sending an invoice requesting QuickBooks to apply tax based on the tax code that you or the small business owner created manually in the classic experience.
In this scenario, we’ll send an Invoice request and ask QuickBooks Sales Tax engine to determine the total tax amount based on the user defined classic sales tax code sent in the request.
Request JSON
Note: Make sure to send user defined manual tax code under TxnTaxDetail->TxnTaxCodeRef. In order to identify which tax code belongs to classic sales tax and which one is AST generated, query TaxCode endpoint using minor version 51 and verify the field TaxCodeConfigType – USER_DEFINED to determine the manual tax code. Additionally, the TaxAgency associated with the tax rate used in the TaxCode should be a system generated Tax Agency. This can be identified by querying the TaxAgency endpoint using minor version 51 and verify the field TaxAgencyConfig – SYSTEM_GENERATED.
Sample response for TaxCode request using minor version 51:
Sample response for TaxAgency request using minor version 51:
Response JSON for Invoice (Truncated to show only tax breakdown information). The $10 tax amount is calculated based on the user defined classic sales tax TaxCodeRef=7 which maps to 10% rate.
Invoice on UI
Use case 4: Sending an invoice by overriding the Tax Amount for Manual Tax Code scenario – QuickBooks will honor the amount but will apply the manual tax codes internally.
In this scenario, we’ll send an Invoice request and ask QuickBooks Sales Tax engine to use the manual sales tax code of 10% tax but override the total tax amount to $9 as sent in the request. QBO Sales tax engine will apply the amount and map it to the manual tax code.
Request JSON
Response JSON (Truncated to show only tax breakdown information). The $9 tax amount sent in the request is honored internally mapping it to the 10% tax code (TaxCodeRef=7) sent in the request.
Invoice on UI
Note: For UseCase 3 and 4 to work, make sure to send user defined manual tax code under TxnTaxDetail->TxnTaxCodeRef. In order to identify which tax code belongs to classic sales tax and which one is AST generated, query TaxCode endpoint using minor version 51 and verify the field TaxCodeConfigType – USER_DEFINED to determine the manual tax code. Additionally, the TaxAgency associated with the tax rate used in the TaxCode should be a system generated Tax Agency. This can be identified by querying the TaxAgency endpoint using minor version 51 and verify the field TaxAgencyConfig – SYSTEM_GENERATED. Sending incorrect tax code or system generated tax codes in these scenarios will result in QuickBooks applying AST tax calculation logic.
Will the hybrid sales tax model break existing apps?
No. In the past, the only use cases supported by API were use cases 1 and 2 mentioned above. These will continue to work with no impact to your app or the customers.
With the latest API release under minor version 51, app developers will have the capability to support additional use cases (use cases 3 and 4).
Do app developers need to make any updates to their app?
No immediate updates are needed, your app will continue to work as is. However, if you wish to extend your app to support these additional use cases then we recommend following the instructions above to add that capability in your app.
Additionally, please note that within the calendar year, all QuickBooks customers will have access to the Hybrid Sales Tax experience and therefore the ability to create and use their own rates within the Automated Sales Tax experience.
For more information about individual entities or fields, refer to the API Reference.
Have additional questions or comments? Share them on our developer forums!
Leave a Reply