Documentation You are here: start » v » 2.0 » taxes

Taxes. And Death. And More Taxes.

How Taxes Work in FoxyCart

A “tax” in FoxyCart is a standalone set of properties that define a particular tax that can be applied to your product categories. Your store can have zero tax rates or 100, and they can be applied individually or in parallel, but the best way to understand how taxes work in FoxyCart is to dive into the admin to look at the available options.

Creating a Tax Rate

The section below will discuss each individual option you'll see when you hit the “taxes” menu item in your store's admin.

This select box allows you to load previously configured taxes to view or edit. It also has options to add a new tax or to delete the current tax.
Tax Summary
This is an informational field that includes the tax name, tax rate, and tax type.
Tax Name
This is the name given to the tax that will be displayed to your customer and also included in API requests and in the transaction datafeed.
Tax Type
This select box has five options.
  • Global will apply to the order regardless the shipping or billing information.
  • Union will apply if the customer's shipping country (or billing country, if no shipping address is present) is an EU member state.
  • Country will apply the tax only if the country entered in the tax's settings matches the customer's shipping country (or billing country, if no shipping address is present).
  • Region will apply only if the country and state/province entered in the tax's settings match the customer's shipping address (or billing country, if no shipping address is present).
  • Local will apply only if the country, state/province, and city entered in the tax's settings match the customer's shipping address (or billing country, if no shipping address is present).
Country, Region, City
Location data to be used for the tax type, above.
Tax is Calculated Automatically
This option allows you to set country or region taxes to set tax rates automatically. See below for more details.
For the “Union” tax type, this option allows the “normal” VAT rates per country
Tax Service Provider
Choose between our currently supported tax rate service providers, currently including Avalara, Thomas Reuters, and others.
Tax Rate (%)
This is the tax rate to be applied as a percentage. So if a tax is 17.5%, enter 17.5, not 0.175.
This input will not be shown if you have automatic tax calculation selected.
Use the Origin Country Tax Rates
For EU VAT as of 2015, there may be situations where you need to charge your store's country's VAT rate instead of the customer's country's rate. This option lets you set a single country's rate to be applied for all EU member states.
Exempt Customers With a Tax ID
Removes the tax if a customer has a Tax ID. More info here.
Apply to Shipping & Handling
If checked, then when this tax applies to a product, it will also be collected on the amount charged for shipping and handling. Useful if you must collect tax on the freight you charge to your customer as part of the sale.
This input will not be shown if you have automatic tax calculation selected, as that is determined automatically.
Applied to Categories
This will list categories that currently apply the tax. See the below section for more info.

Taxes and Categories

Taxes, by themselves, don't actually do anything. In order for a tax to be applied it must be associated with a category. Once associated, any products in that category will get the appropriate taxes applied. To associate a tax with a category, simply check the appropriate checkbox(es) when you edit your category.

How Multiple Taxes Work Together

If you have multiple taxes to be applied in one transaction they will be applied individually. Here's a quick example of what your cart could look like o n pageload on checkout, when certain taxes are “TBD” because the address info hasn't been completed yet:

A FoxyCart cart with multiple taxes

Taxes and Billing v. Shipping Addresses

FoxyCart applies taxes based on the shipping address. If a separate shipping address is not specified, the billing address is assumed to be the shipping address, and taxes are applied accordingly. While there is some debate online as to whether or not this is correct, we have asked multiple tax experts and tax rate services, and this approach is what we believe to be the most correct at this point.

Tax-Exempt Customers

To allow customers to opt out of taxes, you first need to understand how the “exempt customers with a tax id” checkbox works. If you've enabled this option and a customer checks out with a non-empty customer_tax_id value, FoxyCart will remove the appropriate taxes.

To enable the option to exempt customers with tax id, first go to your Taxes Settings and select the tax for which you'd like to offer the exemption. Check the exempt customers with a tax id: option and save. You'll need to repeat this for each tax you have set up where you'd like to offer the exemption.

You can add a Customer Tax ID input to your checkout easily in the template configuration page of your admin, under the checkout → “Customize which checkout fields are shown and required” section. Here you can hide the field (default), make it optional, or make it required.

To pass the tax ID value for a customer from your own website through the cart, you can do that by making use of prepopulation. This simply means calling your cart with the name of the field included, and can be with a product add to cart, or a separate JSONP call to the cart. Because the tax ID could be in the billing or the shipping address, there are two possible fields you'll need to prepopulate, shipping_tax_id and billing_tax_id. As an example of doing that with JSONP:

var customer_tax_id = "#########";
FC.client.request('https://'+FC.settings.storedomain+'/cart?shipping_tax_id=' + customer_tax_id + '&billing_tax_id=' + customer_tax_id);

If you want to run that code on your own website - it will need to be wrapped within an onLoad function and a ready.done event function to ensure it runs when the FoxyCart javascript has initialised. That would look like this:

var FC = FC || {};
FC.onLoad = function() {
    FC.client.on("ready.done", function() {
        var customer_tax_id = "#########";
        FC.client.request('https://'+FC.settings.storedomain+'/cart?shipping_tax_id=' + customer_tax_id + '&billing_tax_id=' + customer_tax_id);

You can also add this value via the API, if you'd like to control things more tightly. (We plan on adding the ability to modify customers in our admin in a future release.) Even if the field is not visible on the checkout, if the customer has a customer_tax_id, the taxes will behave as expected on the checkout. In this way, you could have that field hidden, and manually apply tax ID numbers (via an API script) after doing your own validation, and allow only approved customers to be tax-exempt.

Note that no validation on the number is performed. Please vote for this request.

Automatically Calculated Taxes

If the “Tax is Calculated Automatically” checkbox is checked for a given tax, taxes will be calculated automatically within the designated area for that tax. The default service provider allows for automatic rates in United States and Canada, or when the “Union” tax type is set. If you have an Avalara account, you can also configure that native integration for live rates in all countries and regions they support.

FoxyCart Default Automatic Tax Rates in the US and CA

As an example of auto-calculated tax, if you have a tax set for California that is set to calculate automatically, FoxyCart will query the tax database based on the customer's zip code and/or city, and apply the appropriate tax rate (which may include state, county, city, or other tax jurisdictions). This automatic lookup will dictate if the tax should apply to shipping or not, and if it relates to the billing or shipping address.

Our tax database is provided by Tax Data Systems, which is updated on a monthly basis. Note that neither FoxyCart nor Tax Data Systems makes any warranty or claim as to the accuracy of the tax data returned, but many very large merchants use Tax Data Systems. Currently we use a two different versions of the database:

  1. The default approach is to use the more accurate database, which provides the tax rate based on the city name. When a customer enters their ZIP code, all matching city names are returned. The customer can then select the appropriate city, and the corresponding tax rate will be used.
  2. The other database provides a single rate per zip code that provides a single tax rate per zip code. In the event there are multiple tax rates in a single zip code, the more populated zip code's rate is used. This database is used if the ZIP to city autocompletion is disabled in the template configuration.

Automatic EU VAT Tax Rates

The EU VAT is complicated, and the changes at the beginning of 2015 certainly didn't help. While we're not tax experts on our end, we have tried to give enough flexibility for any merchant that needs to collect the EU VAT. We encourage you to familiarize yourself with the options on the “Union” tax, but here are a few notes:

  • You can automatically apply the correct VAT rate based on the customer's country, as required for some products by the 2015 changes.
    • To do this, create a “Union” tax type, turn on automatic calculations, and leave the “origin country tax rates” set to “no”.
  • You can alternately automatically apply your store's country's VAT tax rate, for other types of products (as of 2015).
    • To do this, create a “Union” tax type, turn on automatic calculations, and change the “origin country tax rates” set to “yes”. Then set the country to be the country whose rates you'd like to apply to all EU customers.
  • You can also apply an arbitrary rate if a customer is in any EU member state.
    • To do this, create a “Union” tax type, turn off automatic calculations, and set the rate as desired.
  • And you can apply normal country-based tax rates individually. So if you have specific products that have alternate rates that vary by country, you can create ~30 different country-based tax rates as needed.
  • We use this open source tax library for our rates, which takes its data from Please note that there is no warranty or claim of accuracy for the automatic tax rates we provide, though we will certainly update them if an issue is brought to our attention.

Please note that the EU VAT requirements are many, and we cannot guarantee our functionality as it relates to any country's tax requirements. At this point, there are a few known issues you should be aware of:

  1. We are still unclear on the requirements for displaying taxes including the VAT. Since certain products now (as of 2015) are taxed at the VAT rate of the customer, this would make it significantly more difficult to actually display a price to a customer until you know with near 100% certainty what country the customer is located in.
  2. The new rules for customer-based VAT rates require two separate corroborating pieces of data to confirm a customer's country. Our geo IP database determines a customer's country with 99%+ accuracy, and the customer then provides their own address. That said, it's technically possible for a customer to change their country and have a mismatch, which might not be enough for the EU VAT requirements.
  3. Please be aware of any data retention requirements, and note that FoxyCart does purge data from inactive stores occasionally. (So if you cancel your FoxyCart subscription, you'll need to keep your own backups as necessary.)
  4. As noted above, our Tax ID field currently does not have any validation. More info here.

Avalara AvaTax 15 Automatic Tax Rates

If you have an Avalara account, you can add your credentials to the integrations page as shown: Avalara AvaTax 15 Native Integration

Important Notes

  • Always be sure to keep your service url correct according to whether or not you're using a live Avalara account or a development account.
  • FoxyCart uses the category code for products as the tax code sent to Avalara, and Avalara sets a limit on the tax code to a maximum of 25 characters. If your category code exceeds that length, we trim the code to be 25 characters. To ensure things behave as you expect, we recommend setting your category codes to not be longer than 25 characters.
  • After you have input your Avalara credentials, click the test button to ensure they are connecting correctly.

For more information about each setting, see the inline help in the admin by clicking on the ? box. If you have further questions about the configuration information here, please contact Avalara.

Once your native Avalara integration is configured, you can select it as a service provider when configuring a tax:

Avalara Tax Service Provider

Address Validation

The “use address validation” option within your Avalara settings will ensure customer addresses used on the checkout page in the supported countries you specify are validated via Avalara's address validation system and confirmed by the customer as shown below:

Avalara Address validation valid address example

If the address is invalid, your customers will see this message, and they will still be able to complete the checkout or modify the address:

Avalara Address validation invalid address example Automatic Tax Rates

We support for automatic rate calculation as well.

If you have an TaxJar account, you can add your credentials to the integrations page as shown under “native integrations”: TaxJar Native Integration

  1. Enter your TaxJar api token from your TaxJar account.
  2. Map your FoxyCart categories to TaxJar's product tax codes to ensure the proper values are sent to TaxJar for the products in the categories.
  3. If you'd like to commit the details of the automatic tax calculations to TaxJar as an Order Transaction, check the box for “create invoices”.

For more information about each setting, see the inline help in the admin by clicking on the ? box. If you have further questions about the configuration information here, please contact TaxJar.

Once your native TaxJar integration is configured, you can select it as a service provider when configuring a tax:

TaxJar Selection

Thomas Reuters ONESOURCE

We support ONESOURCE for automatic rate calculation as well. Some things to keep in mind:

  • All product categories should be configured to use OneSource to get tax rates. Please avoid mixing OneSource and non-OneSource tax rates in the same cart or transaction.
  • To that end, a store should only and always use OneSource. If different tax rate providers are mixed and matched, the displayed tax total will likely not line up with what's actually charged to the customer and displayed on the receipt.
  • In the event that the tax rate for shipping is different than the tax rate for the products, Foxy will display (on the cart and checkout) an estimate using the product's rate for shipping. This can result in the final tax total being slightly lower than displayed on the checkout.
    • Our recommendation is to add language on the tax to indicate it's “estimated”.

Please let us know if you have any questions.

Current Limitations and Future Improvements

Tax-Inclusive Pricing

While there are currently workarounds to get tax-inclusive products, vote for native tax-inclusive pricing support if that'd benefit you.

Cumulative Taxes

Though cumulative taxes can almost always be supported (with FoxyCart's current functionality) with just a little bit of basic algebra, please vote for native cumulative tax functionality if that'd benefit you.

Site Tools