Cross-Border by Avalara

Cross-Border by Avalara helps merchants that sell internationally calculate the Duty and Import Tax assessed at the border for their shipped products and process payment for those fees at checkout. This lets you reduce customs delay and remove unexpected fees, ensuring an optimal experience for international purchases as they pay all fees at checkout and receive their shipments on time as expected.

In this guide, we’ll walk through how to setup Cross-Border by Avalara so it can be used with WooCommerce AvaTax. For details about setting up and using WooCommerce AvaTax in general, please visit the WooCommerce AvaTax documentation.

• WooCommerce AvaTax v1.10+
• All requirements for WooCommerce AvaTax
• A service entitlement enabled for your Avalara account; contact Avalara to get this setup
• You can enter prices inclusive or exclusive of taxes; click here for more information

There are two components to setup:

• Configuring target countries to identify the countries where you collect and sell to
• Classifying your product catalog so that Avalara knows your WooCommerce product IDs and the harmonized system / tariff codes (HS codes) for those products

First, you’ll need to set up the countries that you want to sell to in your Avalara account. You’ll need to provide some information in Avalara about your status in these jurisdictions, such as:

• Do you have a permanent establishment in this jurisdiction?
• When shipping to this jurisdiction, who is the importer of record?
• Are you shipping using a Delivery Duty Paid (DDP) or Delivery at Place (DAP) service?

Follow the steps below to configure target countries:

1. 1. Login to your Avalara account and go to Settings > Where you collect tax.

1. 1. Select the Customs duty tab, then click Add a country where you want to collect customs duty.

1. 1. Select one or more countries to add and click Add selected countries.

1. 1. Find the newly-added country in the Nexus list and click Details.

1. 1. Update the country’s detail page as needed and click Save.

1. 1. Repeat steps 4-5 as needed for each country you’ve added.
   2. Now, go back to Settings > Where you collect tax and select the VAT / GST tab. Repeat steps 3-5 as needed.

Once your countries are configured, it’s time to ensure your product catalog is added to AvaTax with the harmonized tariff codes and classification codes required to get accurate landed cost estimates for your products in WooCommerce.

This can be done automatically by using Avalara’s item classification service to enable item sync for the countries you sell to. Once enabled, cross-border item codes will be generated and synced back to WooCommerce.

To sync your product catalog:

1. 1. Go to WooCommerce > Settings > Tax, and select the AvaTax page.
   2. Scroll to Connection Settings and make sure the Environment field is set to Production using Avatax production credentials. The product catalog can’t be synced in the development environment.
   3. Under Cross-border classification, enable Sync products to classify for cross-border duties. Once enabled, these connection fields will show up:

1. Fill in the connection fields:
   • AvaTax username – Fill in your Avalara AvaTax username.
   • AvaTax password – Fill in your Avalara AvaTax password.
   • Cross-Border Countries – Select countries to calculate Cross-Border duties. This may affect your monthly AvaTax bill.
2. Click Save Changes. Once your AvaTax credentials are saved, scroll back to the Cross-border classification sectiom to connect.
3. Click the Connect button for Cross-Border product sync. This will begin syncing your product catalog to Avalara AvaTax for classification. Once the sync begins, an admin notice will display “Your catalog is syncing to AvaTax.”

The initial connection will sync the products for the entire product catalog. The classification process can take up to 24 hours to complete and return the relevant codes. You can continue working on your site while your products are syncing. There should not be any site slowness or performance issues during the product sync.

When the sync is complete, an admin notice on the next page load will display: “Your catalog is synced to AvaTax! Cross-border tax calculations can now take place at checkout. Catalog updates will be synced to AvaTax as you add, update, or delete products in WooCommerce.”

WooCommerce AvaTax will now automatically present tariffs and duties at checkout. Learn more about the checkout experience here.

Pause or end a product sync

If you need to pause or end the product sync, you can disconnect to stop sending product data to Avalara AvaTax.

1. Go to WooCommerce > Settings > Tax, and select the AvaTax page.
2. Scroll to Cross-border classification, and select the Disconnect button.
3. A pop-up will ask you to confirm the disconnection. Once confirmed, this will end the product sync process.

You can continue syncing by re-connecting.

Variable products

If you have variable products, the parent product and variations will be synced for classification. All variable products inherit codes from the parent product and there are no additional fees for syncing the variations.

Re-classify products

When a product is updated, it can trigger a re-classification if any of the fields sent to Avalara Avatax are changed. This means that the product will be synced again to create new tariff codes. There are charges by Avalara when a product is re-classified through this process.

A re-classification is only triggered when the following fields are changed:

• Product description (Falls back to short description.)
• Product title
• Product category (Only switching to a new category will trigger a re-classification. You can rename a category without triggering re-classification.)

Currently, you can’t manually request re-classification for specific products. Re-classifications are only done automatically when a product is updated.

We recommend automatically syncing your product catalog to easily manage your tariff codes. However, you also have the option to manually import your products for classification. This is a rigorous process and there are two options:

• Send products to Avalara via SFTP or API
• Add products to Avalara manually

Send products to Avalara via SFTP or API

You can import your products to Avalara with several methods. Click here for guides on how to send products to Avalara and map their tariff codes.

If you decide to send the products via SFTP, you must provide the products in the Google product feed format. We recommend creating a product export from WooCommerce by going to WooCommerce > Products > Export.

Here are some additional resources to assist with creating the Google product feed:

• AvaTax guidelines for importing Google product catalogs
  • ⚠️ Please note that while this document recommends using the product SKU for the Google product feed’s id field, you must use the product ID from WooCommerce instead. This will allow the plugin to find the product in AvaTax based on the AvaTax Item Code.
• Guide to Google product feed / WooCommerce product export mapping

Add products to Avalara manually

Alternatively, you can also add products manually by following the steps below:

1. Go to Settings > What you sell.
2. Click Add an item.
3. Update the item page with the following details:
   • Enter the Item Code. ⚠️ The Item Code should match the WooCommerce product ID for this product.
   • Enter the Item Description. This can be the product’s name.
   • Update the Avalara tax code field.
   • Under Harmonized tariff codes, click Add or update tariff codes and populate the country and tariff code fields.
4. Repeat step 4 for every country that you want to sell this product in.
5. Click Save and get attributes.
6. Update the product attributes if required.
7. Click Save.

Repeat steps 2-7 for every product you need to sell internationally.

When an order is placed on WooCommerce, the plugin will now be able to find the products based on their AvaTax Item Code and AvaTax can then return the proper rates based on the entered country and tariff codes.

Once you’ve completed setup, WooCommerce AvaTax will automatically present tariffs and duties at checkout when all products in the cart have harmonized tariff codes set.

If you, as the merchant, are the importer of record, estimated fees and duties will be added to checkout. The presentation of these fees will vary based on the Display tax totals setting under WooCommerce > Settings > Tax.

If Display tax totals are set to “as a single total”, the fees and duties will be displayed at checkout under a single Import Fees item.

If Display tax totals are set to “itemized”, customers will see each cross-border duty or fee listed individually at checkout.

If you are not the importer of record, the fees will be estimated after the order is submitted and can be viewed on the transaction in your Avalara account.

When viewing an order from the WooCommerce > Orders page, you will see line items for any cross-border fees and duties.

If you need to process a refund for an order with cross-border fees and duties, please first do so in your Avalara account so you can determine the accurate amount for the cross-border fees. You can then use this information to process the refund through WooCommerce or with your payment processor.

You can view cross-border transactions and amounts in Avalara by going to Transactions > Transactions and selecting the order in question.

To download a report on your cross-border transactions, login to Avalara, go to Reports > Transaction reports, and select “Cross border reports” from the Report Category drop-down menu. You can select other filters / limits as desired, and then click Generate and download report to create the report.

Q: Can I enter product prices inclusive of tax?
A: Yes! Avalara’s API now supports calculating tax from an inclusive price. Both the tax and product amount are adjusted to correctly match the target price.

To make sure AvaTax calculates your taxes correctly, set your store’s tax options by logging into your shop and navigating to WooCommerce > Settings > Tax > Tax options > Prices entered with tax.

Q: I don’t see cross-border fees at checkout like I expect. What might be wrong?
A: It sounds like you may not be listed as the importer of record. Please ensure that the This company is the importer of record setting is enabled in Avalara for the country in question.

Q: Is there a limit to how many products I can sync?
A: Nope! There are no limits to how many products you can sync.

Q: Can I choose which products to sync?
A: Currently, you cannot choose which products to sync. On connection, the full product catalog will sync for classification.

Q: What happens when I add a new product?
A: When a new product is created, the product will automatically be synced to Avalara AvaTax for classification.

Q: What happens when I update a product?
A: Depending on what product fields are updated, this may trigger a re-classification. This means that the product will be synced again to create new tariff codes. There are charges by Avalara when a product is re-classified. Learn more in the Re-classify products section.

Q: Can I sync products in my sandbox account?
A: Yes, your product catalog can now be synced in the Development environment using Avalara’s sandbox credentials.

Having trouble? Please check these steps before posting a support request:

• Check the WooCommerce AvaTax documentation to ensure that the plugin is configured properly.
• Please ensure that you meet the requirements for Cross-Border and contact your Avalara representative to ensure they’ve enabled Cross-Border on your account.
• Check the FAQs to see if they address your question.

If there is an error during the initial product sync, or during a production creation / update / deletion sync, you will see an admin notice to resync products. This allows you to resync the entire catalog or only the impacted products. The system will automatically select all products with errors to do another sync attempt.

If the errors persist, please enable Debug Mode:

1. Go to WooCommerce > Settings > Tax tab > AvaTax page.
2. Scroll down and enable Log API requests, responses, and errors for debugging.
3. Once enabled, please attempt another resync to generate the logs and send the logs in your support request.

Cross-border is not enabled on this account. Please contact your Customer Account Manager to setup Cross-Border tax calculation.
Please contact your Avalara representative to enable Cross-Border on your account.

Please select at least one supported country.
Make sure you’ve selected at least one country in the Cross-Border Countries field. Are there no supported countries in the drop-down menu? Please make sure that you’ve
set up your target countries in your Avalara account.

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.

apply_filters( 'wc_avatax_wait_time_to_get_classifications', DAY_IN_SECONDS )
This filter accepts any integer that represents the amount of seconds to wait between a request for classification creation and receiving the HS code. DAY_IN_SECONDS is its default value which equals to 86400 (24 hours).

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.

Return to the main AvaTax documentation →