TaxJar API Reference

The TaxJar API provides two endpoints for developers.
By using the API, you accept the terms of the TaxJar user agreement.

We’ve tried to make this simple but let us know if you have any feedback. Email us.

Authorization

In order to use these API, an API Token is required to be passed in the request header.

Get your API Token by signing up

Smart Sales Tax API

The TaxJar Smart Sales Tax API takes the following input:

  • postal code from which you ship (or have nexus)
  • the subtotal amount (without shipping, taxes)
  • shipping charges

The API will return the amount of sales tax and some other helpful variables from our sales tax calculation. The API determines the rate based on country, city and zip-code (including plus 4 information), taking into account whether or not the state in question is origin-based or destination based and whether or not shipping is taxable.

Currently rates for the United States and Canada are supported.

Endpoint

http://api.taxjar.com/sales_tax

Example

Try it

Request

curl 'http://api.taxjar.com/sales_tax?amount=10&shipping=2&to_country=US&to_state=NJ&to_city=Freehold&to_zip=07728&from_country=US&from_state=NJ&from_city=Ramsey&from_zip=07446' -H 'Authorization: Token token="dae79dc5154ccabd7cb169f616d605e7"'

Response

{
              "amount_to_collect" => 0.83,
                           "rate" => 0.083,
                      "has_nexus" => true,
                "freight_taxable" => false,
                     "tax_source" => "origin"
          }

Parameters

Amount Amount of the order, excluding shipping.
Shipping Amount charged for shipping.
From Country 2 Character Country code (US or CA) order when business has nexus.
From State Two letter postal abbreviation for state/province where the order is shipped from. Also if your business has nexus in the ship to state even if shipped from outside of state.
From City City order was shipped from or when business has nexus.
From Zip Zip code order was shipped from or when business has nexus.
To Country 2 Character Country code (US or CA) order was shipped to. (required)
To State State or Province order was shipped to. (required)
To City City order was shipped to.
To Zip Zip code order was shipped to. (required)

Error responses

HTTP statusCause
401Not authorized. Access token is missing or invalid.
400Bad Request. Missing input parameters.
404Not found. State or Zip code likely unknown.
500Internal Server Error. Please contact support@taxjar.com

Example Use Cases

Example 1: As a seller with a single physical nexus in the state of California I will always send my FROM location as my business address and the TO address as the shipping address. I don’t want to manage nexus decisions in my application so I will send all API requests to TaxJar even when the TO address is outside California.

Example 2: I am a seller with one business location in several states (CA, NY, AZ). When I fulfill an order I could ship from any of those states. To make sure my tax calculations are correct I add my business locations to TaxJar. This takes the nexus decision out of my hands. So I can ship FROM California TO Arizona and TaxJar will make sure the proper destination rate is charged since I am shipping from out of state.

Example 3: As a seller with nexus in Quebec, Canada I am expected to charge some level of tax on all sales within Canada. I will want to call the API for every transaction, or at a minimum all transactions within my business country of nexus, Canada.

Example 4: As a marketplace platform we want to provide tax calculation at checkout for many different merchants. We support 1 address per merchant so we will send that address as the FROM address and the customer shipping address in the TO fields for each request along with the item subtotal less discounts as the amount and then the shipping fee separately.

Tax Rate Lookup

The TaxJar Sales Tax Rate API takes location as input and returns the Sales Tax rates for the location. Minimum required is five digit zip. If zip includes plus4 and city is provided, the response will be more accurate. In order to use the API, an API Token is required to be passed in the request header.

Endpoint

http://api.taxjar.com/locations/<zip code>/<city name>

Example

Try it

Request

curl 'http://api.taxjar.com/locations/07446/ramsey' -H 'Authorization: Token token="dae79dc5154ccabd7cb169f616d605e7"'

Response

{
				  "location":{
				    "state":"NJ",
				    "zip":"07446",
				    "state_rate":"0.07",
				    "city":"RAMSEY",
				    "city_rate":"0.0",
				    "county":"BERGEN",
				    "county_rate":"0.0",
				    "combined_district_rate":"0.0",
				    "combined_rate":"0.07"
				  }
				}

What are combined rates?

Combined District Rate Aggregate Rate for all city and county sales tax districts effective at the location. A complete breakdown of these districts is available as well. Please contact support@taxjar.com for more information.
Combined Rate Overall Sale Tax rate which includes the State, County, City and District portions. This is the rate that should be used to determine how much Sales Tax to collect for an order.

Parameters

Zip required
City optional
Country optional for US lookups but required for Canada

Error responses

HTTP statusCause
401Not authorized. Access token is missing or invalid.
400Bad Request. Zip not provided.
404Not found. Five digit zip not recognized.
500Internal Server Error. Please contact support@taxjar.com