Overview ↑ Back to top
WooCommerce AvaTax provides a 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!
WooCommerce 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 (paid service, free trial available)
- WooCommerce 2.6.14 or newer
- PHP 5.3 or newer (you can see this under WooCommerce > Status)
- Taxes enabled on your WooCommerce store (by enabling the “Enable tax rates and calculations” under WooCommerce > Settings > General)
Installation ↑ Back to top
- Download the extension from your WooCommerce dashboard.
- Go to Plugins > Add New > Upload and select the ZIP file you just downloaded.
- Click Install Now, and then Activate.
- Click Configure and read the next section to learn how to setup and configure the plugin.
Getting started ↑ Back to top
Follow the steps below to connect the plugin:
- Login to Avalara.
- Select Account and copy your Account ID to add to the plugin settings.
- If you recently created your account, you should have received your license key via email to 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.
- From your WooCommerce site, go to WooCommerce > Settings > Tax > AvaTax and paste these values in the Account Number and License Key fields.
- 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
- Enable / Disable: Allow AvaTax to calculate taxes for your store. This will override all configured WooCommerce tax rates and only use rates from AvaTax.
- Record Calculations: Send permanent transactions to Avalara when an order is placed. If disabled, tax will still be calculated at checkout, but orders will need to be recorded in your Avalara account manually or by other integrations.
- Commit Transactions: Submit transactions as “committed” any time the order is sent to AvaTax (which will not be editable). Disable to leave 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.
- Company Code: Enter the company code for the organization in AvaTax you want to connect to WooCommerce. Your Company Code is auto filled and can also be found in AvaTax under “Settings”.
- Origin 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.
- Default Product Tax Code: Enter the default tax code to use for your products. 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.
- Default Shipping Tax Code: Enter the default shipping tax code, which will be applied to all shipping methods in your store.
- Cart Calculation: Determine how tax calculations are handled on the cart page. Full tax calculations are always performed at checkout. You may incur fees from Avalara for full tax calculations in the cart.
- Non-US Customers: If taxes should be calculated in the cart, calculate taxes in the cart for international addresses.
- Enable VAT: Allow customers to enter a VAT ID at checkout.
- Enable / Disable: Allow customers to validate their addresses at checkout using AvaTax address validation.
- Supported Countries: Select countries where you want to allow customer address validation via AvaTax. Unsupported countries won’t be available for selection.
- Require for Tax Calculation: Require address validation before orders can be placed with calculated tax.
- Account Number: Your AvaTax account number. Click here for instructions on finding your account number.
- License Key: Your AvaTax license key. Click here for instructions on finding your license key.
- Environment: 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.
- Debug Mode: 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.
Exempt users ↑ Back to top
There are two ways to exempt users from taxes on your site:
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 setup 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.
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:
- Select the customer (if they’re already registered) or enter their full billing and / or shipping address and email address.
- Add products to the order.
- Save the order.
- 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.
Refunded Orders ↑ Back to top
If an order is refunded in full, the corresponding Avalara document is voided and no return adjustment is sent. If you need to partially refund an order, you should create a Return Invoice in Avalara to determine the correct amount of tax to refund for each order item.
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
WooCommerce 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 into 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
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 WooCommerce AvaTax tax calculation. No further configuration needed! Click here to learn more about setting up cross-border calculation in your AvaTax account and using this feature in WooCommerce AvaTax.
Troubleshooting ↑ Back to top
Having trouble? Follow these steps to make sure everything is setup correctly before posting a support request:
- Please ensure that your site meets the plugin requirements.
- Check the FAQs to see if they address your question.
- Confirm that your Account Number and License Key are correct.
- 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_completedaction. 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.
- If tax is incorrectly calculated, you’ll need to get in touch with the Avalara team since the rates are pulled from there.
- 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.
- If you manually created the order, please ensure you follow the correct steps for manual orders.
- 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
WooCommerce 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. 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. Destination address is an array of address fields, $order is the WC_Order object.
apply_filters( 'wc_avatax_tax_origin_address', $address ) – filters the the tax origin address right before sending data to AvaTax.
apply_filters( 'wc_avatax_tax_destination_address', $address ) – filters the 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 via the help desk.