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)
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 the Configure link or go to WooCommerce > Settings > Tax > AvaTax and read the next section to learn how to setup and configure the plugin.
Setup and Configuration ↑ Back to top
If you’re upgrading from the existing TaxNOW integration with Avalara, you’ll notice a slightly different workflow. While we’d still recommend checking out the set up details below, we have an overview of how the upgrade process works below that we’d recommend checking out.
When you try to configure the plugin, you’ll be met with just a few blank fields:
In order to set up the plugin and use it, we’ll first need to connect to AvaTax, and then we can complete setup.
Get credentials from Avalara ↑ Back to top
In order to set up the plugin, you’ll need to enter your account number and license key to connect to your AvaTax account.
- First, log into AvaTax. While logged in, you’ll see your account number under the settings screen in the top right. Copy and paste this into the extension settings.
- Now you need your license key. The license key is sent to the account admin when the account is initially created via email. You can search for this email and copy the license key from it, then paste it in the plugin settings. If you no longer have this email, you must reset your license key from “Settings > Generate a License Key > Generate License Key”, and click “Generate”. You’ll need to save this new license key anywhere your AvaTax license key is used (including the plugin settings here).
- Once you’ve saved the account number and license key, the plugin will connect to AvaTax, and open the settings for configuration.
Extension Settings ↑ Back to top
- Enable / Disable – Enable / check this to allow AvaTax to calculate taxes for your store. This will override all configured WooCommerce tax rates and only use rates from AvaTax.
- Supported Locations – Determines locations for which taxes should be calculated and filed. Select “All Locations” to let AvaTax attempt calculation for any address.
- Specific Locations – (Shown if 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. This can be found under “Organizations” in the Company Code column of your organizations list.
- 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 to use, which will be applied to all shipping methods in your store.
- Cart Calculation – Enable to estimate tax on the cart page for international customers.
- Enable VAT – (shown if your origin address is in the EU) Enable to allow customers to enter a VAT ID at checkout.
- Commit Transactions – Enable this to 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.
- Enable / Disable – Enable / check this to allow customers to click “validate address” at checkout to use AvaTax address validation
- Supported Countries – Select countries you sell to for which you want to allow customer address validation via AvaTax. Not all countries you sell may be supported, so they will not be shown.
- Account Number – Your AvaTax account number; follow the steps above to get this
- License Key – Enable to override all configured WooCommerce tax rates and only use rates from AvaTax
- 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 Log – Enable this to log errors in the plugin, which is helpful for troubleshooting. However, as a best practice and for optimal performance, do not enable this unless you experience issues with the plugin.
Landed Cost ↑ Back to top
For merchants who sell internationally, you can enable Landed Cost from Avalara to estimate duty fees and import tariffs, and optionally charge these fees up-front when taking an order.
If you’d like to use Landed Cost, you can read more about enabling and using it here.
Setting Tax Codes ↑ Back to top
Your default product tax code 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 a customer checks out from a country for which address validation is supported, the customer can optionally validate the address at checkout by clicking the “Validate Address” button. If the address is validated properly, the fields will be adjusted and validated, and a success message is rendered.
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
As documents can only be sent to Avalara once, a transaction is only sent to Avalara upon order payment. This reduces the number of documents that might 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 like the Cheque gateway where payment isn’t accepted immediately, admins 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 the WooCommerce admin, the “Calculate Taxes” button can be used to get tax rates from AvaTax. In order to use this, the customer’s full billing or shipping address and email address must be saved first; you can save the order with this information completed, then click “Calculate Taxes” after saving the order initially to continue manually creating the order.
Note that 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 (one time use only).
Refunded Orders ↑ Back to top
Avalara handles tax liability at the line item level, so refunds with a general amount (not entered for a specific line item) do not send a return adjustment to Avalara. Refunds with line item amounts will send adjustments.
If an order is refunded in full, the corresponding Avalara document is simply voided and no return adjustment is sent.
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.
Order CSV 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.
Order XML Export ↑ Back to top
WooCommerce AvaTax is compatible with WooCommerce Customer / Order XML 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 tag name will be
VATId and this will appear after the
BillingPhone tag if set, or at the end of the order data if not.
For customer exports, the customer VAT ID and tax exemption code are automatically added as new tags titled
TaxExemption, respectively. These are included after the
BillingCompany tag if set, or at the end of the customer data 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 line item (or order) 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.
Upgrading from TaxNOW ↑ Back to top
If you’d used the previous TaxNOW integration for Avalara, you can very easily upgrade to using WooCommerce AvaTax. While the TaxNOW plugin is installed and active, you can also install and activate WooCommerce AvaTax. This will trigger the upgrade routine in WooCommerce AvaTax, and will deactivate the TaxNOW integration:
Behind the scenes, WooCommerce AvaTax will pull in your previous settings from TaxNOW (such as whether address validation was enabled or not), along with any per-product tax rates you’d configured. These will be saved into the new WooCommerce AvaTax settings and tax rates will be maintained on your WooCommerce products. You can double-check that your credentials and settings are correct under WooCommerce > Settings > Tax > AvaTax.
TaxNOW should now remain deactivated, as it should not be run alongside of WooCommerce AvaTax. You can leave it installed until you’ve confirmed that all settings and product tax codes have been migrated successfully, and the TaxNOW plugin can then be safely deleted.
Frequently Asked Questions ↑ Back to top
Q: Can I set exemptions for certain customers?
A: Sure thing! You can set an exemption by editing the user and scrolling down to “Customer Tax Settings”. Here you can pick an exemption reason, then save the user to save the new tax exemptions:
Tax exemptions cannot be currently set without a user account, so guest checkout cannot leverage exemptions. If this feature is important to you, please let our team know you’d like to vote for it.
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.
Troubleshooting ↑ Back to top
Having trouble? Follow these steps to make sure everything is setup correctly before posting a support request:
- 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 (a) review the order notes for error sources, and (b) confirm that your origin address and tax codes are set.
- Double check that origin address and tax codes are configured 😉
- Did you manually create this order? Make sure you save it first with a non-paid order status, then click “Calculate Taxes” (AvaTax needs to get the saved customer info before it can provide rates)
- 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 buy? Please fill out this pre-sales form.
Already purchased and need some assistance? Get in touch with support via the help desk.