Setting Up Tax Data Retrieval From AvaTax

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

JustOn supports the AvaTax service from Avalara as external tax provider. For technical details about the AvaTax service integration, see AvaTax Implementation Details.

Info

For general information about JustOn's tax capabilities, see JustOn Tax Handling.

Working With Avalara Tax Codes

Generally, Avalara associates tax codes to tax rules, which determine the applicable taxes for an invoice line item. Avalara has predefined tax codes with a taxability profile in place for all US states. You can, however, add custom tax rules, which involves adding jurisdictions, tax codes and items.

If your business uses custom tax rules and therefore manages items in Avalara, you must, consequently, configure your invoice line items to specify an Avalara tax code. There are two ways to do so:

Using Item Codes

In Avalara, you can manage items and item codes, and then map items to tax codes. Doing so, supports the following workflow:

(1) Manage item codes in Avalara.

(2) Create the field ON_ItemCode__c on the Invoice Line Item object.

(3) Use the field ON_ItemCode__c of the invoice line item to set the corresponding item code defined in Avalara. You can use the ON field mechanism, Salesforce flows or other automation tools to have the field ON_ItemCode__c set automatically when generating invoices.

(4) Avalara determines the tax code to apply via your defined item-tax code mapping.

Directly Passing Tax Codes

Alternatively, you can specify the tax code directly:

(1) Manage tax codes in Avalara.

(2) Use the field TaxCode__c of the invoice line item to set the intended Avalara tax code. You can use the ON field mechanism, flows or other automation tools to have the field TaxCode__c set automatically when generating invoices.

Note

Omitting or using the wrong tax code may result in an incorrect tax calculation.

EU Sales With AvaTax

Starting with v2.75, JustOn supports AvaTax VAT transactions. This allows for using the tax retrieval service for sales in the European Union as well, including full support for the reverse charge procedure.

If you need VAT transactions in AvaTax, you must configure your invoice line items to specify the VAT identification number (VATIN). To this end, you create the field ON_VATIN__c on the Invoice Line Item object to specify the relevant VATIN (for example, using a formula that retrieves the value from VATIN__c of the account).

Doing so, supports the following workflows:

  • Seller and buyer in the same EU country

    AvaTax makes no distinction between B2C and B2B – if there is a taxable product, the relevant rate is returned.

  • Seller and buyer in different EU countries

    If the buyer is a VAT-registered business (ON_VATIN__c specifies a EU VATIN, reverse charge applies), AvaTax returns 0% tax. If the buyer is an individual (ON_VATIN__c is empty), AvaTax will use the tax code to distinguish between physical goods and services/digital goods and, consequently, apply the corresponding tax rules.

  • Seller in the EU, buyer outside the EU

    AvaTax will use the tax code to distinguish between physical goods and services/digital goods and, consequently, apply the corresponding tax rules.

Configuring AvaTax Access

The AvaTax module uses a Named Credential to access the AvaTax service.

Info

Prior to using AvaTax, your organization must create a user account at Avalara, which is subject to a (chargeable) contract.

To add a named credential for your AvaTax account:

  1. Click to enter Setup, then open Named Credentials.

    In Salesforce Lightning, navigate to Security > Named Credentials.

    In Salesforce Classic, navigate to Security Controls > Named Credentials.

  2. Click New Named Credential.

  3. Enter AvaTax as short label and name.

  4. Specify the AvaTax base URL:

    • SANDBOX: https://sandbox-rest.avatax.com/
    • PRODUCTION: https://rest.avatax.com/

  5. Select the Identity Type Named Principal.

  6. Select the Authentication Protocol Password Authentication.
  7. Enter the user name and password for your AvaTax account.
  8. Make sure that Generate Authorization Header is selected.
  9. Click Save.

Configuring AvaTax Tax Provider

General Configuration

The external tax provider is configured as part of the business entity settings.

Note

Be aware that when using external tax providers like AvaTax, you must specify the complete address information for the business entity.

  1. Click to enter Setup, then open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Business Entity.

  3. Click Edit the row of the business entity you intend to edit.

  4. In the Tax Provider field, specify {"Provider":"AvaTax"}.

    The field Tax Provider uses the JSON format. This allows for passing additional options.

  5. Click Save.

Additional Options

AvaTax supports multiple companies per organization account, that is, a registered (sub) division of your organization (similar to the JustOn business entity).

In addition, you can enable or disable the automatic generation of an invoice document record upon invoice finalization. If it is disabled, JustOn retrieves the tax details from AvaTax, but no document will show up in the AvaTax portal.

Note

The document record generation in AvaTax is disabled by default.

The field Tax Provider uses the JSON format. This allows for passing additional options, like specifying the AvaTax company code. The available options include:

Option Value Descrption Default Value Example
CompanyCode <company code> Specifies the AvaTax company code, DEFAULT if left empty DEFAULT "CompanyCode":"MyCompany"
Record true or false Determines whether to create a document record in AvaTax false "Record":true

To enable the document recording in AvaTax, specify the following JSON expression in the Tax Provider field:

{"Provider":"AvaTax","Record":true}

To specify an AvaTax company, use the tax provider option CompanyCode, like

{"Provider":"AvaTax","CompanyCode":"MyCompany"}

Adding Tax Data Retrieval Button

Usually, the tax data is retrieved automatically upon invoice finalization. Certain business use cases, however, require the tax data to be retrieved manually. To this end, you can add the button External Tax Provider to the invoices list view.

  1. Navigate to the object management settings of the Invoice object.

  2. Open the Search Layouts list.

    In Salesforce Lightning, click Search Layouts for Salesforce Classic.

    In Salesforce Classic, click Search Layouts.

  3. Click Edit in the row of the Invoices List View.

  4. In the Custom Buttons section, move External Tax Provider to the Selected Buttons column.

  5. Click Save to save the modified page layout.

    Depending on the invoice status, the button either invokes the retrieval of draft tax data for draft invoices, or repeats the tax provider update for final invoices.

    Invoice Status Condition Result
    Draft Retrieves draft tax data from the tax provider, replaces existing tax details of invoice line items.
    Open Tax retrieval status is not Final Updates the external tax provider with the final invoice data.

    For help about modifying page layouts, see Managing Page Layouts.

Using Billing Address for Tax Calculation

Usually, the shipping address of a buyer is the relevant location for the tax origin – it determines which tax to apply. This is why JustOn matches the fields Invoice Region, Invoice Country and Invoice State against the shipping address fields of the invoice by default.

Certain business use cases, however, use the billing address to fix the tax. To support this, you can tell JustOn to match Invoice Region, Invoice Country and Invoice State against the billing address fields.

Info

Contact your tax consultant to determine the appropriate way for your business.

  1. Click to enter Setup, then open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Global Settings.

  3. Click Edit in the Default row.
  4. Select the checkbox Use Billing Address for Tax.
  5. Click Save.

Note

This is a global option that cannot be reversed for a single invoice, subscription or account.