Skip to content

VirtoCommerce/vc-module-avatax

Repository files navigation

Avalara Tax Provider

CI status Quality gate Reliability rating Security rating Sqale rating

Avalara.Tax module provides real time integration with Avalara Tax automation. This module is officially certified by Avalara to be compatible with Avalara API.

Avalara Tax UI

Documentation

Working with taxes in Avalara tax module

Installation

Installing the module:

  • Automatically: in VC Manager go to Configuration -> Modules -> Avalara tax -> Install
  • Manually:

Settings

Avalara connection settings

The module can be configured in three places:

  • Platfrom config file: appsettings.json
  • Platform-wide settings: Settings -> Taxes -> Avalara or Modules -> Installed -> Avalara tax -> Settings
  • Store-specific settings: Stores -> (your store) -> Tax providers -> Avalara taxes

Confidential account settings AccountNumber and LicenseKey provided by Avalara during registration process should be configured in appsetting.json:

 "Tax": {
        "Avalara": {
            "AccountNumber": "********",
            "LicenseKey": "**************"
        }
    }

Others nonconfidential settings should be configured at Store-specific settings: Stores -> (your store) -> Tax providers -> Avalara taxes

  • Avalara.Tax.Credentials.CompanyCode - Company code that should match the code provided to the company registered in Avalara admin manager. This allows to store transactions for different stores to different AvaTax companies if necessary.
  • Avalara.Tax.Credentials.ServiceUrl - Link to Avalara API service:
    • https://sandbox-rest.avatax.com for the development environment;
    • https://rest.avatax.com for the production environment.
  • Avalara.Tax.Credentials.AdminAreaUrl - Link to Avalara admin page:
    • https://admin-development.avalara.net for the development environment;
    • https://admin-avatax.avalara.net for the production environment. AvaTax module uses this setting to build the URL to the transaction. Note that environments for both Avalara.Tax.Credentials.ServiceUrl and Avalara.Tax.Credentials.AdminAreaUrl settings should match.

Settings for automatic order synchronization should be configured at Platform-wide settings: Settings -> Taxes -> Avalara or Modules -> Installed -> Avalara tax -> Settings

  • Avalara.Tax.ScheduledOrdersSynchronization.IsEnabled - Enable or disable automatic order synchronization with AvaTax
  • Avalara.Tax.ScheduledOrdersSynchronization.CronExpression - CRON expression for the automatic order synchronization schedule. By default, it runs orders synchronization once every day.

Also, both of these blades have the "Test connection with AvaTax" widget. You can verify that the connection to Avalara Tax API will work with your current settings (even before saving the changes) by clicking this widget:

  • If the test passed, the widget will turn green. this means that currently entered credentials and the service URL are correct, and these settings can be safely saved.

    Test connection widget, success

  • Otherwise, the widget will turn red, and the error status will appear in the blade header. You can click the "See details" link to see the explanation of the error.

    Test connection widget, error message

Note: if the tax calculation is disabled (Avalara.Tax.IsEnabled is turned off), the Avalara tax provider will ignore any tax requests, and this may lead to incorrect tax calculation.

Sending transactions to AvaTax

Avalara.Tax module allows to create AvaTax transactions for orders. It creates a SalesInvoice transaction for orders:

  • Document code matches order number;
  • Document date matches order date;
  • Line items contain all line items from the order plus one more line item for the shipping.

There are 3 ways to send the order to AvaTax:

  • Automatically:
    • Enable the Avalara.Tax.ScheduledOrdersSynchronization.IsEnabled setting and adjust the schedule in the Avalara.Tax.ScheduledOrdersSynchronization.CronExpression setting;
    • Just wait for the job execution.
  • Manually:
    • Single order: go to the order details blade, click the AvaTax widget and then click the Send to AvaTax command; image
    • Multiple orders: go to the orders list blade, select needed orders and click the Send to AvaTax button. image

Note: you should set the AvaTax as tax provider for the store to be able to send transactions to AvaTax.

You can also review the AvaTax transaction details for the order by clicking the AvaTax widget on the order details blade. AvaTax transaction details blade It displays the following information:

  • Date when the order was sent to AvaTax;
  • Link to the AvaTax transaction corresponding to the order;
  • Raw AvaTax transaction representation.

Address validation

This module also contains an action for validating addresses using AvaTax.

curl -X POST "https://my-admin.virtocommerce.comapi/tax/avatax/address/validate" -H "accept:text/json" 

Parameters: request - an instance of AddressValidationRequest class. It contains the address to validate and the storeId to extract AvaTax connection settings for address validation.

This method can be used in storefront theme to prevent creation of order with invalid (not acceptable by AvaTax) address.

Configuring tax types

Cart/order items should be assigned to tax category in order to calculate taxes correctly. That can be done by applying tax codes to the catalog items. That is called "Tax type" in VirtoCommerce platform. If none of the codes assigned to the item Avalara will calculate taxes by applying default code. So if that is the right choice in your case, you can leave "Tax Type" property value blank. Otherwise define available tax types in general settings of VirtoCommerce platform and apply appropriate types to the items. Note that you can apply tax type to the whole category of items. In that case all items in particular category and in nested subcategories will have the selected tax type code.

The tax type can be selected in the following locations:

  • Category: Catalogs -> (your catalog) -> (your category) -> Manage -> Tax type;
  • Item: Catalogs -> (your catalog) -> (your category) -> (your item) -> Tax type;
  • Shipping method: Stores -> (your store) -> Shipping methods -> (your shipping method) -> Tax type.

Note that the available tax types can be configured in VC Platform settings: Settings -> Commerce -> General -> Tax types.

Tax exemptions

This module can also provide the exemption number for selected customers to the Avalara Tax API. To configure it, follow these steps:

  1. Open the customer details for the customer you want to configure exemption for;
  2. Open dynamic properties for that customer;
  3. Add the dynamic property named Tax exempt and select the ShortText type.
  4. Fill the exemption certificate number to the value of this property.

License

Copyright (c) Virto Solutions LTD. All rights reserved.

Licensed under the Virto Commerce Open Software License (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://virtocommerce.com/opensourcelicense

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.