Lifecycle of a Transaction
The centerpiece of Avalara’s world-leading AvaTax service is the ‘Transaction’. A Transaction can reflect one of many different types of business documents, and it’s worth discussing how a transaction can change over time. Let’s begin by understanding how a “Sales” transaction is created, and how it can change over time.
The Transaction State Diagram
In AvaTax, a sales transaction is an exchange that occurs between two companies. Although other types of transactions exist that can be within a single company - for example, inventory transfer transactions - in today’s use case we will only examine transactions that occur between two companies.
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. For today’s article, we will refer to Transactions as the API, and Documents as the values returned back from the API calls.
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. Clearly, the way you use AvaTax can be uniquely suited to your business. Let’s start with a few common use cases.
Scenario 1: Online Storefront
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 to
SalesOrder. 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 to
SalesInvoice. This causes the transaction to be recorded into AvaTax, and you’ll be able to check on it later. 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!
Scenario 2: Reconciliation
Let’s say your company has a reconciliation process in place. Perhaps you know that your customers tend to ask for adjustments to their orders frequently, or perhaps you just like assigning someone to verify all the orders placed by the sales team each night. In this case, you should submit your
SalesInvoice transaction with the
commit flag set to false, and your transaction will be recorded in the
How is this different than the alternative? If you don’t have a reconciliation process, you should set the
commit flag to true on all transactions, and they will all be created directly into
Committed status. A transaction in
Committed is eligible for reporting - that means that, if you subscribe to Avalara Managed Returns, Avalara will take this transaction, bundle it up into a monthly, quarterly, or annual tax return, and file it for you. We won’t file any transactions that are in
This process flow is designed to allow you to have an independent verification step before any taxes are filed on your behalf. There are millions of different reasons to want to have a multi-step process; but to Avalara, every use case is business critical for someone. Here’s how it would work for your team:
- Alice creates a transaction on Monday using
false. The transaction is recorded in
- Bob reviews the nightly transaction list, and calls VerifyTransaction to make sure that the data stored in AvaTax matches the data stored in his accounting system. If any disrepancies exist, the Verify call will return an error; otherwise, the Verify call will move the transaction to
- Charlie works in the warehouse, and she reviews the transactions a second time prior to fulfillment. She makes the final decision whether to accept, reject, or adjust transactions. If the transaction is accepted, she calls CommitTransaction, and if the transaction should be voided, she calls VoidTransaction.
You can easily bypass the
Posted step if you would like to go directly to
Committed; but please be careful. If you file a document and then someone requests a refund, you’ll have to handle …
Scenario 3: Refunds and Changes
Refunds are the next big complication. How do you properly issue a refund to a customer? The answer, not surprisingly, is that the correct answer varies depending on where the document is in the lifecycle.
- If the transaction is in
Committed, it's easy to give a refund. This transaction hasn't been reported to the government yet! You can simply call VoidTransaction - and the document will be moved to the
- If the transaction is in
Lockedstatus, things are a bit tougher. You will need to create a
ReturnInvoicetransaction to issue a refund to the customer. The
ReturnInvoicetransaction should be basically the opposite of the original transaction you sent. This
ReturnInvoicenow has to go through the same steps that the original
SalesInvoicewent through above - it needs to be reviewed, committed, and then eventually reported to the government. Just like you gave the customer their money back, the government will now refund you the sales tax you paid on the original invoice.
- If the customer doesn't want to refund the entire transaction, you can consider calling AdjustTransaction. This API call marks the old transaction as
Adjustedand creates a new transaction with the same transaction code with the updated information. This works well if the salesperson made a mistake and needs to adjust a shipping address, or if a small change was made before anything shipped out of the warehouse.
In many accounting systems, a transaction is considered a permanent record that cannot be modified. If your company elects to use this approach, you should not void any transactions for any reason. You should allow the original transaction to be
Committed and then
Locked, and proceed directly to creating a
ReturnInvoice for the refund.
Putting it All Together
The document lifecycle in AvaTax supports more features and use cases than I can describe briefly here. There are dozens of different ways to design an integration with AvaTax, and our sales engineers are constantly meeting with new customers and ensuring that your business is supported properly throughout AvaTax.
Here’s hoping your orders are committed smoothly!
–Ted Spence, Director, AvaTax Core Engine