Avalara AvaTax

Overview

↑ Back to top

Avalara AvaTax provides seamless integration with Avalara’s tax calculation and management services. You can easily and automatically get and charge the appropriate tax rates for your store based on your origin address and your customers’ addresses, and manage all tax reporting in your AvaTax dashboard. AvaTax is available for merchants in almost every country! Avalara AvaTax allows you to charge appropriate tax automatically and track tax records for your WooCommerce transactions, and can also enable AvaTax address validation for your customers. Set your default product and tax shipping codes, override product codes as needed for categories or individual products, and you’re on your way!

Requirements

↑ Back to top

• An Avalara account
• WooCommerce 3.9.4 or newer
• WordPress 5.6
• PHP 7.4 or newer (you can see this under WooCommerce > Status)
• Taxes enabled on your WooCommerce store (head to WooCommerce > Settings, and ensure that the Enable tax rates and calculations checkbox is selected. If not, select it and click the Save changes button to continue)

Installation

↑ Back to top

1. Download the extension from your WooCommerce dashboard.
2. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
3. Click Install Now, and then Activate.
4. Click Configure and read the next section to learn how to set up and configure the plugin.

Getting started

↑ Back to top

Follow the steps below to connect the plugin:

1. 1. Login to Avalara.
   2. Select Account and copy your Account ID to add to the plugin settings.

1. 1. If you recently created your account, you should have received your license key via email from the account admin. If you don’t have that email, you can reset your license key by following these steps:
      • Go to Settings > License and API Keys > Generate License Key.
      • Click Generate. This will create a new license key that you’ll need to use anywhere a license key is required, including the plugin settings.
   2. From your WooCommerce site, go to WooCommerce > Settings > Tax > AvaTax and paste these values in the Account Number and License Key fields.

1. Click Save Changes. When the page refreshes, you’ll be able to enable Tax Calculation and Address Validation.

Once connected, you can enable tax calculation and/or address validation in their dedicated settings sections. If enabling tax calculation, you’ll need to ensure that the Origin Address is populated in the plugin settings. That’s it! You’re ready to start calculating taxes with AvaTax. Click here to learn more about available extension settings.

Extension settings

↑ Back to top

Tax calculation

• Enable AvaTax for tax calculation: Allow AvaTax to calculate taxes for your store. This will override all configured WooCommerce tax rates and only use rates from AvaTax.
• Save transactions in Avalara for viewing: If selected, transactions are automatically submitted to Avalara when the order status is payment received, processing, or complete. If disabled, taxes are calculated at checkout, but transactions are not submitted to Avalara automatically. You need to submit transactions to Avalara manually.
• Save transactions in Avalara for reporting: Submit transactions as “committed” any time the order is sent to AvaTax (which will not be editable). Disable leaving transactions as “uncommitted” in AvaTax for your manual review and commit.
• Supported Locations: Determines locations where taxes should be calculated and filed.
• Specific Locations: If only specific locations are supported, select which locations should calculate tax and submit filings.
• Select your AvaTax company: A list of the applicable companies for the respective Account ID and License Key is populated in this drop-down. Select the applicable Company Code to calculate tax, and post transactions to Avalara. This is a required field.
• Address: Enter the address of your company here and validate it if possible. This is used for the origin to calculate tax and must be completed to enable tax calculation. You may safely change this in the future, as it’s saved with the order for historical reporting.
• Product tax code: The default product tax code to use for your products. Start typing in this field to search and select the default tax code from the autolookup results. This will be used if no additional tax code is set, and can be overridden on a per-category or per-product basis. You can read more details from AvaTax on tax codes.
• Shipping tax code: The default shipping tax code for all shipping methods in your store. Start typing in this field to search and select the default tax code from the autolookup results.
• Cart Calculation: Determine how tax calculations are handled on the cart page. Full tax calculations are always performed at checkout.
• Non-US Customers: If taxes should be calculated in the cart, calculate taxes in the cart for international addresses.
• Business VAT ID: Allow customers to enter a VAT ID at checkout.
• Calculate Colorado Retail Delivery Fee: Set to enable calculation of the Colorado Retail Delivery Fee automatically. Retails delivery fee collection does not apply to all business. Read more information.
• Avalara Transport: Specify who will be responsible for the transportation of goods in a VAT transaction. This setting is available when you edit the specified shipping method at Settings > Shipping > Add Shipping Zone > Add Shipping Method.

Address validation

• Verify addresses: Allow customers to validate their addresses at checkout for US and Canada using the Validate Address option.

Exemption certificate management

• Enable exemption certificates: Allow customers to create and upload certificates for tax exemption.
• Select countries for exemption: Allow customers in the selected countries (US/Canada only) to upload tax exemption certificates during checkout.
• Enable auto-validation of certificates: Allow customers to validate exemption certificates automatically. Note: This feature requires a subscription to an Avalara Exemption Certificate Management service.

Connection settings

• Account ID/Username: Your AvaTax account number. Click here for instructions on finding your account number.
• License Key/Password: Your AvaTax license key. Click here for instructions on finding your license key.
• Choose your account type: Select “production” to use live AvaTax credentials or “development” to use sandbox testing credentials. You may not use live credentials in development mode, or vice versa.
• Enable logging: Log API requests to the WooCommerce > Status > Logs to assist with troubleshooting. As a best practice, please don’t enable this setting unless you’re having issues with the plugin.

Transactions outside the US

• Calculate customs duties: Allow customers to calculate customs duties for orders outside of the US. In AvaTax, line items must have fully qualified tariff code to calculate customs duties for the destination country. After you enable this, you need to connect to AvaTax again to synchronize your products in WooCommerce with AvaTax. You also need to select the the countries outside of the US to automatically assign the HS codes. The following settings are available only after you enable this options:
• AvaTax username: Enter AvaTax user name to connect to AvaTax for product synchronization.
• AvaTax password: Enter AvaTax password to connect to AvaTax for product synchronization.
• Countries for HS Code assignment: Select the countries outside of the US where you want to calculate the customs duties. Avalara assigns HS Codes automatically only for the selected countries.

Exempt users

↑ Back to top

There are two ways to exempt users from taxes on your site:

• Setup the exempt customer in AvaTax (recommended)
• Setup exemptions in WooCommerce

Exempt users in AvaTax

By setting up exemptions directly in AvaTax, you can ensure that customers are exempt from taxes whether they’re a registered user of your site or a guest. To do this, set the user’s email address as the customer code in the AvaTax exemption certificate. Their exemption will then be applied based on their eligibility in AvaTax when they enter their email address at checkout.

Exempt users in WooCommerce

You also set up exemptions in WooCommerce by going to Users, selecting the user in question, and updating the Tax Exemption field. When this user places an order on your site, they’ll be exempt from taxes (partially or fully, based on the type of exemption). Click here to learn more about tax exemption.

Setting product tax codes

↑ Back to top

Your default product tax code, configured in the plugin settings will be used for all products unless overridden at the category level or product level. If you have a tax code set for a category, it will override the default tax code for all products in that category. The tax code can be set while creating or editing a category of products.

If you set a tax code for a product, this will override any category or default product tax codes you’ve configured, as these rules are most specific. You can set a tax code for a product under Product Data > General:

If your product is variable, you can still set the tax code here, which is inherited by variations. You can also set variation-specific tax codes if needed.

Address validation

↑ Back to top

AvaTax provides address validation services for a limited number of countries. If a customer checks out where address validation is supported, the customer can validate their address by clicking Validate Address. If the address is validated properly, the fields will be adjusted and the customer will see a success message. If the address is incorrect, a notice will be displayed with whatever error is returned so the customer can make the suggested adjustment and re-validate the address.

Submit transactions to AvaTax

↑ Back to top

Documents can only be sent to Avalara once, so transactions are only sent to Avalara upon payment. This reduces the number of documents that may need to be voided due to failed payment or cancellation.

Customer orders

↑ Back to top

When a customer completes an order from the checkout process on your site, the customer’s tax is estimated at checkout. That tax is finalized when the order data is sent to Avalara and submitted as a document in AvaTax. If the payment is submitted during the checkout (for example, payment is accepted with a credit card), the transaction will be automatically sent to AvaTax without action needed. For other cases where payment isn’t accepted immediately (e.g. paying via check or cash on delivery), you can manually send an order to Avalara using the Send to Avalara order action. This action can only be taken once per order, so it should be done when the payment is complete.

Manually created orders

↑ Back to top

When manually creating an order in WooCommerce, you can calculate taxes by following the steps below:

1. Select the customer (if they’re already registered) or enter their full billing and/or shipping address and email address.
2. Add products to the order.
3. Save the order.
4. Click Recalculate.

This won’t immediately record a transaction document in Avalara, but is meant to estimate the taxes to charge the customer. Once the customer has paid and a shop admin marks the order as “Processing” or “Complete” (and the totals are no longer editable), the shop admin can use the Send to Avalara action to record the transaction officially. This action can only be used once.

Refund orders

↑ Back to top

Starting with version 1.15.0 of the plugin, full and partial refunds issued in WooCommerce will be automatically reflected in Avatax. The sales tax adjustment will be automatically applied for the month of the refund, not the month of the order. No additional tax adjustments are required. To refund an order in WooCommerce:

1. Log into WordPress.
2. Navigate to WooCommerce > Orders.
3. Select an order and click the Refund button.
4. Set the quantity or manually input the refund amounts for each item you’d like to refund. The refund total amount cannot be more than the order total amount.
5. Click the Refund button to automatically refund the order. You will see a note under Order notes that the refund has been sent to Avalara.

Refunds for committed versus uncommitted transactions

↑ Back to top

Orders from your shop will be sent to Avatax as either a committed or uncommitted transaction depending on your settings in WooCommerce. Our plugin supports any type of refund issued for committed transactions. For uncommitted transactions, refunds will fail if it’s a full, tax-only, percentage, or partial refund. Any other refund will succeed. Whether you need to send transactions to AvaTax as committed or uncommitted depends on your business. We recommend consulting with a tax professional to choose the best option for you. To enable committed transactions:

1. Log into WordPress.
2. Navigate to WooCommerce > Settings > Tax and select the AvaTax page.
3. Enable Set transactions as “committed” when sending to Avalara.
4. Save changes.

For uncommitted transactions that are sent to AvaTax, you can change the status of the transaction in your AvaTax dashboard.

Refund scenarios

↑ Back to top

Our plugin supports a wide range of refund scenarios. Here are some scenarios and what to expect:

Full refunds

To refund the entire order, set the quantity to match the original order quantity for each item you’d like to refund. This will automatically populate the total including tax to be refunded.

Tax-only refunds

To refund the full taxes for an order, set the refundable tax amount to match the original tax for each item. You can also partially refund the tax for one or more items within the same order. If taxes are refunded partially, the amount will be distributed across all tax rates because AvaTax does not support tax-rate-based refunds. To refund an order in full after refunding only taxes, set the quantity for all items to match the original quantity. Then set the refundable tax amount to zero, or manually enter the refund amount for each item. Please be sure to enter the correct tax as WooCommerce does not validate the tax refund amount. For example, if an item’s tax is $2, it’s possible to set the refund tax amount to more than $2 as long as it doesn’t exceed the total refundable amount for the order.

Partial refunds

To fully refund a single item in an order, set the quantity to match the original order quantity for a particular item. To partially refund one or more items, set the quantity for a particular item or manually set a refund amount for each item. To partially refund particular items in an order, manually set the refund amount. Please be sure that you enter partial refund amounts correctly. Partial amounts are not validated so the refund amount can be greater than the quantity sold. It’s possible to refund a single item multiple times, for example, if you need to refund an item in two parts. Or if you refund the tax for an item first, then later the rest of the amount.

VAT support

↑ Back to top

Avalara AvaTax for WooCommerce supports VAT transactions B2C and B2B transactions for sale and digital services in and outside of the EU. Customers can provide VAT ID at the checkout page after they select the Enable VAT option. The Checkout page displays VAT ID and VAT message received from AvaTax. The logs, orders, credit memos, and refunds also display the VAT ID received from AvaTax. WooCommerce stores the VAT message from AvaTax and displays it in Order details in the WooCommerce admin and storefront.

Avalara Transport field for VAT transactions

The Avalara Transport field specifies who will be handling the transportation of goods in a VAT transaction. This helps to apply VAT correctly. You can set this from the WooCommerce shipping settings.

1. Go to WooCommerce > Settings and select the Shipping tab.
2. Select Add Shipping Zone.
3. Enter the Zone Name and select the Zone Regions.
4. Select Add Shipping Method and select an appropriate shipping method, and then select Add Shipping Method.
5. After you have added the shipping method, select Edit to edit the shipping method.
6. In the Avalara Transport field, specify the transporter of the goods for a VAT transaction. The default value is Seller.

Plugin Compatibility

↑ Back to top

Subscriptions

↑ Back to top

AvaTax works with WooCommerce Subscriptions to properly assess tax on initial and recurring orders. For an initial order, tax is calculated on the initial total and recurring total separately, so that customers are shown accurate totals at checkout for both components of the order. If you use a payment gateway that supports recurring total modifications, then AvaTax will also recalculate taxes before the order is processed by the payment gateway. This ensures that your customers are always charged the correct renewal amount while letting you account for changes in customer address or tax regulations automatically. Please be sure you’re using version 1.4.1+ of the plugin to recalculate renewal tax.

Customer/Order/Coupon Export

↑ Back to top

Avalara AvaTax is compatible with WooCommerce Customer / Order CSV Export – when active, AvaTax data will automatically be added to order and customer exports. For the orders export, the VAT ID for a customer will automatically be added to the export file if available. The column name will be vat_id and this will appear after the billing_company column if set, or at the end of the row if not. For customer exports, the customer VAT ID and tax exemption code are automatically added as new columns titled vat_id and tax_exemption, respectively. These are included after the billing_company column if set, or at the end of the row if not.

Local Pickup Plus

↑ Back to top

When Local Pickup Plus is used with AvaTax, the pickup location is used as the ShipTo address for that order or line item rather than the customer address, ensuring that taxes are appropriately calculated for the item’s destination. If more than one shipping location is allowed per order, then AvaTax will change the ShipTo address for each item so that taxes are calculated individually per item using the pickup location as the destination.

Frequently Asked Questions

↑ Back to top

Q: Which customer address is used for tax calculations? A: If the shipping address is completed, then that address is used. Otherwise, the customer billing address is assumed to also be the shipping address, and this address is used for tax calculation. In either case, the customer email address is used as the primary customer ID in Avalara. Q: Does this plugin support AvaTax Cross-Border features to calculate duties and import taxes? A: Yes! If you’re using Cross-Border calculation with AvaTax, you’ll automatically see those duties or import taxes reflected in your Avalara AvaTax tax calculation. No further configuration is needed! Click here to learn more about setting up cross-border calculation in your AvaTax account and using this feature in Avalara AvaTax. Q: Does this plugin support the calculation of the new Colorado Retail Delivery Fee? A: Yes, this plugin will automatically send the needed data to Avalara to determine if orders should include the new Retail Delivery Fee in Colorado. Our plugin is taking into consideration orders that include only virtual products, that have a local pickup shipping method in Colorado, and tax-exempt merchants and doesn’t charge them the tax fee. Also, while we’re sending the required data, you will need to map an item in your Avalara account to correctly assign the tax to a customer’s order. Please set up a new Retail Delivery Fee item and map it to the Retail Delivery Fee Tax Code (OF400000). Also, make sure that the Item Code is set as retail-delivery-fee You can find more information on mapping items to Avalara tax codes here lastly when creating manual orders, please add a “Retail Delivery Fees” fee item valued at $0.27 to automatically apply the fee to the transaction in Avalara. You can learn about manually adding fee items here. Note that this may result in two RDF fees appearing on the transaction in Avalara. To correct this, please open the transaction in your Avalara Dashboard and delete the fee with the following format: fee_ID. We are following the developer documentation for updates and will make improvements when possible. more information on how to do that is here.

Troubleshooting

↑ Back to top

Having trouble? Follow these steps to make sure everything is setup correctly before posting a support request:

1. Please ensure that your site meets the plugin requirements.
2. Check the FAQs to see if they address your question.
3. Confirm that your Account Number and License Key are correct.
4. If your gateway submits paid transactions (such as a credit card), but these orders are not sent to Avalara immediately, it usually means your gateway does not properly trigger the woocommerce_payment_completed action. While we’re happy to help debug this issue, it will need to be fixed by the payment gateway. Using the PayPal Standard gateway is a good way to compare this.
5. If tax is incorrectly calculated, you’ll need to get in touch with the Avalara team since the rates are pulled from there.
6. If tax is not calculated at all, please review the order notes for error sources and confirm that your origin address and tax codes are set.
7. If you manually created the order, please ensure you follow the correct steps for manual orders.
8. Enable logging and submit a help request with the log so we can review the transaction notes to help troubleshoot.

For Developers

↑ Back to top

Avalara AvaTax has several hooks available so that WordPress developers can customize its behavior. If you find that you need additional hooks, please submit a thread to our help desk to request the hooks you need.

Filters

↑ Back to top

apply_filter( 'wc_avatax_validate_address_button_label', $label ) – lets you change the label for address validation from “Validate Address” apply_filters( 'wc_avatax_checkout_origin_address', $origin_address, $cart ) – filters the tax origin address at checkout. Origin address is an array of address fields, $cart is the WC_Cart instance. apply_filters( 'wc_avatax_checkout_destination_address', $destination_address, $cart ) – filters the tax destination address at checkout. The destination address is an array of address fields, $cart is the WC_Cart instance. apply_filters( 'wc_avatax_order_origin_address', $origin_address, $order ) – filters the tax origin address when processing an order. Origin address is an array of address fields, $order is the WC_Order object. apply_filters( 'wc_avatax_order_destination_address', $origin_address, $order ) – filters the tax destination address when processing an order. The destination address is an array of address fields, $order is the WC_Order object. apply_filters( 'wc_avatax_tax_origin_address', $address ) – filters the tax origin address right before sending data to AvaTax. apply_filters( 'wc_avatax_tax_destination_address', $address ) – filters the tax destination address right before sending data to AvaTax. apply_filters( 'wc_avatax_order_ready_statuses', $statuses ) – filters an array of order statuses that allow manual order sending

Actions

↑ Back to top

do_action( 'wc_avatax_after_checkout_tax_calculated' ) – fires after calculating tax for a cart at checkout. do_action( 'wc_avatax_after_order_tax_calculated', $order_id ) – fires after calculating tax for an order. do_action( 'wc_avatax_order_processed', $order_id ) – fires when an order is sent to Avalara.

Questions & Support

↑ Back to top

Have a question before you download? Please fill out this pre-sales form. Already downloaded and need some assistance? Get in touch with support.