When to commit

As indicated previously, your design must provide the ability to disable document recording by setting transactions to SalesOrder. This indicates that the transactions are temporary estimates don't get recorded in AvaTax. The purpose of this is to show the current cost in a quote before calculating taxes. In this section, we’ll look at how the commit field works.

Transaction state

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

Once created, a document moves through a few different states:

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

In a typical transaction, your first task is to provide a tax estimate for the user. To do this, call CreateTransaction with the transaction type set to SalesOrder or PurchaseOrder. This gives you an accurate estimate of tax (assuming the user entered the address correctly!), but AvaTax won’t record any tax data because the user hasn’t bought anything.

When you’re ready to complete the transaction, call CreateTransaction again, but this time, set the transaction type to SalesInvoice or PurchaseInvoice and the commit value to true. These two values cause the transaction to be recorded into AvaTax. It can then be collected and included in reports.

The reason you have to contact the API a second time may not be immediately obvious - but the ship to address may have changed, your company configuration may have changed, your company may be newly established in a country, and so on.. Any one of these small changes can affect the accuracy of a tax calculation.

Tip

If you calculate tax on an uncommitted SalesInvoice and nothing changed, you can use the VerifyTransaction and CommitTransaction methods to make sure that your data is in exactly the same state between your environment and AvaTax.