AvaTax Implementation Details

Some countries, like the United States or Canada, have very complex sales tax rules that are difficult to manage. JustOn allows for retrieving tax data from an external tax provider.

JustOn supports the AvaTax service from Avalara as external tax provider.

Info

Refer to the Avalara Help Center for information about error messages returned when retrieving taxes from AvaTax.

This page summarizes specific information about the AvaTax service integration. For details about the general tax data retrieval implementation, see Tax Data Retrieval: Implementation Details.

Country and State Codes

AvaTax requires country and state codes for address validation. To simplify the handling of address data, JustOn recommends to use the built-in Salesforce picklists for countries and states. For details, see Enable and Disable State and Country Picklists in the Salesforce Help.

Data Fields

The AvaTax tax provider uses the fields listed in the following sections.

Info

The AvaTax integration is designed to use the the existing fields if they exist. Only a small number of fields must be created if they are applicable to your use cases, including

ON_CustomerId and ON_TaxExemptReason on the Account object
ON_ItemCode and ON_VATIN on the Invoice Line Item object

Account

Field	AvaTax Model	AvaTax Name	AvaTax Description	Example
ON_CustomerId__c Optional, to be created Id Fallback	CreateTransactionModel	customerCode	Customer Code - The client application customer reference code. Note: This field is case sensitive. To have exemption certificates apply, this value should be the same as the one passed to create a customer.	`ABC`
ON_TaxExemptReason__c To be created	CreateTransactionModel	entityUseCode	Entity Use Code - The client application customer or usage type. Entity/Use Codes are definitions of the entity who is purchasing something, or the purpose for which the transaction is occurring. This information is generally used to determine taxability of the product.	`D`

Info

The ON_TaxExemptReason field marks a customer as fully or partially tax exempt and must contain the exempt code. The field can either be a fixed text field or a picklist.

If you use a picklist, specify the exempt codes as the picklist values. If necessary, provide the corresponding exempt descriptions using the Translation Workbench.

For details about the exempt codes, refer to Exemption Reason Matrices for US and Canada in the Avalara Help Center.

Business Entity

Field	AvaTax Model	AvaTax Name	AvaTax Description	Example
Street__c	AddressesModel	shipFrom.line1	First line of the street address	`123 Main Street`
City__c	AddressesModel	shipFrom.city	City component of the address	`Irvine`
StateCode__c	AddressesModel	shipFrom.region	State/Province/Region component of the address	`CA`
CountryCode__c	AddressesModel	shipFrom.country	Two-character ISO 3166 country code	`US`
PostalCode__c	AddressesModel	shipFrom.postalCode	Postal Code/Zip Code component of the address	`92615`

If the Code values of the address are not set, the following fields are used as fallback:

Field	Fallback Field
StateCode__c	State__c
CountryCode__c	Country__c

Invoice

Field	AvaTax Model	AvaTax Name	AvaTax Description	Example
Name	CreateTransactionModel	code	Transaction Code – the internal Reference Code
Account.Name	CreateTransactionModel	referenceCode	Can be used to reference the original document for a return invoice, or for any other reference purpose.
Class__c	CreateTransactionModel	type	Specifies the type of document to create. Determined automatically from the `Class__c` field.
Date__c	CreateTransactionModel	date	Transaction Date – The date on the invoice
CurrencyIsoCode or Company Default Currency	CreateTransactionModel	currencyCode	The three-character ISO 4217 currency code for this transaction.	`USD`
BillingStreet__c or ShippingStreet__c	AddressesModel	shipTo.line1	First line of the street address	`123 Main Street`
BillingCity__c or ShippingCity__c	AddressesModel	shipTo.city	City component of the address	`Irvine`
BillingStateCode__c or ShippingStateCode__c	AddressesModel	shipTo.region	State/Province/Region component of the address	`CA`
BillingCountryCode__c or ShippingCountryCode__c	AddressesModel	shipTo.country	Two-character ISO 3166 country code	`US`
BillingPostalCode__c or ShippingPostalCode__c	AddressesModel	shipTo.postalCode	Postal Code/Zip Code component of the address	`92615`

If the Code values of the address are not set, the following fields are used as fallback:

Field	Fallback Field
BillingStateCode__c	BillingState__c
BillingCountryCode__c	BillingCountry__c
ShippingStateCode__c	ShippingState__c
ShippingCountryCode__c	ShippingCountry__c

Info

If multi-currency support is not enabled for your org, the company default currency is used.

Invoice Line Item

Field	AvaTax Model	AvaTax Name	AvaTax Description	Example
Sequence__c	LineItemModel	number	Line number within this document. Must be unique.	`10`
Quantity__c	LineItemModel	quantity	Quantity of items in this line.	`1`
PosTotalNet__c	LineItemModel	amount	Total amount for this line.	`100`
TaxCode__c	LineItemModel	taxCode	Tax Code – System or Custom Tax Code. Use this field if you directly specify the Avalara tax code.	`PS081282`
ON_ItemCode__c To be created	LineItemModel	itemCode	Item Code (SKU) Use this field if you specify an Avalara item code to have Avalara determine the corresponding tax code.	`Y0001`
Title__c	LineItemModel	description	Item description.	`Yarn`
GrossInvoice__c	LineItemModel	taxIncluded	Indicates whether the line has `Tax Included`, defaults to `false`.
ON_VATIN__c To be created	LineItemModel	businessIdentificationNo	VAT ID of the customer for the line item.

Note

AvaTax requires unique invoice line item numbers (sequence), which JustOn usually guarantees. If some custom configuration produces duplicate sequence values, make sure to correct the invoice line item numbering accordingly.

If you use custom tax rules, set either TaxCode__c or ON_ItemCode__c to have Avalara determine the applicable tax. For details, see Working With Avalara Tax Codes.

Tax Data Retrieval

The invoice class and status determine which AvaTax DocumentType is used to retrieve the tax information.

Invoice Class	Invoice Status	DocumentType
Invoice	Draft	SalesOrder
Invoice	Finalized	SalesInvoice
Credit	Draft	ReturnOrder
Credit	Finalized	ReturnInvoice

When retrieving temporary tax data for draft invoices, temporary AvaTax transactions are used, which do not show up in the AvaTax Customer Portal.

When an invoice is finalized, the External Tax Status field is set Final, and the corresponding AvaTax transaction is committed.

Invoice Cancellation

When an invoice is canceled, the cancellation invoice has the same tax data as the canceled invoice. The AvaTax service is not called until the cancellation invoice is finalized.

Upon finalizing the cancellation invoice, the following takes place:

JustOn calls AvaTax to void the canceled invoice.
After voiding the canceled invoice, the External Tax Status field of the cancellation invoice is set Final, and the External Tax Provider Error field is updated.
The tax data of the cancellation invoice is not modified.

Processing the Retrieved AvaTax Tax Data

Upon successful tax data retrieval, JustOn creates tax details for each invoice line item and updates the invoice line item.

Tax Details

Field	AvaTax Model	AvaTax Name	AvaTax Description
Name	TransactionLineDetailModel	taxName	The name of the tax against which this tax amount was calculated.
Rate__c	TransactionLineDetailModel	rate	The rate at which this tax detail was calculated.
Amount__c	TransactionLineDetailModel	tax	The amount of tax for this tax detail.
AppliedTaxRule__c	TransactionLineDetailModel	rateRuleId	The unique ID number of the rule according to which this tax detail was calculated.

Invoice Line Item

Field	Description	Value as Retrieved From AvaTax
TaxRate__c	The tax rate that applies to this invoice line item.	The sum of the `Rate__c` values of the tax details.
PrecalulatedTax__c	The absolute tax amount.	The sum of the `Amount__c` values of the tax details.
AppliedTaxRule__c	The tax rule identified as applicable for this invoice line item.	`null`
TaxCode__c	The tax code.	The tax code used by AvaTax to determine the taxes.
TaxType__c	The type of the tax rate.	`Combined`
TaxProvider__c	The provider that calculated the tax details.	`AvaTax`

Using AVT Fields to Set Additional AvaTax Values

JustOn can write additional AvaTax tax data values to custom fields of the invoice, the invoice line items and the tax details.

Be aware of the following details:

The fields can be defined on the Invoice, Invoice Line Item and Tax Detail objects.
The API field name must to be the same as the field name of the corresponding AvaTax model, prefixed with AVT_, like AVT_companyId.
The values are only copied if there is a corresponding field on the target object.
The AVT field needs to have a compatible data type.
Only primitive data types are supported, like String and Decimal.

AvaTax Source	JustOn Target
TransactionModel	Invoice
TransactionLineModel (TransactionModel.lines)	Invoice Line Item
TransactionLineDetailModel (TransactionLineModel.details)	Tax Detail