When to commit

In the Avalara system, transactions (“line items”) can be associated with Document Codes. A Document Code (doc) is a unique identifier. Each Document Code has a status of committed (“true”) or uncommitted (“false”).

You can think of a Document Code’s commit status as a simple flag that determines if a transaction should appear on your compliance reports for remittance to the Department of Revenue at the end of your filing period.

Managing Document Codes in your application is critical to a successful implementation. Good Document Code management also makes the compliance reporting experience significantly easier for your downstream users.

The Commit API is often used when not all calculated taxes are deemed final for compliance reporting.
When a transaction is deemed final, you can commit the Document Code associated with the transaction(s) via the Commit API.
You can commit an entire invoice by committing the Document Code associated with that invoice rather than recalculating the taxes.
You do not need to commit or uncommit transactions in real time - you only need to ensure your Document Codes have the correct commit status before reconciliation or report generation begins, usually at the end of a filing period.
Committed Document Codes are locked (they cannot be uncommitted) on the 1st day of the subsequent calendar month in which they are sent. For example, if you commit a Document Code on November 15th, that Document Code will be locked on December 1st.

Notes: Committing or uncommiting a Document Code affects all transactions associated with that Document Code. It is important to use unique identifiers for Document Codes to give you the flexibility to commit and uncommit specific transaction(s) later.

For example, let’s say you have a bill run that consists of 1,000 invoices, each with 10 line items per invoice, and you use the same Document Code for each invoice. When the bill run is complete, one of your Tax Analysts determines there is an error in one of the invoices. Because the same Document Code was used for each invoice, you cannot simply uncommit the Document Code associated with the bad invoice and remove it from your data set. You must uncommit the entire bill run, or send an adjustment for that specific invoice and send a new, corrected invoice. The Commit API makes it easy to correct mistakes like this.

Using the Commit API

The Commit API gives your application the ability to choose the data that should appear in your compliance reports. A Document Code’s default commit status is uncommitted.

To use the CommitAPI:

Create new transactions at any point in the billing cycle.
Populate the Document Code (doc) with a unique identifier (for example, a randomly generated GUID). Document Codes can be used to group transactions together between invoices, but be aware of associating too many transactions with a single Document Code. This makes it more difficult to uncommit specific transactions later.
Use the Commit (cmmt) flag to identify transactions to include in or exclude from the compliance report for the reporting cycle.

It’s not necessary to set the cmmt flag immediately on a transaction. You can use the Commit API to update the cmmt flag.

Important: If you send a Document Code through the CalculateTaxes API as uncommitted, you can only change its commit status through the Commit API; you cannot change a Document Code's status through the CalculateTaxes API.

Commit scenarios

The first call for a given code (doc) establishes the committed state of the document and of all subsequent calls to AFC with that same document code. (Even if you try to set the cmmt flag to something else in the CalculateTaxes request, the commit state will not change.) The cmmt flag in the CalculateTaxes request is a "use-once" feature that establishes the state of all the transactions for particular document on its first call using CalculateTaxes in a particular reporting month.

The attribute invn attribute is used to ensure matching between systems.

The attribute doc is used to make sure you have a method to keep track of your calls to AFC and to keep track of blocks of transactions.

For example:

You could call the CalculateTaxes API with a doc of 1 and an invn of 1, and set cmmt: true in your first call. This call will be recorded and committed to AFC (tax liability is recorded).
You could call the CalculateTaxes API with a doc of 1 again, an invn of 1, and set cmmt: false in your second call. In this case, the commit flag has no effect, and you have just doubled the tax liability for invn 1.
You could call the CalculateTaxes API with a doc of 1.1, an invn of 1, and set cmmt: true. From a reporting perspective, you now have all three calls tied to invn 1.
You could call the Commit API for doc 1 and set cmmt: false. Now you have essentially removed the tax liabilities created in calls 1 and 2 above. For invn 1 you still have tax liabilities based on the call made in step 3 using doc 1.1.

To change the state of a give doc after the first call using CalculateTaxes for that doc, you must use the Commit endpoint. Calling this endpoint can also provide verification that all is well with the doc and the state of the document.

Given this information, let's war game a scenario and make sure you understand how get to get tax liabilities committed consistently for all the various document types in your application for a single Customer entry — a happy path with no efficiencies: