Should I commit?

As indicated previously your design should include the ability to disable document committing by setting these transactions toSalesOrder. This indicates that the transactions are temporary estimates that aren’t recorded to AvaTax. This is useful, for example, for showing the current cost in a shopping cart before taxes are calculated. In this section, we’ll take a look at how thecommit field works.

Transaction state

When you create a transaction, the information about that transaction is referred to as a “Document”. You will see many comments or articles that refer to “Documents” rather than transactions - it helps if you think of the “Transaction” as the API call and the “Document” as the data that is stored on disk.

Once created, a document moves through a few different states before it is collected and reported on a tax return:

As you can see from the lifecycle document above, a transaction can go through a number of steps before it is finalized. We have designed these steps to be flexible enough to solve problems for a variety of different customers and different types of tax processes. Let’s start with a few common use cases.

In an online store, your first task is to provide a sales tax estimate for the user casually browsing through your website. These casual visitors have not purchased anything yet, but by giving them an accurate tax estimate you can show off your store’s high quality and commitment to accuracy. To help out this customer, you call CreateTransaction with the transaction type set toSalesOrder. This gives you an accurate estimate of tax (assuming the customer put in their address correctly!), but it won’t record any tax data yet because the customer hasn’t bought anything.

When the customer chooses to finish their transaction, your storefront should call CreateTransaction again, but this time you should set the transaction type toSalesInvoice and thecommit value totrue. These two values cause the transaction to be recorded into AvaTax, and it can then be collected and filed on a tax return.

The reason you have to contact the API a second time may not be immediately obvious - but the customer may have waited long enough that the tax rates might have changed, or their address may have changed, or your company configuration may have changed. Any one of these small changes can affect the accuracy of a tax calculation, especially when an online storefront is still capable of selling to customers at 11:59 PM on the night before a sales tax holiday!

Advice: If you calculate tax on aSalesInvoice and nothing has changed, you can use the VerifyTransaction and CommitTransaction methods to make sure your data is in exactly the same state between your ecommerce site and AvaTax. This is more efficient than creating a transaction usingcommit=true.

Previous

Next