In order to calculate VAT for more complex scenarios, it is necessary for the engine to receive additional data input. These additional input fields are passed as part of the and CreateTransaction and CreateNexus requests.
After passing these input fields, the Avalara tax engine then determines the following key questions in calculating VAT:
The sections below describes the additional data fields added in AvaTax to support new VAT enhancements. These fields provide the engine with the data it needs to properly match the article for each piece of the VAT calculation — Place of Supply, Liability to Pay, and any Exemptions.
Before describing the transaction input fields for VAT calculations, it is important to understand how to create transactions in AvaTax and the different elements that you can include in your API request. This information is documented in the AvaTax Developer Guide, but in simple terms, a transaction consists of:
More information is available in the CreateTransaction API.
Advice: The Address model and the Parameters model can be included at the document level or within the line level. For most cases, AvaTax expects to see parameters at the document level so that they apply to the entire transaction.
The following fields can be used in the CreateTransaction API for transactions that will calculate VAT.
This field specifies the name of the customer who is purchasing the goods or service and is used in the Marketplace Audit Report available in AvaTax Reports. This report is required to include this data for auditing purposes. This field is also used in VAT Returns.
This field is specified at the document level.
Type | Document Type | Required? |
A string that identifies the name of the customer who is purchasing the goods or services. |
| No |
A company can have multiple locations. The reportingLocationCode
represents the location code you created when you set up a location and specifies the location that the merchant uses for the sale of their goods on a marketplace. This is different than the companyCode
, which is the company that this location is a part of.
Including a
reportingLocationCode
on transactions allows you to create location-specific reports and filter by location code on the Transactions page. For Avalara clients that are configured as marketplace merchants, this field is required for deemed supplier use cases.
This field is specified at the document level of a transaction.
Type | Document Type | Required |
A string that specifies the location code of the marketplace on which the merchant sells products. |
| Yes for deemed supplier use cases when the Avalara client is a merchant selling on a marketplace |
For EU transactions, the bu
sinessIdentificationNo
is a separate identifier that relates to the counterparty's VAT registration number in a transaction. This can be specified at either the document level or the line level. When specified at the document level, this number will be used for all lines in the transaction.
If you specify a VAT business identification number for the customer in a transaction and you have also set up a business identification number for your company during company setup, the transaction will be treated as a business-to-business transaction for VAT purposes, and it will be calculated according to VAT tax rules.
Consider the following when using this field:
SalesOrder
or SalesInvoice
, this is the final customer's VAT number. It is only relevant for B2B transactions. When populated, it must include the VAT country two-digit ISO code prefix (e.g. “DE123456789"). This can be an empty string or omitted entirely for B2C transactions.PurchaseOrder
or PurchaseInvoice
, this is the vendor’s VAT number.Type | Document Type | Required? |
A string containing the full VAT ID (including the country ISO prefix) of the customer or vendor for this transaction, for example, "ATU12345678" |
| No |
This specifies the identification of the merchant/seller on the marketplace. For Avalara clients that are configured as marketplaces, this field is required for deemed supplier use cases and is specified in the transaction's LineItemModel.
Type | Document Type | Required? |
A string specifying the identifier your platform uses to identify the merchant selling through your platform. |
| Yes for deemed supplier use cases |
If the goods being sold in a VAT transaction are second hand (used), this flag should be set to true
. AvaTax assumes all goods are new by default unless this value is set. AvaTax will also calculate VAT on second-hand goods. This value is specified in the transaction's LineItemModel.
Options | Document Type | Required? |
|
| No |
This parameter indicates who in the VAT transaction is responsible for handling the transportation of the physical goods. This parameter is required for EU transactions and for certain marketplace transactions and must be submitted on all physical goods transactions. It is not required for services transactions. Transport
can be specified in the TransactionParameterModel or the TransactionLineParameterModel.
Options | Document Type | Required? |
|
| Yes for physical goods, including for some deemed supplier use cases.No for services transactions. |
Triangulation occurs when there are three companies involved in a single supply of goods, and they are all in three different EU countries. For example, a French company with a French VAT registration sells some goods to a German customer, but the French company first has to buy the goods from a Spanish supplier prior to shipment directly to the Germany customer. This would require the French company to VAT register itself in Spain for Spanish VAT to record the purchase and onward dispatch (sale) to the Germany customer. (The French company could also register for Germany VAT to do the same.)
To avoid creating a need for many companies to register like this, Triangulation Simplification exemption was created within the EU VAT law, which is implemented across all member states so that the French company does not have to register for VAT in Spain.
This flag must be enabled if the transaction is part of a triangulation simplification scenario. It can be specified in the TransactionParameterModel or the TransactionLineParameterModel.
Options | Document Type | Required? |
|
| Optional for the following use cases
Required for other triangulation scenarios |
The PartyCVATIDCountry
parameter is used in triangulation transactions to verify that Party C has provided a VAT ID for the country the goods are shipped to. When configuring this parameter, specify the country's 2-digit country ISO code.
Type | Document Type | Required? |
A string the country ISO prefix for the country where goods are shipped to. |
| Required for use case, "Purchase Party B from Party A" only if IsTriangulation is not passed. |
The PartyAVATIDCountry
parameter is used in triangulation transactions to verify that Party A has provided a VAT ID for the country the goods originated from. When configuring this parameter, specify the country's 2-digit country ISO code.
Type | Document Type | Required? |
A string the country ISO prefix for the country where goods originated from. |
| Required for use case, "Sale Party B to Party C" only if IsTriangulation is not passed. |
Delivery Terms (or Incoterms) refer to agreed-upon conditions between a buyer and a seller for the delivery or goods. They are three-letter trade terms describing the practical arrangements for the delivery of goods from sellers to buyers and set out the obligations, costs and risks between the two parties.
The DeliveryTerms
parameter is used to determine who acts as Importer of Record and who arranges the transport of the goods if this information is not separately sent to AvaTax in the request. Further, the DeliveryTerms
is also used in conjunction with Importer of Record to influence whether AvaTax includes Import Duty and Tax in the transaction totals.
If the fields for Transport
or isSellerImporterOfRecord
are passed in the request and conflict with the Delivery Term, the values provided in the first will take priority over the Delivery Term field. If Transport
or isSellerImporterOfRecord
are not passed in the request and Delivery Term is passed, AvaTax will determine who acts as Importer of Record and who arranges the Transport of the goods based on the Delivery Term provided. If none of these fields is passed, AvaTax will keep the current behavior and default Transport to “Seller” for goods and Importer of Record to “False” (i.e., the AvaTax user does not act as Importer of record).
DeliveryTerms
can be specified in the TransactionParameterModel or the TransactionLineParameterModel.
The table below describes the available delivery terms. Of these options, DAP
and DDP
indicate that Import Duty and Tax should be included in the transaction total.
Options | Document Type | Required? |
|
| Yes |
This parameter is required if the transaction is part of a triangulation simplification scenario because AvaTax needs to know the VAT ID of the middleman. When providing the MiddlemanVatId
, you must include the complete VAT ID, starting with the two-digit country ISO prefix.
This parameter can be specified in the TransactionParameterModel or the TransactionLineParameterModel.
Type | Document Type | Required? |
A string containing the full VAT ID (including the country ISO prefix) of the middleman, for example, "ATU12345678" |
| Yes for triangulation simplification scenarios |
This parameter specifies the country where the merchant is established (has a physical address).
For EU transactions, if a seller is not established or is not in the EU, then this is used to determine whether the marketplace is considered the deemed supplier.
For Avalara clients that are configured as marketplaces, this parameter is required for Deemed Supplier use cases and can be specified in the TransactionLineParameterModel.
Options | Document Type | Required? |
Specify the two-character ISO code that identifies the country where the merchant is established. |
| Yes, for deemed supplier use cases |
This parameter specifies the name of the merchant selling the item and is used in the Marketplace Audit Report available in AvaTax Reports. This report is required to include this data for auditing purposes.
This parameter can be specified in the TransactionLineParameterModel.
Type | Document Type | Required? |
A string that identifies the merchant selling the item. |
| No |
This parameter specifies the VAT ID of the Merchant selling the item and is used in the Marketplace Audit Report available in AvaTax Reports. This report is required to include this data for auditing purposes.
This parameter can be specified in the TransactionLineParameterModel.
Type | Document Type | Required? |
A string that identifies the VAT ID of the merchant selling the item. |
| No |
This parameter indicates whether the customer in the sales transaction is registered through a fiscal representative in a given country calculating VAT. This field defaults to false
. It can be specified in the TransactionParameterModel or the TransactionLineParameterModel.
This information is also available in the Supplier/Customer table.
Options | Document Type | Required? |
|
| No |
This parameter allows users to specify the method by which goods are transported from one country to another. This field defaults to a blank string.
This field is required for Malaysia transactions. For VAT calculations in Malaysia, the low goods GST threshold will get applied to transactions that are transported via air
.
Options | Document Type | Required? |
|
| Required for Malaysia transactions in order to determine the deminimis threshold. For transactions of goods shipped into Malaysia, only the |
Nexus refers to a connection between a business and a taxing jurisdiction that creates a legal requirement for the business to register and remit taxes within the jurisdiction. In AvaTax, Nexus is a setting you configure to identify jurisdictions where you're registered to collect and remit tax.
The following parameters were added to the CreateNexus API. Though these values are configured in Nexus, they can be overridden in a transaction request.
Some of the EU countries have individual options that allow VAT to be deferred until the return is filed. For the Avalara client, this field identifies whether the Nexus VAT country applies for an Import VAT Deferment scheme. The customer sets this value in the Country Nexus as part of their configuration. This value defaults to false
and can be overridden in the transaction request.
Options | Required? |
| No |
This flag indicates whether the seller (Avalara client) is registered through a fiscal representative in the given Nexus country for VAT. Fiscal representatives manage the seller's VAT obligations in a particular country and act on the seller's behalf.
This value defaults to false
and can be overridden in the transaction request.
Options | Required? |
| No |