action.skip

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.

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 Temporary AvaTax Transaction
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