Cross-Border by Avalara

Overview ↑ Back to top

Heads up! Cross-border must be enabled on your account by Avalara before you can use this feature in WooCommerce AvaTax! Please contact Avalara to set up cross-border.

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.

Requirements ↑ Back to top

Setup ↑ Back to top

There are two components to setup:

Configure target countries ↑ Back to top

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. Login to your Avalara account and go to Settings > Where you collect tax.
  2. The Settings > Where you collect tax menu in Avalara

  3. Select the Customs duty tab, then click Add a country where you want to collect customs duty.
  4. Adding a new country to the Customs Duty tab in Avalara

  5. Select one or more countries to add and click Add selected countries.
  6. Adding countries where you collect customs duty in Avalara

  7. Find the newly-added country in the Nexus list and click Details.
  8. Selecting the details button for a customs duty country in Avalara

  9. Update the country’s detail page as needed and click Save.
  10. Note: If you intend to collect all costs from your customers, select the This company is the importer of record setting.

    Updating a supported country in Avalara

  11. Repeat steps 4-5 as needed for each country you’ve added.
  12. Now, go back to Settings > Where you collect tax and select the VAT / GST tab. Repeat steps 3-5 as needed.
  13. Adding a country to support VAT / GST calculation in Avalara

Automatically sync your product catalog ↑ Back to top

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.

Please make sure that you’ve set up your Avalara account and plugin settings for the Production environment before continuing.

To sync your product catalog:

  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:
  4. avatax-cross-border-connection-fields

  5. 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.
  6. Click Save Changes. Once your AvaTax credentials are saved, scroll back to the Cross-border classification sectiom to connect.
  7. Click the Connect button for Cross-Border product sync. This will begin syncing your product catalog to Avalara AvaTax for classification. Once the sync begans, an admin notice will display “Your catalog is syncing to AvaTax.”

The initial connection will sync the products for the entire product catalog. The process will take up to 24 hours to create the classification 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, only the parent product will be synced for classification. All variables will inherit codes from the parent product.

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’s no additional charge to you 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.

Manually classify your product catalog ↑ Back to top

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

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:

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.

Updating a product in Avalara

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.

Checkout experience ↑ Back to top

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.

Cross-border fees as a single total at WooCommerce checkout

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

Itemized cross-border fees at WooCommerce 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.

Managing international orders ↑ Back to top

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

Cross-border fees on an order in the WooCommerce backend

Note: Manually adding orders with cross-border calculation is not currently supported. If you need to submit an order on behalf of a customer, we recommend using the User Switching plugin to do so from the frontend.

Refunding orders ↑ Back to top

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.

Viewing orders in Avalara ↑ Back to top

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

Cross-border reporting ↑ Back to top

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.

Generating a cross-border report in Avalara

Frequently asked questions ↑ Back to top

Q: Why can’t I enter product prices inclusive of tax?
A: Avalara’s API does not yet support calculating tax from an inclusive price, so this isn’t possible right now in the plugin. We’ll continue to monitor this so we can support it in the plugin once possible in the API.

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.

FAQ for automatically syncing products ↑ Back to top

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 with the updated information. Learn more in the Re-classify products section.


Troubleshooting ↑ Back to top

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.

Syncing errors ↑ Back to top

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.

Error messages ↑ Back to top

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.

Product sync is unavailable for sandbox accounts.
The product catalog can’t be synced in the Development environment using Alavara sandbox credentials. Please be sure you’re using the Production environment with Avalara production credentials.

Please select at least one supported country.
Make sure you’ve selected at 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.

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_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).

Questions & support

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.

AvaTax Documentation ↑ Back to top

Return to the main AvaTax documentation →

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top