Avalara Developer Network Developer avaTax

4.1 - Committing a Transaction

The concept of committing a transaction is necessary to separate preliminary estimates from final sales. Many types of connectors exist, for example:

  • A direct sales store might commit all transactions immediately and declare that all sales are final. Adjustments are handled by refunding all or part of the transaction.
  • A simple accounting system might only commit transactions after they have been verified. This allows a salesperson to quickly write transactions, which will then be double-checked by a back office employee before fulfillment. Adjustments are handled by modifying the transaction before it is locked for reporting.
  • A complex accounting system might provide multiple stages of verification. A transaction can be marked Posted after the first verification step, and Committed after the second. Adjustments are handled by modifying the transaction before it is reported.

Here’s how to implement commit for each of these scenarios.

Direct Commit

For software that considers all transactions final, you will create a transaction directly using the "commit": "true" flag in the CreateTransaction API call.

Creating transactions directly in Committed status is covered in Chapter 2 - Transactions.

One Stage Reconciliation

For software that permits transactions to be verified after creation, transactions are created with the Commit flag set to false. Transactions that have not been committed are stored with the status code Saved. They are considered to be provisional; they will not be reported to a tax authority until they have been verified.

Your back-end system should provide a way for your management team to review Saved transactions and perform reconciliation. A good way to design a verification process for a back-end systems team is to call ListTransactionsByCompany and pass in the parameter $filter=status eq Saved. This API call will list all transactions for your company that have not yet finished reconciliation, and you can use this to display a queue of transactions to be reconciled.

When a transaction has been reconciled and is final, your software will use the CommitTransaction API call to mark the transaction as committed. Here’s how to commit a transaction:

POST https://sandbox-rest.avatax.com/api/v2/companies/DEVGUIDE/transactions/MYTRANSACTIONCODE/commit

{
  "commit": "true"
}

Now that you have this process in place, let’s verify that your connector can set up a one-stage transaction correctly. This test case is required only for connectors that use one-stage reconciliation.

Test Case - 4.1.1

Setup

  • In your connector, create the following transaction:
    • Document Type: SalesInvoice
    • Document Code: Chapter-4-Test-1
    • Company Code: DEVGUIDE
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
  • Addresses:
    • SingleLocation
    • 100 Ravine Lane NE, Bainbridge Island, WA, 98110
  • Line #1:
    • Amount 100
    • TaxCode P0000000
  • Set the commit flag to false.
  • Calculate tax for your transaction.
  • Next, trigger a call to CommitTransaction with the following options:
    • Company Code: DEVGUIDE
    • Transaction Code: Chapter-4-Test-1
    • Commit: "true"

Assertions

  • The transaction's status will be "Committed".
  • CreateTransaction:
    {
      "type": "SalesInvoice",
      "code": "Chapter-4-Test-1",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "commit": "false",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }
                    
  • CommitTransaction:
    {
      "commit": "true"
    }
                    

Two Stage Reconciliation

Some companies prefer to have multiple stages of reconciliation. In this case, a transaction can go through three statuses: Saved, Posted, and Committed.

The three stages work as follows:

  • Create a transaction in the status Saved following the same process as for one-stage reconciliation.
  • Display a queue of transactions that are in the first stage of reconciliation using ListTransactionsByCompany with the parameter $filter=status eq Saved.
  • When a transaction is ready to move out of the first stage of reconciliation, update it by calling VerifyTransaction. The transaction's new status will be Posted.
  • Display a queue of transactions that are in the second stage of reconciliation using ListTransactionsByCompany with the parameter $filter=status eq Posted.
  • When a transaction is ready to move out of the second stage of reconciliation, update it by calling CommitTransaction as above. The transaction's new status will be Committed.

In the two-stage reconciliation process, additional verification features are available. When you call VerifyTransaction, you can optionally choose to assert that the transaction’s amount matches an amount in a different ledger. Here’s how the VerifyTransaction API call works:

POST https://sandbox-rest.avatax.com/api/v2/companies/DEVGUIDE/transactions/MYTRANSACTIONCODE/verify
 
{
  "verifyTransactionDate": "2017-06-15",
  "verifyTotalAmount": 100,
  "verifyTotalTax": 6.25
}

Your system can maintain and verify these fields if desired, but it is not required. If your system does not maintain all three values (date, amount, and tax), it is acceptable to verify only one or two of them.

When you provide this information, the API will test the transaction and report an error if any fields do not match. This feature allows you to perform automated reconciliation of transactions, and to detect discrepancies programmatically. Your software can call VerifyTransaction on all entries in your accounting system ledger every evening, and assert that the amounts match expectations. Any transactions that fail to verify can be escalated for human oversight.

The ListTransactionsByCompany API is intended to help you display a list of transactions that are in any particular stage of the reconciliation process. You can use it to examine any stage for transactions that need human review.

Let’s examine how a two-stage verification process would work:

Test Case - 4.1.2

Setup

  • In your connector, create the following transaction:
    • Document Type: SalesInvoice
    • Document Code: Chapter-4-Test-2
    • Company Code: DEVGUIDE
    • Customer Code: TESTCUSTOMER
    • Document Date: 2017-06-15
  • Addresses:
    • SingleLocation
    • 100 Ravine Lane NE, Bainbridge Island, WA, 98110
  • Line #1:
    • Amount 100
    • TaxCode P0000000
  • Set the commit flag to false.
  • Calculate tax for your transaction.
  • Next, trigger a call to VerifyTransaction with the following options:
    • Company Code: DEVGUIDE
    • Transaction Code: Chapter-4-Test-1
    • VerifyTransactionDate: 2017-06-15
    • VerifyTotalAmount: 100

Assertions

  • The transaction's status will be "Posted".
  • CreateTransaction:
    {
      "type": "SalesInvoice",
      "code": "Chapter-4-Test-2",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "commit": "false",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }
                    
  • VerifyTransaction:
    {
     "verifyTransactionDate": "2017-06-15",
     "verifyTotalAmount": 100.00,
     "verifyTotalTax": 9.00
    }
                    

Locked Transactions

The purpose of committing a transaction is to indicate that the transaction is ready to be reported to a tax authority. For customers using Avalara’s Managed Returns Service, our software will automatically prepare a liability worksheet for you every filing period and notify you to approve the tax filing. When you approve the tax filing, all transactions included on that filing are automatically Locked. A transaction that is locked cannot be changed further - it is considered a permanent part of your company’s accounting record, and must be preserved as is for audit circumstances.

You can determine which transactions are locked by calling the ListTransactionsByCompany API with the parameter $filter=locked eq true.

Any attempt to modify a locked transaction will fail with an error.