Addresses in AvaTax transactions

Addresses are a crucial part of the sales tax calculation process. There are various factors that go into the sales tax calculation, but addresses are probably the most important. You pay a total sales tax rate. This rate consists of several smaller rates, and each one goes to a different tax jurisdiction, such as a state, a county, or a city.

AvaTax determines the correct tax jurisdictions based on the provided addresses. This seems straightforward. However, many tax jurisdictions exist, and their boundaries are complex. Avalara's content research team identifies the correct tax jurisdictions for you. Simply provide the address, and AvaTax will handle the rest.

Supported address types

The table in this section describes the address types supported in AvaTax.

The simplest type of transaction is a retail point-of-sale transaction, where the origin address and the destination address are the same. This type of transaction uses the address type singleLocation. For example, in this scenario, a customer makes a purchase in a retail location and takes possession of the product at that location.

For transactions where the origin and destination addresses aren’t the same, the two address types that factor into sales tax calculation are origin addresses and destination addresses. For example, if you live in Washington and you’re selling a mug to someone in California, your origin address (of type shipFrom) would be Washington and your destination address (of type shipTo) would be California.

While only the city, state, and postal code are required for calculation, it’s best practice to provide as much address information as you have available. This will help to ensure the most accurate tax calculation possible.

You can specify addresses at either the document level or the line level.

Document level: A transaction, as a whole, uses document-level addresses as the default. If a transaction doesn't have any addresses at the line level, each line will be assumed to use the addresses from the document level. When you record a single transaction, and all invoice lines on the transaction have the same addresses, you only need to set your address values once at the root level of your transaction, no matter how many invoice lines you’re calculating.
Line level: Line-level addresses represent individual, separate shipments. It's possible to have a scenario where an end customer checks out of the cart with the products/services from different merchants. In this case, the shipFrom address differs for some or all lines. The shipTo address is likely to always remain the same for a given checkout process, but in this case, pass them together at line level.

Note Don't create transactions that include both document-level and line-level addresses. For example, if your transaction includes multiple lines, and those lines include line-level addresses, then all lines should include line-level addresses.


Field Name	Model	Summary
`singleLocation`	AddressLocationInfo	If a transaction occurred at a retail point-of-sale location, provide that single address here and leave all other address types null.
`shipFrom`	AddressLocationInfo	The origination address where the products were shipped from or from where the services originated.
`shipTo`	AddressLocationInfo	The destination address where the products were shipped to or where the services were delivered.
`pointOfOrderAcceptance`	AddressLocationInfo	The location where the order was accepted by your supplier, such as a call center, business office where purchase orders are accepted, and server locations where orders are processed and accepted. AvaTax uses this address to determine the establishment country of your supplier in the transaction. Include this address in Purchase document types.
`pointOfOrderOrigin`	AddressLocationInfo	The location from where your customer (home or business) placed the order to you. This is used to determine the establishment country of your customer. Include this address in Sales document types.

Specifying latitude and longitude in addresses

In some cases, a location or service site can only be pinpointed by geolocation. For these situations, AvaTax supports specifying a latitude and longitude when configuring any of the above address types. If a user provides these along with a line, city, region, country, and postal code, AvaTax will use only the latitude and longitude and will discard the line, city, region, country, and postal code information for the transaction.

Ensure that you have the correct latitude/longitude information for an address before using the AddressLocationInfo API. If you provide either a latitude or longitude but not both, AvaTax uses the line, city, region, country, and postal code for the addresses.

Tip You can only specify latitude and longitude for US addresses.

Resolving addresses

Validate and resolve addresses using an address validation system. If you use Avalara's address validation system, call the ResolveAddress API. Avalara's address validation service is available only for US and Canadian addresses.

When you call this API, Avalara returns a response indicating whether the address can be found or if any errors or typos are detected. This helps users when entering an address. Follow these steps:

When the user enters data into an address field, call ResolveAddress with the provided information.
If the ResolveAddress function reports that ResolutionQuality is External or NotCoded, this indicates that AvaTax can't identify the address the user typed in. Return a warning to your user and ask them to verify the address.
If the user chooses to accept an incorrect address, it's possible to specify line1 = "GENERAL DELIVERY". This is a special code recognized by the USPS that allows nonrecognized addresses to be processed even if automated address validation doesn't identify the correct location. For more information, see the USPS website on General Delivery.