cURL Ruby Python PHP Node .NET Java Go
API Guides
© 2024 TaxJar. TaxJar is a trademark of TPS Unlimited, Inc. Privacy Policy & Terms of Service

Quickstart Guides

Using one of our official API clients? Hit the ground running with our quickstart guides:

You’ll learn how to set up the API client, authenticate with TaxJar, and make common requests using our sales tax API such as sales tax calculations and pushing transactions into TaxJar.

Product Exemptions

Mixed Order of Exempt and Non-Exempt Clothing in NY

$ curl https://api.taxjar.com/v2/taxes \
  -H "Authorization: Bearer 9e0cd62a22f451701f29c3bde214" \
  -H "Content-Type: application/json" \
  -d '{
    "to_city": "Mahopac",
    "to_state": "NY",
    "to_zip": "10541",
    "to_country": "US",
    "from_city": "Delmar",
    "from_state": "NY",
    "from_zip": "12054",
    "from_country": "US",
    "amount": 29.94,
    "shipping": 7.99,
    "line_items": [
      {
        "quantity": 1,
        "unit_price": 19.99,
        "product_tax_code": "20010"
      },
      {
        "quantity": 1,
        "unit_price": 9.95,
        "product_tax_code": "20010"
      }
    ]
  }'

Taxability By Line Item

{
  "tax": {
    "order_total_amount": 37.93,
    "shipping": 7.99,
    "taxable_amount": 37.93,
    "amount_to_collect": 1.98,
    "rate": 0.05218,
    "has_nexus": true,
    "freight_taxable": true,
    "tax_source": "destination",
    "breakdown": {
      "taxable_amount": 37.93,
      "tax_collectable": 1.98,
      "combined_tax_rate": 0.05218,
      "state_taxable_amount": 7.99,
      "state_tax_rate": 0.04,
      "state_tax_collectable": 0.32,
      "county_taxable_amount": 37.93,
      "county_tax_rate": 0.04,
      "county_tax_collectable": 1.52,
      "city_taxable_amount": 0.0,
      "city_tax_rate": 0.0,
      "city_tax_collectable": 0.0,
      "special_district_taxable_amount": 37.93,
      "special_tax_rate": 0.00375,
      "special_district_tax_collectable": 0.14,
      "shipping": {
        "taxable_amount": 7.99,
        "tax_collectable": 0.67,
        "combined_tax_rate": 0.08375,
        "state_taxable_amount": 7.99,
        "state_sales_tax_rate": 0.04,
        "state_amount": 0.32,
        "county_taxable_amount": 7.99,
        "county_tax_rate": 0.04,
        "county_amount": 0.32,
        "city_taxable_amount": 0.0,
        "city_tax_rate": 0.0,
        "city_amount": 0.0,
        "special_taxable_amount": 7.99,
        "special_tax_rate": 0.00375,
        "special_district_amount": 0.03
      },
      "line_items": [
        {
          "id": "1",
          "taxable_amount": 19.99,
          "tax_collectable": 0.87,
          "combined_tax_rate": 0.04375,
          "state_taxable_amount": 0.0,
          "state_sales_tax_rate": 0.0,
          "state_amount": 0.0,
          "county_taxable_amount": 19.99,
          "county_tax_rate": 0.04,
          "county_amount": 0.8,
          "city_taxable_amount": 0.0,
          "city_tax_rate": 0.0,
          "city_amount": 0.0,
          "special_district_taxable_amount": 19.99,
          "special_tax_rate": 0.00375,
          "special_district_amount": 0.07
        },
        {
          "id": "2",
          "taxable_amount": 9.95,
          "tax_collectable": 0.44,
          "combined_tax_rate": 0.04375,
          "state_taxable_amount": 0.0,
          "state_sales_tax_rate": 0.0,
          "state_amount": 0.0,
          "county_taxable_amount": 9.95,
          "county_tax_rate": 0.04,
          "county_amount": 0.4,
          "city_taxable_amount": 0.0,
          "city_tax_rate": 0.0,
          "city_amount": 0.0,
          "special_district_taxable_amount": 9.95,
          "special_tax_rate": 0.00375,
          "special_district_amount": 0.04
        }
      ]
    }
  }
}

In many states certain products are either exempted from sales tax, taxed at a lower rate, or even exempted below certain prices and within only certain jurisdictions. To help you make an accurate determination about how an individual item should be taxed, the TaxJar API allows you to submit a product_tax_code parameter with each line_item in an order.

Let’s take one of the most commonly cited examples: clothing items sold in the state of New York that fall below the threshold of $110. Interestingly, these types of items are exempt from the state tax rate, but are only exempt from county taxes in certain jurisdictions. Fortunately, you need not worry about those rules. Simply pass in a value of 20010 in the product_tax_code parameter of a line_item, and we’ll do the work for you.

Mixed Order Example

Here’s an example of an order in NY that contains a mixed order of exempt and non-exempt clothing items. Interestingly, we’ve chosen a destination address in a county where the clothing exemption does not apply (it only applies at the state level).

As you can see in the response, the TaxJar API figures out the taxability by item, by jurisdiction. All you need to do is tell us an item is “Clothing” using product_tax_code 20010.

To obtain the current list of supported product_tax_codes, they are always available via our Categories endpoint.

Additional Reminder

If no product_tax_code is submitted with a line_item, then that item is deemed to be fully taxable. You do not need to send any information to tell TaxJar that something is taxable. It assumes that, unless told otherwise through the existence of a product_tax_code.

Handling Nexus

The very first bit of logic used when calculating sales tax is the notion of nexus. In short, whether or not your business has sufficient presence within a taxing jurisdiction to require you to remit sales tax.

Using the TaxJar API, there are two ways for you let us know if you have nexus for a given order:

  1. If you are calculating tax just for your own business, you can store all of your nexus information within your TaxJar account. Just use the State Settings page to enter all of your business locations. When you make a call to the TaxJar API with your API token, we will look at your nexus information on file and calculate sales tax when appropriate. Of course, our ability to calculate properly will depend on your maintaining an accurate list of nexus locations. To add states and nexus locations, just go to the State Settings page and click the Add State with Nexus button.

  2. If you would rather not load your locations into your TaxJar account or if you are trying to perform calculations for other merchants, you may pass in nexus information with each call to the TaxJar API. At minimum, if you pass in valid values for nexus_country and nexus_state, we can make a proper nexus determination.

No Nexus, Non-Taxable Sale

{
  "tax": {
    "amount_to_collect": 0,
    "freight_taxable": false,
    "has_nexus": false,
    "rate": 0,
    "tax_source": null,
    "taxable_amount": 0
  }
}

Mixed Order with nexus_address Parameters

$ curl https://api.taxjar.com/v2/taxes \
  -H "Authorization: Bearer 9e0cd62a22f451701f29c3bde214" \
  -H "Content-Type: application/json" \
  -d '{
    "to_city": "Mahopac",
    "to_state": "NY",
    "to_zip": "10541",
    "to_country": "US",
    "from_city": "Delmar",
    "from_state": "NY",
    "from_zip": "12054",
    "from_country": "US",
    "amount": 215.30,
    "shipping": 0,
    "line_items": [
      {
        "quantity": 1,
        "unit_price": 150,
        "product_tax_code": "20010"
      },
      {
        "quantity": 3,
        "unit_price": 19.95,
        "shipping": 5.45,
        "product_tax_code": "20010"
      }
    ],
    "nexus_addresses": [
      {
        "city": "Delmar",
        "state": "NY",
        "zip": "12054",
        "country": "US"
      }
    ]
  }'

Nexus Address Example

You have set up your TaxJar account and have an API token, but have no nexus address information on file. Try submitting the same New York clothing article found under Product Exemptions.

You should see a response similar to the one on the right.

TaxJar has no knowledge of your nexus, and because no nexus information was passed into the TaxJar API, we interpret it as a non-taxable sale.

Now, send the same order in, but with the optional nexus_addresses[] parameters filled in.

You should now see the same result as shown in the Product Exemption example.

Important: While nexus_addresses[] parameters are optional, if you do use them, you must at a minimum send in country and state parameters. Otherwise, we can’t return a value.

When to Use from_ Address Information

In general, we recommend always passing in the address information from which an order ships. This gives us what we need to make sourcing determinations in both origin and destination states. If you know that you are shipping within/to a destination state, you may elect not to send from_ address information. In addition, in the absence of from_address parameters, we will look to your State Settings in your TaxJar account, using the address information there. However, we recommend a best practice of always sending from_ address information.

Marketplaces

If you are building or operating a marketplace platform, allowing multiple sellers to list and sell their items through you, there are a few different options.

First, if you are the merchant of record, then you are responsible for collecting and remitting sales tax for all of those sales. In such a case, you would use the TaxJar API to calculate the proper amount of tax to collect, then, if you wish to use TaxJar for reporting and filing, send completed orders to TaxJar using the same API token that is tied to your account.

In most cases that we’ve seen, marketplaces are not acting as the seller of record, so the sales tax responsibilities and liabilities fall to the merchant. However, most marketplaces, as a courtesy, like to provide sales tax calculation services at the point of checkout. If you are building/operating such a marketplace, then you would use your TaxJar account and its API token to make calls to our API, sending in order information and receiving the corresponding sales tax to collect.

Because we won’t know anything about a given merchant when you call the TaxJar API with their order information, you will need to submit additional parameters to get an accurate sales tax rate. For example, we need to know in what jurisdictions the merchant has nexus in order to determine whether an order is even subject to sales tax. For this purpose, we have the nexus_address parameters. Simply pass in a list of addresses with each order to get proper nexus determination. Of course, in order to provide this to the TaxJar API, you will need to have this information stored for each merchant. As such, we recommend storing all merchant business location addresses in your system, so that it is easy to pass in when calculating sales tax.

In Summary

  • If you’re building or operating a marketplace, the TaxJar API can help you calculate sales tax.

  • For most marketplaces where each merchant acts as the seller of record, you will need to submit nexus_address parameters for the merchant in every TaxJar API call.

  • We recommend storing all merchant business location addresses in your system to pass in when calculating sales tax.

In addition to helping you calculate sales tax for your merchants, we also make it very easy to help them file and remit their sales tax to the states. TaxJar’s transaction endpoints allow you to send completed order information to a merchant’s TaxJar account. Simply include the merchant’s TaxJar API token when posting, and those orders will show up in the merchant’s account with a return-ready report breaking out tax owed by jurisdiction. API calls to the Transactions endpoint do not get counted toward your monthly threshold. Merchants who choose to use TaxJar will simply pay us based on the number of transactions we’re processing for them on a monthly basis.

Custom Apps & Carts

While the TaxJar API was originally created as a way for eCommerce marketplaces to provide compliance help for merchants, our transaction endpoints also make it possible to build an integration from any shopping cart, invoicing tool or accounting platform to TaxJar.

You only need two things to make this possible:

  1. A customer’s TaxJar API token (so that you are sending the data to the proper account). This will require some work to collect and store the user submitted token.

  2. Sufficient order detail information for TaxJar to generate accurate return-ready sales tax reports.

Please note that every pushed transaction requires a unique ID string. You can submit both orders and refunds as well as instructions to edit or delete them.

How and when to send these transactions to TaxJar is entirely up to you. Some potential ideas:

  1. If you already provide customers with a reporting interface that allows them to select a date range to view orders within that range, simply add a button that uses the same date range to query and send those orders/refunds.

  2. To enable a more automated solution, allow users to opt-in to regular transaction submissions. You can choose to do this upon saving completed orders to your platform’s database or set up in batches that occur on a regular basis (e.g. nightly).

Avoiding Unnecessary API Calls

Want a simple way to reduce the number of TaxJar API calls you need to make? Compare the delivery address of an order or invoice to the list of nexus_addresses for your business or merchant. If the delivery address falls in a different state than those in which your business (or merchant of sale) has nexus, no sales tax need be collected. Note, this only works for US-based sales.

Furthermore, many carts estimate taxes in the cart or preview pages prior to checkout. You could consider eliminating this estimate or at least delaying it until the shopper is closer to completing the purchase. During checkout make sure you wait to make a request to calculate tax until the shipping address is complete. Many customers use an address validation service to ensure a valid shipping address prior to calling the TaxJar API with the final order totals and shipping from and to addresses.

API Integrations

At TaxJar, we provide official integrations for popular eCommerce platforms such as WooCommerce and Magento. All of our official integrations are built and maintained in-house by eCommerce experts.

We currently provide official integrations for the following platforms:

Magento

Our Magento sales tax extension currently supports Magento 2.0+. The TaxJar API is fully integrated for checkout calculations and zip-based rate imports as a fallback.

NetSuite

Our NetSuite integration requires a TaxJar Professional or higher subscription and your NetSuite account must have SuiteTax enabled.

  • Learn how to install and configure the integration with our NetSuite Guide

WooCommerce

Our WooCommerce plugin is compatible with WooCommerce 2.6+ and WordPress 4.2+.

Certified Integrations

Dozens of certified integrations are available for other popular marketplaces and eCommerce, ERP, POS, accounting, inventory management, and order management platforms as well. These integrations are built and maintained by third-party developers and tested and certified by the TaxJar team. See the full list of integrations built by our partners.

Security

TLS 1.2 Test Snippet

# Run the following command and ensure that your system is using
# cURL version 7.34.0 or higher
curl --version
# Additionally, check that your OpenSSL version is 1.0.1 or higher with
openssl version -a

require 'taxjar'
client = Taxjar::Client.new(api_key: '[YOUR TAXJAR TOKEN]')

begin
  client.categories
  puts 'TLS 1.2 supported, no upgrade required'
rescue OpenSSL::SSL::SSLError
  puts 'TLS 1.2 is not supported, you will need to upgrade'
end

import taxjar
client = taxjar.Client(api_key='[YOUR TAXJAR TOKEN]')

try:
  client.categories()
  print 'TLS 1.2 supported, no upgrade required'
except requests.exceptions.SSLError:
  print 'TLS 1.2 is not supported, you will need to upgrade'

<?php
require __DIR__ . '/vendor/autoload.php';

$client = TaxJar\Client::withApiKey('[YOUR TAXJAR TOKEN]');

try {
  $client->categories();
  echo 'TLS 1.2 supported, no upgrade required'
}
catch (GuzzleHttp\Exception\RequestException $e) {
  echo 'TLS 1.2 not supported, you will need to upgrade'
}
catch (Exception $e) {
  echo 'Unknown error from TaxJar, please try again'
}
?>

const Taxjar = require('taxjar');

const client = new Taxjar({
  apiKey: '[YOUR TAXJAR TOKEN]'
});

client.categories().then(() => {
  console.log('TLS 1.2 supported, no upgrade required');
}).catch(e => {
  if (e.error && e.error.code === 'ECONNRESET') {
    console.log('TLS 1.2 not supported, you will need to upgrade');
  } else {
    console.log('Unknown error from TaxJar, please try again');
  }
});

// If you are using the TaxJar NuGet package and you are targeting
// .NET Framework 4.5, you will need to include the following
// snippet within your application to enable TLS 1.2:

#if NET45
    ServicePointManager.SecurityProtocol = ServicePointManager.SecurityProtocol | SecurityProtocolType.Tls12;
#endif

// For more information on enabling TLS 1.2 support see: https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls

// Check your Java version with `java -version`.
// If your version of Java is v1.8 or above, no change is needed.
// If your version of Java is v1.7, ensure you have v4.0.0
// of taxjar-java installed to enable TLS 1.2 support.

// All versions of Go already support TLS 1.2 by default,
// so you will not need to make any changes.

In order to secure customer data, TLS 1.2 is required for all requests to TaxJar as of July 1, 2020. The TLS protocol is used to encrypt your servers’ communications with TaxJar, so it’s important that you use the latest version. (TLS 1.2 is much more secure than previous versions.)

To test if your server is using TLS 1.2, run the code snippet for the language of your choice:

If you see the message “TLS 1.2 supported, no upgrade required” print, you’re good to go! Otherwise, you will need to upgrade your OpenSSL version:

Linux

If you are using Linux, you’ll need to know which distribution you are on. You can run cat /etc/*-release to find this information.

Ubuntu

  • 12.04 LTS (Precise), you will need to install package updates. You can do this by running sudo apt-get update && sudo apt-get install --only-upgrade openssl, and then restarting your TaxJar application. You may also need to update your libssl. You can update this by running sudo apt-get update && sudo apt-get install --only-upgrade libssl-dev.

  • 10.10 (Maverick), 11.04 (Natty), or 11.10 (Oneiric), you will need to upgrade to at least Ubuntu 12.04 (Precise). The easiest way to do this is to rebuild your server, as upgrading from these non-LTS Ubuntu versions is not supported.

  • 10.04 LTS (Lucid), you will need to upgrade to at least Ubuntu 12.04 (Precise). We recommend rebuilding your server, as the upgrade process is risky.

RedHat Enterprise Linux, or CentOS

  • version 6, you will need to install package updates. You can do this by running sudo yum update openssl libcurl, and restarting your TaxJar application.

  • version 5, you will need to upgrade to at least Red Hat Enterprise Linux 6. We recommend rebuilding your server, as the upgrade process is risky.

Debian

  • Upgrade to at least Debian 7.0 (Wheezy).

Other Linux Variants

  • Ensure that running openssl version gives a version of at least 1.0.1. If it does not, you will need to install package updates, and may need to upgrade to a newer version of your operating system.

OSX

We recommend that you upgrade your OpenSSL version using Homebrew. You can run brew install openssl to install the latest version of OpenSSL on your machine. You may also need to update the version of your language, i.e., Ruby, Python, PHP, Node, C#/.NET, Java, or Go.

Windows

If you are using a Windows machine, your development environment is providing your copy of OpenSSL. You can upgrade this by upgrading your development environment itself, i.e., your installation of Ruby, Python, PHP, Node, C#/.NET, Java, or Go.

cURL Ruby Python PHP Node .NET Java Go
Get API Token Log In

© 2024 TaxJar. TaxJar is a trademark of TPS Unlimited, Inc. Privacy Policy & Terms of Service