AvaTax allows you to override calculated tax by specifying a tax override at either the document level or line level of a transaction.

The following types of override objects are supported: taxAmount, taxDate, and taxAmountByTaxTypes. Each of these is described later in this topic.

The taxAmount override will do just that, override the tax amount on the transaction. This is helpful if you need to record transactions to AvaTax that had the tax calculated in another system.

The taxDate override allows you to specify what tax date to use in the calculation. By default, AvaTax uses the document date as the taxDate. The common use case for this override is processing refunds - you want to calculate the refund tax credit using the same information that the original sale used.

The taxAmountByTaxTypes is used with customs duty and import tax and is only available on the line level. This override allows you to specify a total override of the calculated tax on the line with a specific tax type. AvaTax distributes the override across all the line details for that tax type.

When performing a tax override, AvaTax expects you to specify one of the following tax types:

None: Indicates that AvaTax calculated tax for this transaction, and no override occurred.

TaxAmount: Indicates that AvaTax calculated tax for this transaction, but the final tax amount on the transaction was determined outside of AvaTax. To see the amounts determined by AvaTax, review the taxCalculated field in the response; to see the amounts determined by the customer's outside tax engine, review the taxAmount field. This behavior can also occur when a customer requests a refund. For refunds calculated using the RefundTransaction API, AvaTax ensures that the exact tax charged to the customer is refunded to the customer using a tax amount override.

Exemption: Indicates that the entity exemption was ignored.

TaxDate: Indicates that AvaTax calculated tax on this transaction using the tax rules in effect on a date other than when the transaction occurred. This behavior typically occurs during refunds. If the customer attempts to return a product without a receipt that shows the exact amount paid, AvaTax can calculate tax on the date when they believed the product was purchased.

AccruedTaxAmount: An override used in Consumer Use Tax transactions.

DeriveTaxable: AvaTax derives the taxable amount from the tax amount.

OutOfHarbor: Indicates transaction data where the tax was determined by a system other than AvaTax and then passed into AvaTax.

TaxAmountByTaxType: Used to override a specify tax amount for a specific tax type.

VendorChargedTax: Overrides tax calculated by a vendor in Consumer Use Tax transactions.

Overriding the tax amount

A taxAmount override overrides the tax amount of a transaction rather than using the AvaTax calculated value. This feature is available so that you can import transactions where you’ve already calculated the tax amount before using AvaTax. An example would be importing data from an older system so that you can keep all of your data in AvaTax. Other customers may choose to use this feature to import data from partner sales - for example, if you were selling via a merchant platform and you wanted to import your data into AvaTax.

Example

Overriding the tax date

A TaxDate override is used when you want to calculate tax on a date different than the date of a document. For example, when you return a product, the tax date of the transaction would be the date of the original transaction rather than the date of the refund.

Let’s say Alice purchases a new chair from a store on May 1. She discovers that the chair doesn’t fit in her home office, and she decides to return the chair on June 1. If you calculate tax on the June 1 date, you might refund a different amount of tax to Alice than she paid on May 1. So, you use a TaxDate override to ensure that the tax rates are calculated as of May 1.

Example

Overriding the tax amount for a tax type

Typically used for cross-border and transactions outside of sales, use, or value-added tax transactions, the taxAmountByTaxTypes override allows you to specify the total tax amount to override per tax type applicable at the line level in the request.

taxAmountByTaxTypes workflow

Follow the workflow below to use the taxAmountByTaxTypes override.

taxAmountByTaxTypes fields

Field	Attribute	Description
`taxTypeId`	string	The name of the tax type, as retrieved from the quote response
`taxAmount`	number($double)	The amount of tax to override

taxAmountByTaxTypes example

Sales order request

Sales order response

Sales invoice example

Override a transaction