Skip to main content
Version: 3.x

AvaTax

Avalara AvaTax is a cloud-based solution automating transaction tax calculations and the tax filing process. Avalara provides real-time tax calculation using tax content from more than 12,000 US taxing jurisdictions and over 200 countries, insuring your transaction tax is calculated based on the most current tax rules.

Prerequisites​

Before you begin, ensure you have met the following requirements:

  • You have created a Avalara account.
  • You have installed the Taxes App.

Configuration​

The AvaTax configuration form consists of three sections: Credentials, Settings, and Address.

Each configuration must have Instance name - it is used to identify it across all the views.

Credentials​

Fields needed to authenticate the instance:

  • Username - the username for the Avatax account. You will generate it in the Avalara dashboard (Settings → License and API keys → License key).
  • Password - the password for the Avatax account. You will generate it in the Avalara dashboard (Settings → License and API keys → License key).
  • Company code - the company code for the AvaTax account.
  • Sandbox - a flag that indicates whether the instance should use the sandbox environment or the production environment.

Settings​

Fields that affect the created transactions:

Document recording​

Taxes App creates AvaTax transactions on two events:

  • while calculating taxes (in order or checkout)
  • while confirming an order

When calculating taxes, the default document type is SalesOrder. It makes the transaction temporary and not visible in the Avalara dashboard.

In the case of order confirmation, the default document type is SalesInvoice. It makes the transaction permanent and visible in the Avalara dashboard.

The AvaTax configuration form in the Taxes App contains Document recording toggle. When switched off, it changes all the document types to SalesOrder. This effectively stops the "document recording", making all the transactions temporary.

Address​

Fields that describe the address of the company.

After entering, the address must be verified by clicking the Verify button that triggers AvaTax address validation. In response, AvaTax returns the validated address the user has to review. After either applying or rejecting suggestions, you can save the configuration.

Mapping transaction fields​

When an order is confirmed, the Taxes App creates a transaction in AvaTax. The transaction contains fields that are mapped from the order. For several fields, you can provide custom values with privateMetadata. You have to make sure to set the value before confirming the order (e.g. when the order is still a draft).

The mutation for setting the private metadata is:

mutation UpdatePrivateMetadata {
  updatePrivateMetadata(
    id: "ORDER_ID"
    input: { key: "METADATA_KEY", value: "METADATA_VALUE" }
  ) {
    item {
      metadata {
        key
        value
      }
    }
  }
}

where ORDER_ID is the id of the order, METADATA_KEY is key of the supported mapping, and METADATA_VALUE is the value for that field.

Taxes App supports the following mappings:

Document code​

Metadata key: avataxDocumentCode

By default, the document code is set to be equal to Saleor order id.

If you want to override it, you can do so by providing a value for the privateMetadata field avataxDocumentCode.

caution

Due to AvaTax API restrictions, the document code will be sliced to be under 20 characters.

Entity type​

Metadata key: avataxEntityCode

AvaTax supports entityUseCode field that represents the type of customer the transaction is assigned to. The field is then used to determine the taxability of the transaction.

Let's say you have a draft order that was filled by tax-exempted US government entity. In AvaTax, the code for a "FEDERAL_GOV" entity is "A".

To map the entity type, you need to provide the value for the entityUseCode field of the Order privateMetadata field of key avataxEntityCode and value of "A".

Tax calculation date​

Metadata key: avataxTaxCalculationDate

By default, the tax calculation date is set to be equal to the order creation date from Saleor order.

If you want to override it, you can do so by providing a value for the privateMetadata field avataxTaxCalculationDate.

info

The value of the avataxTaxCalculationDate field must be a valid UTC datetime string.

Was this page helpful?