Avalara Developer Network Developer avaTax

2.3 - Should I Commit?

Both transactions we created in the previous section were SalesOrder transactions, meaning they were temporary estimates that weren’t recorded to the AvaTax website. This is great for showing a shopping cart, are others where you’ll want to actually record the transaction. In this section, we’ll take a look at how the commit field works.

The Transaction State Diagram

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 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 and the commit value to true. 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!

Let’s take a look at an example API call to create a committed transaction:

Test Case - 2.3.1

Setup

  • In your connector, create the following transaction:
    • Document Type: SalesInvoice
    • Document Code: Chapter-2-Test-4
    • Company Code: DEVGUIDE
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
    • Addresses:
      • SingleLocation
      • 100 Ravine Lane NE, Bainbridge Island, WA, US 98110
    • Lines:
      • Number: 1
      • Quantity: 1
      • Amount: 100
    • Commit: True
  • Calculate tax for your transaction using AvaTax.

Assertions

  • Since this is a 'SalesInvoice' transaction with "Commit" set to "True", the transaction will be recorded and visible on the AvaTax website.
  • You can log onto the AvaTax website and find this transaction. The transaction is in status: Committed.
  • {
      "type": "SalesInvoice",
      "code": "Chapter-2-Test-4",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "01",
          "quantity": 1,
          "amount": 100
        }
      ],
      "commit": true
    }
    


Now we’ll take a look at how the transaction we just created looks in AvaTax. To view this transaction, please navigate to your development account AvaTax website and then click the Transactions tab. You search for the transaction by the DocumentCode you used. If you don’t find any results, check your Date Range options.

You can use the AvaTax website to review and reconcile transactions - we’ll cover that topic more in Chapter 4 - Reconciliation. For now, let’s continue onwards to learn about other types of transactions besides sales.