Skip to main content
Avalara Help Center

AvaTax for Communications SaaS Pro Commit/Uncommit Process

Learn how to manage the document status of transactions in AvaTax for Communications to control which transactions are included on reports.

Overview

AvaTax for Communications provides the ability to manage the document status of transactions as a way to identify which transactions should be included in the Compliance Reports for remittance to the Department of Revenue (DoR). When a document is considered final, a Commit API call can be sent to change the document status to 'committed', indicating that the transaction should be included on Compliance Reports. This also allows users to commit an entire invoice by using the document code instead of calculating the taxes again when the document is determined to be final.

Document status

The document status options are:

Status Description
Uncommitted The details of this transaction have not been finalized, and it will not be included on Compliance Reports.
Committed This details of this transaction have been finalized, and it will be included on Compliance Reports for tax compliance reporting and remittance to the Department of Revenue (DoR).

For more information on the impact of document status in AvaTax for Communications, see the Document status in AvaTax for Communications guide.

Supporting Commit/Uncommit Field(s)

Field Values and Data Structure Tables

The following fields must be provided within the tax calculation APIs in order to support this feature.

Data Fields for Commit Feature - Data Definition

Field

Value

Data Type

Description

DocumentCode

User-defined, 150 character limit, Alphanumeric

String

Value that identifies a transaction, quote, or invoice in the calling system. The value is provided by the user when performing the tax calculation.

 

VALIDATION:

  • Value must not be longer than 150 characters.

Commit

True

False (Default)

Nullable<bool>

Nullable Boolean field indicating if the DocumentCode should be committed as soon as the tax calculation is processed.

 

NOTES:

  • Nullable value is used in order to make field optional for backwards-compatibility purposes.
  • Transaction will not be committed if an error occurred during processing.
  • If a DocumentCode is provided but Commit is null, Commit will be defaulted to false when saving the information.
  • If Commit is true, DocumentCode must not be empty.

 

The following data structure is passed as a parameter to the CommitTransactions API:

CommitData - Data Definition

Field

Value

Data Type

Description

DocumentCode

User-defined, 150 character limit, Alphanumeric

String

Document code for transactions to commit or uncommit.

Committed

True

False

bool

Indicates if document code should be committed or uncommitted.

CustomerNumber

User-defined

String

Optional. 20 characters max.

InvoiceNumber

User-defined

Nullable<int>

Optional

Optional

User-defined

Nullable<int>

Optional

Optional4

User-defined

Nullable<int>

Optional

Optional5

User-defined

Nullable<int>

Optional

Optional6

User-defined

Nullable<int>

Optional

Optional7

User-defined

Nullable<int>

Optional

Optional8

User-defined

Nullable<int>

Optional

Optional9

User-defined

Nullable<int>

Optional

Optional10

User-defined

Nullable<int>

Optional

OptionalAlpha

User-defined

String

Optional. 20 characters max.

OptionalFields

User-defined

OptionalField[]

Array of OptionalField objects.

Note: When reports are generated, the optional fields provided in this data structure replace the corresponding values originally provided in the transactions at the time of processing the tax calculations. Please leave the values null to avoid replacing the original transaction values.

Support for Single Transaction Tax Calculation APIs

When processing tax calculations in non-Invoice Mode tax calculation APIs, the DocumentCode and Commit fields must be provided within the body of the Transaction or SalesUseTransaction data structures. Please see the API Samples section for an example of how to provide this information through the APIs.

Support for Invoice Mode API

Within the Invoice Mode tax calculation APIs, it is not necessary to provide the DocumentCode and Commit fields within each transaction. Instead, these fields are provided as separate parameters within the body of the ProcessCustomerBatch, ProcessCustomerBatchV2, CalcTaxesInCustMode or CalcTaxesInCustModeV2 APIs. Please see the SOAP Samples section for an example of how to provide this information through the APIs.

Supporting Commit/Uncommit API(s)

The commit API, CommitTransactions, provides users with the ability to change the Commit flag for transactions tied to a DocumentCode.

Tip icon After the reporting cycle, all DocumentCodes with Commit flags set to True are locked and cannot be modified once the compliance report is generated. Users may, however, commit previously uncommitted DocumentCodes via the commit API. To request an updated compliance report, please  submit a support case.

Summary

The CommitTransactions API is used to commit or uncommit a DocumentCode.

Parameters

A CommitData object is required as a parameter in order to specify a valid DocumentCode and a Boolean indicating whether transactions with the specified DocumentCode should be committed or uncommitted. Any optional field values provided in this parameter are used when reports are generated in order to replace the corresponding values originally specified within the transaction at the time of tax calculation processing.

Validation

DocumentCode in the input data parameter must not be blank or null.

DocumentCode cannot be longer than 150 characters.

DocumentCode must match a DocumentCode provided previously when performing a tax calculation.

Returns

Boolean indicating success or failure.

Note: Exception thrown with appropriate error message in case of failure.

Errors

DocumentCode cannot be blank or null.

DocumentCode not found.

DocumentCode has been locked.

API Samples

The API samples below are the contents within the SOAP body (SOAP headers are excluded).

Note: Please refer to https://communications.avalara.net/swagger/ui/index.html for REST version of the API Samples.

Single Telecom Transaction Example

<CalcTaxesWithPCode xmlns="http://tempuri.org/"> 
    <aTransaction xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <a:AdjustmentMethod>0</a:AdjustmentMethod> 
        <a:BillToPCode>442200</a:BillToPCode> 
        <a:BusinessClass>1</a:BusinessClass> 
        <a:CategoryExemptions i:nil="true"/> 
        <a:Charge>123.45</a:Charge> 
        <a:Commit>false</a:Commit> 
        <a:CompanyIdentifier>XYZ</a:CompanyIdentifier> 
        <a:CountyExempt>false</a:CountyExempt> 
        <a:CountyPCode>0</a:CountyPCode> 
        <a:CustomerNumber>Test123</a:CustomerNumber> 
        <a:CustomerType>1</a:CustomerType> 
        <a:Date>2017-04-04T00:00:00-05:00</a:Date> 
        <a:Debit>false</a:Debit> 
        <a:DiscountType>3</a:DiscountType> 
        <a:DocumentCode>086b565c-e12b-4f26-b716-19f734e11302</a:DocumentCode> 
        <a:Exclusions i:nil="true"/> 
        <a:ExemptionType>3</a:ExemptionType> 
        <a:Exemptions i:nil="true"/> 
        <a:FacilitiesBased>true</a:FacilitiesBased> 
        <a:FederalExempt>false</a:FederalExempt> 
        <a:FederalPCode>0</a:FederalPCode> 
        <a:Franchise>true</a:Franchise> 
        <a:Incorporated>true</a:Incorporated> 
        <a:InvoiceNumber>98765</a:InvoiceNumber> 
        <a:IsPrivateLine>false</a:IsPrivateLine> 
        <a:Lifeline>true</a:Lifeline> 
        <a:Lines>5</a:Lines> 
        <a:LocalExempt>false</a:LocalExempt> 
        <a:LocalPCode>0</a:LocalPCode> 
        <a:Locations>3</a:Locations> 
        <a:Minutes>115.55</a:Minutes> 
        <a:OriginationPCode>443800</a:OriginationPCode> 
        <a:PrivateLineSplit>0</a:PrivateLineSplit> 
        <a:Regulated>true</a:Regulated> 
        <a:SafeHarborOverrides i:nil="true"/> 
        <a:Sale>true</a:Sale> 
        <a:ServiceClass>1</a:ServiceClass> 
        <a:ServiceLevelNumber>3456</a:ServiceLevelNumber> 
        <a:ServiceType>6</a:ServiceType> 
        <a:StateExempt>false</a:StateExempt> 
        <a:StatePCode>0</a:StatePCode> 
        <a:TaxInclusive>false</a:TaxInclusive> 
        <a:TerminationPCode>1248900</a:TerminationPCode> 
        <a:TransactionType>13</a:TransactionType> 
    </aTransaction> 
</CalcTaxesWithPCode> 

Single Sales and Use Transaction Tax Calculation

<SAUCalcTaxesWithPCode xmlns="http://tempuri.org/"> 
    <aTransaction xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
        <a:AdjustmentMethod>0</a:AdjustmentMethod> 
        <a:Charge>123.45</a:Charge> 
        <a:Commit>false</a:Commit> 
        <a:CompanyIdentifier>XYZ</a:CompanyIdentifier> 
        <a:CountyExempt>false</a:CountyExempt> 
        <a:CountyPCode>0</a:CountyPCode> 
        <a:CustomerNumber>Test123</a:CustomerNumber> 
        <a:CustomerType>1</a:CustomerType> 
        <a:Date>2017-04-04T00:00:00-05:00</a:Date> 
        <a:DocumentCode>98c45e1b-2e95-42eb-81c0-0bc3ad6bc1dc</a:DocumentCode> 
        <a:ExemptionType>0</a:ExemptionType> 
        <a:FOB>1</a:FOB> 
        <a:FederalExempt>false</a:FederalExempt> 
        <a:FederalPCode>0</a:FederalPCode> 
        <a:Incorporated>true</a:Incorporated> 
        <a:InvoiceNumber>98765</a:InvoiceNumber> 
        <a:LocalExempt>false</a:LocalExempt> 
        <a:LocalPCode>0</a:LocalPCode> 
        <a:Sale>true</a:Sale> 
        <a:SaleAttributes i:type="a:DefaultAttributes"/> 
        <a:ServiceType>106</a:ServiceType> 
        <a:ShipFromPCode>443800</a:ShipFromPCode> 
        <a:ShipToPCode>442200</a:ShipToPCode> 
        <a:StateExempt>false</a:StateExempt> 
        <a:StatePCode>0</a:StatePCode> 
        <a:TaxInclusive>false</a:TaxInclusive> 
        <a:TransactionType>29</a:TransactionType> 
    </aTransaction> 
    <aNexusList i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/> 
    <anExclusionList i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/> 
</SAUCalcTaxesWithPCode> 

Invoice Mode ProcessCustomerBatch API Sample

<ProcessCustomerBatch xmlns="http://tempuri.org/">
    <custBatchId>62291</custBatchId>
    <returnDetail>true</returnDetail>
    <nexus i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
    <exclusions i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
    <documentCode>24c13f4f-4584-4b87-8e97-2ac243a912dc</documentCode>
    <commit>false</commit>
</ProcessCustomerBatch>

Invoice Mode CalcTaxesInCustMode Sample

<CalcTaxesInCustMode xmlns="http://tempuri.org/">
    <transactions xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Transaction>
            <a:AdjustmentMethod>0</a:AdjustmentMethod>
            <a:BillToPCode>442200</a:BillToPCode>
            <a:BusinessClass>1</a:BusinessClass>
            <a:CategoryExemptions i:nil="true"/>
            <a:Charge>123.45</a:Charge>
            <a:CompanyIdentifier>XYZ</a:CompanyIdentifier>
            <a:CountyExempt>false</a:CountyExempt>
            <a:CountyPCode>0</a:CountyPCode>
            <a:CustomerNumber>Test123</a:CustomerNumber>
            <a:CustomerType>1</a:CustomerType>
            <a:Date>2017-04-04T00:00:00-05:00</a:Date>
            <a:Debit>false</a:Debit>
            <a:DiscountType>3</a:DiscountType>
            <a:Exclusions i:nil="true"/>
            <a:ExemptionType>3</a:ExemptionType>
            <a:Exemptions i:nil="true"/>
            <a:FacilitiesBased>true</a:FacilitiesBased>
            <a:FederalExempt>false</a:FederalExempt>
            <a:FederalPCode>0</a:FederalPCode>
            <a:Franchise>true</a:Franchise>
            <a:Incorporated>true</a:Incorporated>
            <a:InvoiceNumber>98765</a:InvoiceNumber>
            <a:IsPrivateLine>false</a:IsPrivateLine>
            <a:Lifeline>true</a:Lifeline>
            <a:Lines>5</a:Lines>
            <a:LocalExempt>false</a:LocalExempt>
            <a:LocalPCode>0</a:LocalPCode>
            <a:Locations>3</a:Locations>
            <a:Minutes>115.55</a:Minutes>
            <a:OriginationPCode>443800</a:OriginationPCode>
            <a:PrivateLineSplit>0</a:PrivateLineSplit>
            <a:Regulated>true</a:Regulated>
            <a:SafeHarborOverrides i:nil="true"/>
            <a:Sale>true</a:Sale>
            <a:ServiceClass>1</a:ServiceClass>
            <a:ServiceLevelNumber>3456</a:ServiceLevelNumber>
            <a:ServiceType>6</a:ServiceType>
            <a:StateExempt>false</a:StateExempt>
            <a:StatePCode>0</a:StatePCode>
            <a:TaxInclusive>false</a:TaxInclusive>
            <a:TerminationPCode>1248900</a:TerminationPCode>
            <a:TransactionType>13</a:TransactionType>
        </a:Transaction>
    </transactions>
    <adjustments i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
    <sauTransactions i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
    <sauAdjustments i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
    <nexus i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
    <exclusions i:nil="true" xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
    <returnDetail>true</returnDetail>
    <documentCode>3fe09d2d-a226-4fa1-a733-981e691c70fc</documentCode>
    <commit>true</commit>
</CalcTaxesInCustMode>

CommitTransactions API Sample

<CommitTransactions xmlns="http://tempuri.org/">
    <commitData xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Committed>true</a:Committed>
        <a:DocumentCode>d816c744-e77d-413b-bcf0-71d35fc239d8</a:DocumentCode>
    </commitData>
</CommitTransactions>

CommitTransactions API Sample with Optional Fields

<CommitTransactions xmlns="http://tempuri.org/">
    <commitData xmlns:a="http://schemas.datacontract.org/2004/07/EZTaxWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Committed>true</a:Committed>
        <a:CustomerNumber>Cust12345</a:CustomerNumber>
        <a:DocumentCode>d816c744-e77d-413b-bcf0-71d35fc239d8</a:DocumentCode>
        <a:InvoiceNumber>12345</a:InvoiceNumber>
        <a:Optional>2</a:Optional>
        <a:Optional10>10</a:Optional10>
        <a:Optional4>4</a:Optional4>
        <a:Optional5>5</a:Optional5>
        <a:Optional6>6</a:Optional6>
        <a:Optional7>7</a:Optional7>
        <a:Optional8>8</a:Optional8>
        <a:Optional9>9</a:Optional9>
        <a:OptionalAlpha1>OptAlpha1</a:OptionalAlpha1>
        <a:OptionalFields>
            <a:OptionalField>
                <a:OptionalKeyNo>1</a:OptionalKeyNo>
                <a:OptionalValue>1</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>2</a:OptionalKeyNo>
                <a:OptionalValue>2</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>3</a:OptionalKeyNo>
                <a:OptionalValue>3</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>4</a:OptionalKeyNo>
                <a:OptionalValue>4</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>5</a:OptionalKeyNo>
                <a:OptionalValue>5</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>6</a:OptionalKeyNo>
                <a:OptionalValue>6</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>7</a:OptionalKeyNo>
                <a:OptionalValue>7</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>8</a:OptionalKeyNo>
                <a:OptionalValue>8</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>9</a:OptionalKeyNo>
                <a:OptionalValue>9</a:OptionalValue>
            </a:OptionalField>
            <a:OptionalField>
                <a:OptionalKeyNo>10</a:OptionalKeyNo>
                <a:OptionalValue>10</a:OptionalValue>
            </a:OptionalField>
        </a:OptionalFields>
    </commitData>
</CommitTransactions>

Frequently Asked Questions

  1. What happens if I commit an already committed document code? What happens if I uncommit an already uncommitted document code?
    • You may send the commit/uncommit request again without any adverse consequences.

      If the document code to commit/uncommit is already committed/uncommitted, no action will be taken and no error will occur. Response will have 200 code.

  2. What happens if I commit/uncommit using an invalid document code?
    • If the document code does not exist, the error No transactions found for document code will be returned. Response will have 404 code (REST) or 500 (SOAP).
  3. What happens if I commit/uncommit a document code that has been locked?
    • If the document code is locked, the error Document code has been locked will be returned. Response will have 404 code (REST) or 500 (SOAP).
  4. What happens to uncommitted document codes? Can I commit a document code from a previous billing period?
    • The document code and associated tax data is retained for up to 3 months. During this time, you can add new transactions, commit, and uncommit the document code. The handling is no different than the handling for a document code created in the current billing cycle.
  5. What determines which billing period the committed transactions will be reported in?
    • The date the document code is committed determines the billing period the committed transactions will be reported in. The original submission date and invoice date are not used, only when the transactions were committed. This allows a client to determine the billing period based upon business needs after the calculation was made instead of requiring it to be set prior to the tax calculation.

      The billing period by default is from the 1st of the month to the end of the month. This date can be configured by account to a different day by submitting the request via a support case.

  6. I need to add new transactions to a committed document, how do I do this?
    • Submit the transactions with the same document code and Commit=true.

      There is not currently an API method available to directly confirm the document status of a transaction. To verify if a document code is committed, the preferred approach is:

      1. Uncommit the document code

      2. Submit the new transaction(s) with the document code in the transaction data

      3. Commit the document code when the transaction details have been finalized.

  7. Do I need to set the Company Identifier to the 3 byte code for the account for transactions I assign a document code to?
    • Usage of the Company Identifier to establish which records should be included in the compliance reporting and usage of the Commit/Uncommit process are mutually exclusive. If a record has been assigned a document code and is committed, it will be included in the compliance reports regardless of the value in the Company Identifier field.
  8. Can I re-use document codes? Can I change the document code used to group transactions?
    • The document code must be unique for each grouping of transactions and cannot be changed once used. You cannot re-use document codes. It is up to the client to determine the approach for creating a unique document code that best suits their business needs.
  9. Can we switch from using Company Identifier to using Commit in the middle of a billing cycle?
    • Yes, the two approaches are mutually exclusive but can co-exist.

      Clients switching over will need to factor in that committed transactions use only the date the transaction was committed to determine which billing period the transactions will be reported in. The Company Identifier, Invoice Date, Submitted Date and Optional10 field will be not be used for reporting consideration with transactions that use Commit.

  10. What happens if I send a CalcTaxes API call with cmmt = false using a document code that is already committed? What happens if I send a CalcTaxes API call with cmmt = true using a document code that is uncommitted?

    • The document will remain unchanged. To change the document status after the initial CalcTaxes API call for the DocumenCode, you must use the CommitTax API method.

  • Was this article helpful?