Avalara Developer Network Developer blog

Adjusting Transactions

Now that you’re using AvaTax, your software creates transactions with ease. What happens when a customer reports that they want to make a change? Most accounting systems allow you to adjust invoices or modify transactions in some fashion. Let’s review how AvaTax provides support for these scenarios.

Refresher

For previously recorded transactions with a status of committed in AvaTax; the service identifies the transaction in AvaTax is committed and does not permit the transaction to be overwritten. If your transaction is committed but not locked, you can call VoidTransaction - that means you caught it before it was reported on a tax return. The transaction will be canceled and you can create a new one with the corrected information.

However, if your transaction was locked and reported on a return, we can still help you. If you use Avalara’s Managed Returns service, we can provide help amending your returns. An amended return allows you to notify the state and correct any discrepancies. Reach out to your account manager today and we’ll be happy to help you with any tax reporting challenges!

Isn't there another way?

So after reading the refresher above; you may still ask, isn’t there another way I can still Adjust a previously recorded and committed transaction? The short answer is yes, however, there are some key issues you need to be aware of. First, the refresher section above outlines the recommended approach for the best audit trail and accounting visibility related to changing a recorded and committed invoice in a financial system. Second, many Avalara customers use Avalara’s filing service or will plan to use in the future; and for anyone using this service, after the 10th of each month, the previous month’s transactions are marked “locked”. Locked transactions cannot be Adjusted using the API.

Common User Story for needing to Adjust a Transaction

I have processed my daily invoice run from my financial / order management system, printed my invoices and am reviewing the invoices. I spot that one of the invoices has an item which we no longer stock and I will not be able to fulfill; and on another invoice, the customer had called me after the invoice run and wants to change the order quantity. My application has in the past always let me edit an invoice before I send it to my customer. This has the benefit of keeping my invoice numbers sequential and keep the customer’s notification email invoice number in sync with what I have communicated to my customer. I want this same behavior when I am using AvaTax.

Adjusting a Transaction

Using the AdjustTransction method; AvaTax will create a revised document using the same “code”, which means from an audit trail perspective; AvaTax keeps track of all previously recorded transactions with the same code. The last Adjusted transaction will be marked with a “committed” status, previously committed transactions will be marked “adjusted”. Let’s review an example:

First, we will call CreateTransaction, for a quantity of 10 with an extended price of 1000)

{
    "code": "INV1001",
    "companyCode": "DEFAULT",
    "type": "SalesInvoice",
    "commit": "true",
    "customerCode": "TOI",
    "date": "2017-10-09",
    "lines": [{
        "number": "Line 1",
        "quantity": 10,
        "amount": 1000,
        "taxCode": "PC040100",
        "description": "Baseball Cap",
        "addresses": {
            "ShipFrom": {
                "line1": "2790 NE Strand Rd",
                "city": "Bremerton",
                "region": "WA",
                "country": "US",
                "postalCode": "98311"
            },
            "ShipTo": {
                "line1": "26772 Calle Maria",
                "city": "Capistrano Beach",
                "region": "CA",
                "country": "US",
                "postalCode": "92624"
            }
        }
    }]
}

Next, we’ll call AdjustTransaction to change the invoice from a quantity of 10 to 9 and an extended price of 1000 to 900:

{
    "adjustmentReason": "Other",
    "adjustmentDescription": "Quantity change",
    "newTransaction": {
        "code": "INV1001",
        "companyCode": "DEFAULT",
        "type": "SalesInvoice",
        "commit": "true",
        "customerCode": "TOI",
        "date": "2017-10-09",
        "lines": [{
            "number": "Line 1",
            "quantity": 9,
            "amount": 900,
            "taxCode": "PC040100",
            "description": "Baseball Cap",
            "addresses": {
                "ShipFrom": {
                    "line1": "2790 NE Strand Rd",
                    "city": "Bremerton",
                    "region": "WA",
                    "country": "US",
                    "postalCode": "98311"
                },
                "ShipTo": {
                    "line1": "26772 Calle Maria",
                    "city": "Capistrano Beach",
                    "region": "CA",
                    "country": "US",
                    "postalCode": "92624"
                }
            }
        }]
    }
}

You’ll now see that the transaction contains the updated amounts. Your resulting transaction will show an adjusted amount of $900 and quantity of 9.

Handling Errors

There are a few types of errors to look for when calling the Adjust API:

  • Did you remember to put the updated transaction request in the NewTransaction element? If not, you will get the error ValueRequiredError.
  • The adjustment reason field is required; if you omit it, you will get an error of type GetTaxError indicating that the reason field must not be empty.
  • If you had been using Avalara's Managed Returns Service, and the original transaction had been filed on a tax return, you would have received an error indicating that the document is locked and cannot be adjusted.

End result: Your transaction is revised and updated!

Another Alternative

If you expect to modify transactions regularly, you may choose to use the CreateOrAdjustTransaction API. This method follows a slightly different bit of logic:

  • When you provide your transaction to the API, it checks to see if that transaction already exists.
  • If the transaction already exists, it calls AdjustTransaction.
  • If the transaction does not exist, it calls CreateTransaction.

Using CreateOrAdjustTransaction allows you to call the API for a specified document code without checking in advance if the transaction has yet been recorded in AvaTax. This makes it a great option to sync up your accounting system or sales pipeline with your tax data.

-Mark Withers Partner Launch Team

Back to posts