Input fields for VAT calculations

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:

What is the place of supply? In other words, in what country is the VAT obligation?
Which party has the liability to pay?
Are there any applicable exemptions?
For marketplace transactions, who is liable to collect, report, and remit the VAT due from the consumer?

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.

Understanding AvaTax transactions

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:

First-class elements that can be specified at the document level and apply to the entire transaction
Line item model that includes elements that apply to a line in a transaction.
An address model
A parameters model

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.

CreateTransaction input fields

The following fields can be used in the CreateTransaction API for transactions that will calculate VAT.

Document level fields

customerSupplierName

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.

reportingLocationCode

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.

businessIdentificationNo

For EU transactions, the businessIdentificationNo 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:

When the document type is 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.
When the document type is PurchaseOrder or PurchaseInvoice, this is the vendor’s VAT number.

Line item fields

merchantSellerIdentifier

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.

isGoodsSecondHand

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.

Parameter fields

Transport

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.

IsTriangulation

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.

Party C VAT ID country

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.

Party A VAT ID country

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.

Delivery terms

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.

MiddlemanVatId

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.

MerchantEstablishmentCountry

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.

MerchantName

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.

MerchantVatId

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.

IsCustomerRegisteredThroughFiscalRep

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.

ModeOfTransport

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.

CreateNexus data fields

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.

IsImportVatDeferment

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.

IsRegisteredThroughFiscalRep

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.

Type	Document Type	Required?
A string that identifies the name of the customer who is purchasing the goods or services.	Sales Order Sales Invoice Purchase Order Purchase Invoice	No

Type	Document Type	Required
A string that specifies the location code of the marketplace on which the merchant sells products.	Sales Order Sales Invoice Purchase Order Purchase Invoice	Yes for deemed supplier use cases when the Avalara client is a merchant selling on a marketplace

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"	Sales Order Sales Invoice Purchase Order Purchase Invoice	No

Type	Document Type	Required?
A string specifying the identifier your platform uses to identify the merchant selling through your platform.	Sales Order Sales Invoice Purchase Order Purchase Invoice	Yes for deemed supplier use cases

Options	Document Type	Required?
`true` `false` (default)	Sales Order Sales Invoice Purchase Order Purchase Invoice	No

Options	Document Type	Required?
`CFR`: Cost and Freight `CIF`: Cost, Insurance, and Freight `CIP`: Carrier and Insurance Paid to `CPT`: Carriage Paid To `DAP`: Delivered at Place `DDP`: Delivered Duty Paid `DPU`: Delivered at Place Unloaded `EXW`: Ex Works `FAS`: Free Alongside Ship `FCA`: Free Carrier `FOB`: Free on Board	Sales Order Sales Invoice Purchase Order Purchase Invoice	Yes