Avalara Developer Network Developer avaTax

4.2 - Modifying a Transaction

During the reconciliation process, if you discover that a transaction is not correct, you can fix the transaction in one of three ways: you can Adjust, Void, or Refund the transaction.

Adjust

To keep a transaction intact, but make a change or correction, you would adjust the transaction using the AdjustTransaction API. When you call the API, two things will happen:

  • The existing transaction will be marked as Adjusted, and
  • A new transaction will be created in the appropriate status (either Saved or Committed).

A commonly asked question about the Adjust API is “Why can’t I just change one field on the transaction object?” Unfortunately, tax laws often have complex interdependencies, and it is not guaranteed that a transaction would still be valid if only one field changes. Tax authorities occasionally create tax laws that affect the behavior of line items based on the presence of other line items in the same transaction, on the classification of items, on the quantity of items, or on threshold values. As a result, the AdjustTransaction API call will re-create your transaction completely in order to ensure that it meets the AvaTax standard of accuracy.

If you need to make a small change to your transaction, you may choose to reconstruct the original data you submitted to the CreateTransaction API call using the AuditTransaction API. This API allows you to rebuild the CreateTransactionModel data structure that you used when you originally created the object. You can then make a small change to the transaction and submit it to the AdjustTransaction API.

If you are looking to make a small change to an existing transaction, you can consider calling AddLines or DeleteLines. These methods will allow you to add lines to an existing transaction or remove lines from an existing transaction. Internally, these API calls use the same method as AdjustTransaction and they will still behave the same as if you called AdjustTransaction directly.

Here’s how you can modify a transaction to correct an error:

Test Case - 4.2.1

Setup

  • In your connector, create the following transaction:
    • Document Type: SalesInvoice
    • Document Code: Chapter-4-Test-3
    • Company Code: DEVGUIDE
    • Document Date: 2017-06-15
    • Customer Code: TESTCUSTOMER
    • Addresses:
      • SingleLocation
      • 100000000000000 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 AdjustTransaction with all information the same, except using the corrected address:
    • line1: 100 Ravine Lane NE, Bainbridge Island, WA, 98110

Assertions

  • Two transactions exist:
    • Chapter-4-Test-3
      • status: Adjusted
      • line1: 100000000000000 Ravine Lane NE
    • Chapter-4-Test-3
      • status: Committed
      • line1: 100 Ravine Lane NE
      • "adjustmentReason": "Other"
      • "adjustmentDescription": "Correct shipping address"
  • CreateTransaction:
    {
      "type": "SalesInvoice",
      "code": "Chapter-4-Test-3",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "commit": "true",
      "addresses": {
        "singleLocation": {
          "line1": "100000000000000 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }
                    
  • AdjustTransaction:
    {
      "adjustmentReason": "Other",
      "adjustmentDescription": "Correct shipping address",
      "newTransaction": {
        "type": "SalesInvoice",
        "code": "Chapter-4-Test-3",
        "companyCode": "DEVGUIDE",
        "date": "2017-06-15",
        "customerCode": "TESTCUSTOMER",
        "commit": "true",
        "addresses": {
          "singleLocation": {
            "line1": "100 Ravine Lane NE",
            "city": "Bainbridge Island",
            "region": "WA",
            "country": "US",
            "postalCode": "98110"
          }
        },
        "lines": [
          {
            "number": "1",
            "amount": 100,
            "taxCode": "P0000000"
          }
        ]
      }
    }
                    

Note that transactions that are locked cannot be adjusted.

Void

To remove a transaction that is not valid, you use the VoidTransaction API. When you call this API, the transaction will be moved to the status Cancelled. Transactions in the Cancelled status will no longer be used for reporting purposes and will not be included in reports unless specifically requested.

To void a transaction, you must provide a reason code. The reasons available are:

  • Unspecified
  • PostFailed
  • DocDeleted
  • DocVoided
  • AdjustmentCancelled

These codes are available for you to use to help distinguish between a variety of different types of reasons for voiding a transaction, but they do not have different behavior within AvaTax. You are free to use whichever reason code is appropriate for your task.

Here’s how to void a transaction:

Test Case - 4.2.2

Setup

  • In your connector, create the following transaction:
    • Transaction Type: SalesInvoice
    • Transaction Code: Chapter-4-Test-4
    • 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 VoidTransaction with the following reason:
    • code: DocVoided

Assertions

  • One transaction exist:
    • Chapter-4-Test-4
      • status: Cancelled
      • Amount: 100
  • CreateTransaction:
    {
      "type": "SalesInvoice",
      "code": "Chapter-4-Test-4",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "commit": "true",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }
                    
  • VoidTransaction:
    {
      "code": "DocVoided"
    }
                    

Note that transactions that are locked cannot be voided.

Refund

A transaction refund is sometimes called a return or a reverse charge invoice. To match commonly used language, we have chosen to call this the RefundTransaction API.

When you refund a transaction, you are what you are technically doing is creating a ReturnInvoice with values that are the negative. These negative values indicate that money is being returned from the seller to the purchaser. This corresponds to the accounting concept of a positive and negative journal entries that cancel each other out.

You can choose to use the RefundTransaction API in a few different ways:

  • You can refund the entire transaction by setting "refundType": "Full".
  • You can refund specific lines from a transaction by specifying "refundType": "Partial", and setting a list of lines to refund using the refundLines parameter to the list of line numbers of the lines that are being refunded.
  • If your customer originally paid sales tax on the transaction, and they later provided a resale exemption certificate, you can call set the "refundType": "TaxOnly".
  • If you wish to give a customer a percentage refund, perhaps for a discount, you can specify "refundType": "Percentage".

You should ensure that the refundDate value is set to the correct date for the refund. The tax rates that will be used are the correct rates from the previous transaction.

Here’s how to use RefundTransaction to return a customer’s money:

Test Case - 4.2.3

Setup

  • In your connector, create the following transaction:
    • Document Type: SalesInvoice
    • Document Code: Chapter-4-Test-5
    • 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 RefundTransaction with the following reason:
    • refundTransactionCode: Chapter-4-Test-5-Refund
    • refundType: Full
    • refundDate: 2017-06-22
    • referenceCode: Refund of Chapter-4-Test-5 - Returned after 7 days.

Assertions

  • One transaction exist:
    • Chapter-4-Test-5
      • status: Committed
      • Amount: 100
    • Chapter-4-Test-5-Refund
      • status: Committed
      • Amount: -100
  • CreateTransaction:
    {
      "type": "SalesInvoice",
      "code": "Chapter-4-Test-5",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "TESTCUSTOMER",
      "commit": "true",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }
                    
  • VoidTransaction:
    {
      "refundTransactionCode": "Chapter-4-Test-5-Refund",
      "refundType": "Full",
      "refundDate": "2017-06-22",
      "referenceCode": "Refund of Chapter-4-Test-5 - Returned after 7 days."
    }
                    

For customers using Avalara’s Managed Returns Service, it may not always be possible to report ReturnInvoice transactions on every tax filing. Avalara works with tax authorities around the world to ensure that we handle negative values correctly in each jurisdiction; some jurisdictions have requirements that must be met in order to correctly report a ReturnInvoice transaction. This means that a ReturnInvoice transaction may potentially be “carried-forward” from one filing to another until it meets the tax authority’s requirements for filing.

To list all ReturnInvoice transactions that have not yet been reported to a tax authority, please call the ListTransactionsByCompany API with the parameter $filter=type eq ReturnInvoice and status eq Committed. If a return invoice transaction has not been able to be reported for more than six months, we recommend contacting Avalara’s Compliance department to request an amended tax return which will allow the refund value to be claimed directly.