Magento

Magento Sales Tax Extension Guide

Platform
Magento CE & EE
Versions
1.7.x - 1.9.x
Extension
Magento Connect
Last Updated
August 10, 2016

We put together this integration guide for Magento 1.x merchants and developers looking to better understand TaxJar’s extension for sales tax calculations. Using Magento 2? Check out our official Magento 2 sales tax extension guide.

You’ll learn how TaxJar provides free checkout calculations with our SmartCalcs API and zip-based rates for native Magento calculations as a fallback. Along the way, we’ll configure your store to collect sales tax where you have nexus, handle product exemptions, import orders into TaxJar, and much more. For a primer on everything sales tax, read our Magento sales tax guide before getting started.

Getting Started with TaxJar

First install the Magento sales tax extension. The easiest way is to use Magento Connect and install it from your Magento admin panel:

Installing TaxJar from Magento Connect

Alternatively, you can access all of the code on GitHub and download the extension as a ZIP file by clicking Download ZIP.

If you’re installing the extension manually, upload all files in the /app directory to their respective directories.

That’s it!

If you’re already logged in to your Magento admin panel, log out and log back in again for a clean slate.

Pre-Import Checklist

Before going further, let’s review some of your existing Magento settings to make sure TaxJar is clear for landing. Log in to your Magento admin panel.

Go to System > Configuration in your admin panel. Under Shipping Settings > Origin, make sure you have a valid address with a US-based region and 5-digit postal code. If not, go ahead and add your address then click the orange Save Config button.

Magento Shipping Origin

If you have existing sales tax rates, don't worry. We only overwrite zip-based sales tax rates if they reside in one of your nexus states. Your other rates will be remain intact and can still be used.

To review your existing rates, go to Sales > Tax > Manage Tax Zones & Rates.

Magento Tax Rates

For existing sales tax rules don't sweat it either. We attach our zip-based sales tax rates to new or existing rules based on the tax classes you select in our extension. This means that custom rates can still be tied to existing sales tax rules. We've designed our extension to stay out of the way as much as possible.

Magento Tax Rules

Sales Tax Calculations

You’ve reviewed the pre-import checklist and everything looks ready for primetime.

Go to System > Configuration from the main menu. Select Tax under the Sales configuration menu on the left. We’re now ready to configure the TaxJar Magento extension for sales tax calculations.

Magento TaxJar Configuration

Connecting to TaxJar

Before enabling SmartCalcs, you’ll first need to connect to TaxJar from your Magento store. Click the Connect to TaxJar button. This will open a popup asking you to create a new account or log in to TaxJar. Once you’re in, you’ll be shown a confirmation screen to import your API token:

TaxJar Connect Confirmation

Click the Connect button and your token will automatically be saved in Magento. The configuration screen will refresh and show new options:

TaxJar Configuration After Connection

Nexus Addresses

After connecting to TaxJar, you’ll first want to set up the states where your company has nexus. Go to Sales > Tax > Nexus Addresses from the main menu. From there you can add, change, or delete nexus addresses associated with your TaxJar account. There’s also a Sync from TaxJar button to automatically import any of your existing addresses from TaxJar:

Magento Nexus Addresses

We currently support one address per state/region in the US and Canada. For other countries we support one address per country. Make sure you enter a valid address for each state. If you’re unsure where you need to collect sales tax, read our blog post on nexus. We also provide helpful sales tax guides for each state.

When managing your nexus addresses in Magento, all of your changes are automatically synced with TaxJar. Once you’re finished adding all of the states where you have nexus, continue on.

Sales Tax Exemptions

Before enabling SmartCalcs, you may want to assign a TaxJar product tax code to a product tax class in Magento. For example, say you have nexus in New York and sell clothing apparel. Clothing items under $110 are exempt in certain jurisdictions of New York. To set this up in Magento, all we need to do is go to Sales > Tax > Product Tax Classes. Click the Taxable Goods class and you’ll notice a shiny new dropdown for assigning a TaxJar product category:

Magento TaxJar Product Tax Codes

Select Clothing and click Save Class. You now have clothing tax exemptions applied to all products assigned to the Taxable Goods class. This works for new or existing product tax classes. We leave the tax code assigning up to you and it’s completely optional.

For a list of product tax codes SmartCalcs currently supports, check out our category endpoint reference.

Customer Exemptions

If you have customer groups exempt from sales tax, you’ll need to set their corresponding tax classes to exempt for checkout calculations. Go to Sales > Tax > Customer Tax Classes. Click the customer tax class you’d like to exempt and you’ll notice a dropdown:

Magento TaxJar Exempt Customer Tax Classes

Select Yes and click Save Class. Now any customers associated with that customer tax class will be exempt from SmartCalcs. If you’re still seeing sales tax collected, make sure you’re not collecting for this class using our backup rates feature or your own custom tax rates by reviewing your tax rules under Sales > Tax > Manage Tax Rules.

Enabling SmartCalcs

By default Magento uses zip-based rates for calculating sales tax. When you calculate taxes by zip code, you may not be collecting the most accurate amount of sales tax. Zip codes can cover multiple districts, counties, cities, and even states/regions. These jurisdictions can have different rates. In addition, you may have product exemptions depending on what you’re selling and where. There’s limitations when you rely solely on a zip code for figuring out sales tax.

With SmartCalcs enabled you’ll get the most accurate sales tax rates based on the entire shipping address (not just zip code) with built-in support for shipping taxability, sourcing logic, itemized discounts, and product exemptions. Response times are fast (sub-75ms) with 99.99% uptime. Rest assured it won’t interrupt your checkout process.

SmartCalcs Checkout Tax

Set Enabled for Checkout to Yes for live checkout calculations. Click the orange Save Config button. Upon saving, SmartCalcs will be used for calculations instead of Magento’s rate-based tables. However, we can still use those rate-based tables as a fallback just in case.

Magento TaxJar SmartCalcs Config

Backup Sales Tax Rates

We provide a fallback to Magento’s native zip-based rates in case our API becomes unresponsive. While that’s unlikely to happen, it’s always good to have a backup plan. Upon setting Backup Rates to Yes for the first time, you’ll be shown a screen similar to this:

Magento TaxJar Import Success

You’ll notice we imported zip-based sales tax rates for each state where you have nexus. Since we’re downloading thousands of rates into your database at once, this can take several minutes. For destination-based states, TaxJar always returns the highest rate for each zip code to ensure you’re not under-collecting sales tax. For origin-based states we do the same for wildcard rates.

If you decide to add a new nexus state under Sales > Tax > Nexus Addresses and would like to refresh your rates manually, just click the Sync Backup Rates button. It’s that simple. Keep in mind we automatically refresh your backup rates on the first of each month to make sure they’re up to date.

To verify sales tax rates and rules are loaded, go to Sales > Tax > Manage Tax Rules. You should see your imported rates attached to a couple of sales tax rules:

Magento Tax Rules

When turning off nexus for a state, please keep in mind that we never remove tax rates for non-nexus states/regions. This allows our merchants to use their own custom zip-based rates in Magento if needed. After removing a nexus state, you’ll need to manually remove the rates for that state and re-sync your backup rates to refresh the tax rules.

Backup Sales Tax Classes

If you’re taking advantage of our backup rates, make sure you select the appropriate product and customer tax classes under the TaxJar configuration. Usually this means you’ll want to select Taxable Goods and Retail Customer if you haven’t added your own custom classes. Additionally you’ll want to select Shipping for a separate tax rule if you plan to collect sales tax on shipping fees.

Post-Import Configuration

After importing zip-based backup rates, TaxJar’s extension automatically does several things to help prepare you for collecting sales tax using Magento’s native calculations:

Based on your shipping origin state configured under Shipping Settings > Origin, we set the shipping taxability and whether to use origin or destination-based sourcing (e.g. your address of shipping origin or the customer's shipping address).

This means we update two settings under Sales > Tax in your store configuration: Tax Class for Shipping and Tax Calculation Based On.

Magento Tax Shipping Configuration

For most stores, Tax Class for Shipping we'll be set to the default Shipping product tax class and Tax Calculation Based On will be set to Shipping Address. If your store's shipping origin is origin-based (not destination), we'll set it to Shipping Origin.

Keep in mind these settings only affect Magento's native zip-based rates calculations. If you decide to enable SmartCalcs (live checkout calculations), this will only be used as a backup.

Our extension sets the following tax display settings under Sales > Tax to Excluding Tax:

  • Price Display Settings
    • Display Product Prices in Catalog
    • Display Shipping Prices
  • Shopping Cart Display Settings
    • Display Prices
    • Display Subtotal
    • Display Shipping Amount

For most stores, these settings will already be set to Excluding Tax.

Magento Tax Display Configuration

In order to import transactions into your TaxJar account, we need access to your store via Magento's Core API (SOAP/XML-RPC). Our extension automatically creates a new API user and role under System > Web Services. This allows you to automate your sales tax reporting and save hours of time each filing period.

Magento SOAP User

Magento SOAP Role

We'll cover how to finish connecting TaxJar to your Magento store shortly. No data will be shared until you link the account from TaxJar, but you now have everything configured to make it work seamlessly. If you'd prefer to only use TaxJar for sales tax calculations, feel free to remove the API user and role.

If you’re a developer, you may be wondering if TaxJar changes anything with the database after installation. Beyond setting default configuration values and storing extension-related data in the core_config_data table, we only add a single column to tax_class for managing product tax class codes and a tax_nexus table for managing nexus addresses.

Debug Mode

If you need to contact support, enabling debug mode shows you diagnostic information about your Magento store and the TaxJar extension itself. It also prevents the extension from downloading zip-based rates into your store.

To help us help you, take a screenshot of the debug mode message and include it in your support email if you’re having difficulties. Disable it afterwards if you want to continue importing rates.

Magento TaxJar Debug Mode

Sales Tax Reporting

We’re almost done setting up TaxJar with your Magento store. If you’re interested in sales tax reporting and automated filing, proceed!

Make sure your server fulfills Magento’s system requirements. Your PHP memory limit should be at least 256 MB or higher (512 MB recommended). If you’re not sure about the requirements, contact your hosting provider.

Setting Up Sales Tax Reporting

Now that we have calculations up and running, it’s time to import orders into TaxJar.

As mentioned earlier, we use Magento’s Core API to connect to your store from our servers. This is separate from the extension to keep things simple.

To connect to TaxJar, go back to our reporting app at app.taxjar.com. Visit the dashboard or go to Account > Linked Accounts and click the Connect to Magento button.

Connect to Magento from TaxJar

You’ll be asked for your store URL. Make sure you provide the exact domain and make sure to check whether or not you need to include www. If you have SSL enabled (recommended), you should also use https:// instead of http://:

TaxJar to Magento Connection Step 3

Click Save & Connect. If the connection was successful, we’ll automatically begin importing your Magento orders over the last 60 days. If you receive an error message, please review this support article for ways to troubleshoot.


Wrapping Up

You’ve finished setting up TaxJar and Magento! At this point you should be collecting sales tax in your Magento store and importing orders into TaxJar for reporting. From here on out this guide becomes more in-depth to explain what we’re doing behind the scenes. If you’re curious, feel free to read on.


How SmartCalcs Works

Your store seems to be calculating sales tax correctly, but now you might be wondering several things:

  • How many SmartCalcs API calls will be made per order?
  • What happens if SmartCalcs goes down or becomes unresponsive?
  • How does SmartCalcs handle my custom / international rates?
  • Will SmartCalcs work with my other extensions?
  • How often do the zip-based rates refresh?

Our extension only makes live API calls when the order resides in a state where you have nexus. This saves you a lot of API calls and money. Additionally, API calls are cached until the checkout data changes. So if you have a customer repeatedly loading the checkout page without changing their shipping info, your store will not make additional API calls. On average, our SmartCalcs integration will make 2-3 API calls per order in a nexus state. If you allow customers to estimate their shipping and tax on the cart page, that’s included.

API calls are only made under 3 circumstances:

  1. Checkout process for a nexus state
  2. Cart shipping and tax estimate for a nexus state
  3. Refreshing zip-based backup rates in the admin panel

If the order does not reside in a nexus state, SmartCalcs will fall back to Magento’s zip-based rate tables. This gives you the opportunity to use custom or international rates for regions where you may have nexus that TaxJar either doesn’t support yet or you’d rather handle it yourself.

In the unlikely event that SmartCalcs goes down or times out after 10 seconds, Magento’s native calculations will kick in using the backup rates as well.

Our SmartCalcs integration observes the sales_quote_collect_totals_before checkout event and extends the Mage_Tax_Model_Sales_Total_Quote_Tax model only if enabled. If you’re using a third-party checkout extension or something else that may rely on Magento’s internal rate tables (such as multi-warehouse inventory), try out TaxJar’s extension on a test or staging server before deploying to production.

Your zip-based rates will refresh automatically on the first of each month via cron job. You can manually refresh these rates yourself by re-saving the TaxJar extension configuration. Each refresh counts as one API call.

After a customer completes an order using SmartCalcs, our extension will record the sales tax amount and rate by line item in your database. If your store allows multiple currencies, the sales tax will be converted to the customer’s currency:

Magento TaxJar Alternate Currencies

How Reporting Works

After setting up your Magento connection in the TaxJar app, we’ll automatically queue up an import to pull order and refund transactions from your store for the last 60 days. From there we’ll continue to import your store transactions on a nightly basis. If you sign up for a paid TaxJar subscription, you can request a backfill import for older transactions.

To import transactions from your store into TaxJar, we connect to your store using Magento’s Core API over a SOAP/XML-RPC endpoint. Our extension creates an API user and role automatically.

We break up imports into smaller jobs divided by day to minimize load on your server. To speed up the import process, you’ll want to make sure WSDL Cache is enabled under System > Configuration > Services > Magento Core API > General Settings. WS-I Compliance must also be set to No.

Magento Core API Configuration

Orders must be in a complete or closed status for TaxJar to import them. This ensures we only import completed orders and refunds into the system.

International Stores

We support checkout calculations powered by SmartCalcs in more than 30 countries including VAT in the EU and Canada. To perform international calculations, add the countries to your nexus addresses under Sales > Tax > Nexus Addresses. For backup zip-based rates, we currently support the United States since it’s tightly integrated with our reporting app.

With that said, our SmartCalcs integration will automatically fall back to custom zip-based rates in Magento and already supports non-USD currencies. If you need backup rates in other countries you can set up custom tax rules under Sales > Tax > Manage Tax Rules.

Extension Changelog

Curious to see what’s changed with our extension lately? Read on to learn more!

v2.3.1

  • Add manage account and sales tax report buttons to configuration.
  • Create reporting API user and role immediately after connecting to TaxJar.
  • Import TaxJar product categories immediately after connecting to TaxJar.
  • Fix multi-store connection issue with SID param.
  • Fix non-SSL store connection issue.

v2.3.0

  • Exempt specific customer tax classes from SmartCalcs requests.
  • Support product tax codes in Core API salesOrderInfo response.

v2.2.1

  • Support Magento EE gift card tax exemption.
  • Tweak calculation requests to rely directly on line items for upcoming SmartCalcs accuracy check.

v2.2.0

  • Free sales tax calculations for Magento merchants. You must upgrade to this version to receive free calculations at checkout using our new API endpoint.

v2.1.2

  • Fix calculations with associated items in configurable/bundled products.
  • Fix calculations fallback for earlier versions of Magento CE before 1.8.
  • Add tax by line item rather than subtotal to prevent rounding issues.
  • Fix nexus check for international locations.

v2.1.1

  • Fix nexus upgrade script for v2.0.1 users.
  • Purge nexus addresses on disconnect for switching accounts.
  • Package nexus address template form.phtml.

v2.1.0

  • Nexus addresses can now be managed in Magento under Sales > Tax > Nexus Addresses. If upgrading from a previous version and using checkout calculations, make sure you sync your existing addresses from TaxJar or set up a new address. Your addresses will automatically sync with TaxJar when added or changed.
  • International support for SmartCalcs checkout calculations. One nexus address per country outside of US/CA is currently supported for more than 30 countries.
  • Review nexus addresses for missing data and set up observer to report tax configuration issues.
  • Report errors when using AJAX sync backup rate button in the TaxJar configuration.

v2.0.1

  • Separate SmartCalcs shipping tax amount for orders and invoices.
  • Fix display issue after connecting to TaxJar with caching enabled.
  • Minor bug fixes for older versions of PHP and strict standards.

v2.0.0

  • Moved TaxJar configuration to System > Configuration > Tax. This is a breaking change with new configuration fields. If upgrading from a previous version, you’ll need to re-connect to TaxJar and re-enable your settings.
  • Streamlined configuration with focus on SmartCalcs for upcoming free calculations and zip-based rates as a fallback.
  • New “Connect to TaxJar” button for faster onboarding.
  • New select fields for assigning backup tax rules to custom product and customer tax classes.
  • New AJAX sync button for manually refreshing backup rates from TaxJar.
  • Admin notifications tied to our RSS feed for extension updates and news.

v1.6.1

  • Hotfix SmartCalcs integration model casing.
  • Trim shipping origin postal code before making API requests.
  • Minor code cleanup.

v1.6.0

  • SmartCalcs integration at checkout for live sales tax calculations and higher accuracy.
  • Product tax code support for exemptions.
  • Fix rule and rate purging when uninstalling extension.
Start managing your sales tax today. Be up and running in minutes Start Your Free Trial