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:
- Autocommit - a flag that indicates whether the instance should automatically commit the transactions.
- Shipping tax code - the tax code for shipping.
- Document recording - a flag that indicates whether the instance should record the 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
.
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
.
The value of the avataxTaxCalculationDate
field must be a valid UTC datetime string.