TaxJar API Reference

The TaxJar API provides multiple 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.

Examples of the Authorization header are shown in the examples for each endpoint.

Get your API Token by signing up

Smart Sales Tax API: Standard

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

https://api.taxjar.com/sales_tax

Multistate Nexus

The API uses all addresses added in the TaxJar account associated with your API key to determine nexus and rate information. This means that any requests will be processed against all states where you have indiciated that your business has nexus. To manage and view these addresses, click here.

Examples

Try it
Postman REST Client

Via curl

Simple Request with Order Total
curl -X GET -H "Authorization: Token token="your_api_key_here"" "https://api.taxjar.com/sales_tax?amount=28.93&from_city=Ramsey&from_state=NJ&from_zip=07446&shipping=5.45&to_city=Ramsey&to_state=NJ&to_zip=07446"
Simple Request that Uses Addresses from a TaxJar Account
curl -X GET -H "Authorization: Token token="your_api_key_here"" "https://api.taxjar.com/sales_tax?amount=28.93&shipping=5.45&to_city=Ramsey&to_state=NJ&to_zip=07446"
Request that Specifies Canada
curl -X GET -H "Authorization: Token token="your_api_key_here"" "https://api.taxjar.com/sales_tax?amount=28.93&from_city=AIYANSH&from_state=BC&from_zip=V0J1A0&from_country=CA&shipping=5.45&to_city=AIYANSH&to_state=BC&to_zip=V0J1A0&to_country=CA"

Responses

We will respond to your request with a JSON string that looks like the following:

          {
            "taxable_amount": 28.92,
            "amount_to_collect": 0.83,
            "rate": 0.083,
            "has_nexus": true,
            "freight_taxable": false,
            "tax_source": "origin"
          }

Occassionally, you may encounter messages in your JSON reponse that will be useful for debugging your application. The messages are appended to the response as:

          {
            "taxable_amount": 28.92,
            "amount_to_collect": 0.83,
            "rate": 0.083,
            "has_nexus": true,
            "freight_taxable": false,
            "tax_source": "origin",
            "msg": "Order amount of 28.93 does not match item totals of 28.92"
          }

HTTP Status Codes

We also use the following HTTP status codes to notify your application about the status of its request:

HTTP Status Code Description
400 Your request was rejected most likely because parameters are missing or your request is malformed. Check your request and try again.
404 The location parameters provided in the request are most likely invalid or missing. Check that the location parameters provided are correct.
200 The request was successful and an accompanying authoritative response was generated.
500 The API has encountered an internal error. Email support@taxjar.com with details about what happened when the error was received or what may have been done to cause the error.
401 Check that your request includes the Authorization header that matches this format: Token token="your_api_key_here". The Smart Sales Tax API uses a HTTP Authorization header for authentication. Resolve possible billing issues at your account’s plan page. Check that your API key is valid and matches the API key listed on your account’s API access page.

Parameters

Parameter Parameter Name Description
amount Amount Amount of the order, excluding shipping. For requests that include line items, this amount must equal the subtotal of the line items submitted. If it does not equal the line items the API will still process the request but the API will let developers know via a 203 HTTP status, an HTTP Warning header, and message in the JSON response that it used a different total to calculate the amount to collect, including the subtotals it used.

Default is 0.0. Example valid values are 130.04, 130.0, 130.
shipping Shipping Amount charged for shipping. If the business has discounts applied to shipping, submit only the already discounted shipping amount to the API unless the business charges tax on shipping regardless of any discounts applied to shipping amounts.

Default is 0.0. Example valid values are 5.95, 5.0, 5.
from_country From Country The country from which the business is shipping. Valid values are either US or CA for the United States or Canada respectively.

Default is US. Only valid values are US and CA.
from_state From State Two letter postal abbreviation for the state or province where the order is shipped from. If your business has nexus in the state to which your business is shipping and the state is not associated with an address stored in the TaxJar account associated with the API key then the developer will need to add this parameter to the request. This parameter is only optional if the developer wants to only use addresses stored the TaxJar account associated with the API key.

Defaults to any state in the associated TaxJar account that has nexus with the to_state parameter. If no addresses are associated with the TaxJar account, this value will default to null and the amount to collect will be 0.0. If the parameter is not provided by the developer, this value will default to null. Example valid values are BC, CA, NC.
from_city From City The city from which the business will be shipping. This parameter is optional.

Defaults to any city in the associated TaxJar account that has nexus with the to_state parameter. If no addresses are associated with the TaxJar account, this value will default to null. If the parameter is not provided by the developer, this value will default to null. Example valid values are Irvine, NEW YORK, asheville.
from_zip From Zip The zip or postal code from which the business will be shipping.

Defaults to any zip or postal code in the associated TaxJar account that has nexus with the to_state parameter. If no addresses are associated with the TaxJar account, this value will default to null. If the parameter is not provided by the developer, this value will default to null. Example valid values are 28801, V0J 1A0, 10154-4199.
to_country To Country The country to which the business is shipping. Valid values are either US or CA for the United States or Canada respectively.

Default is US. Only valid values are US and CA.
to_state To State The state to which the business is shipping. This is a required parameter.

There is no default value for the parameter. Example valid values are BC, CA, NC.
to_city To City The city to which the business is shipping. This parameter is optional.

Default is null. Example valid values are Irvine, NEW YORK, asheville.
to_zip To Zip The zip or postal code to which the business is shipping. This is a required parameter.

There is no default value for the parameter. Example valid values are 28803, V0J 1A0, 10154-4199.

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.

Smart Sales Tax API: Enhanced

TaxJar’s Enhanced Smart Sales Tax API provides additional detailed tax information for enterprise customers, such as support for line items and product taxability. In order to access the Enhanced API, your TaxJar account will need to be set by TaxJar’s sales department. Please contact support@taxjar.com to request access to the Enhanced API.

Endpoint

https://api.taxjar.com/v1/sales_tax

Line Item Support

The Sales Tax API supports calculating the amount of taxes due given line item amounts, quantities and discounts. Submitting line items is an optional feature and order level taxability is used by default if you choose not to provide line items in your request. To use line item taxes, you must also submit the order amount and shipping information at the order level. Finally, line items need to be uniquely identified in your request and you may use any type of identifier (for example, as an integer or string) as long as each discount, amount, and quantity share the same identifier.

Line items use the following format when submitting them in your request:

line_items[unique_key][unit_price]=5
line_items[unique_key][quantity]=3
line_items[unique_key][discount]=1.00

Where unit_price is the item’s unit price, quantity is the number of that item being purchased, and discount is the amount discounted off the line item’s total amount.

Discounts

If you have a discount at the order level, you will need to submit each line item with the appropriate discount amount for that line on the order. For example, given two line items on an order:

line_items[tshirt][unit_price]=5
line_items[tshirt][quantity]=3
line_items[tshirt][discount]=1.00
line_items[dress][unit_price]=5
line_items[dress][quantity]=3

The tshirt line item will have a discount of $1.00 applied to the total for the tshirt line item of $15.00. Since the discount is applied to the line item’s total, the grand total for the line item becomes $14.00. The second line item dress is not affected by the discount.

Quantities

You may use either whole or partial quantity values for line items. For example, 1, 1.0, and 4.5 are all valid values for the quantity value on a line item.

Optional Parameters

The quantity and discount values may be omitted on line items. If you do not submit a quantity, we assume a quantity of exactly one. If you choose to not submit a discount, we assume no discounts are applicable to the line item.

Line Item Product Taxability Support

The Enhanced version of the Smart Sales Tax API support the ability to pass in product codes on a per-line-item basis in order to determine the correct per-item tax. It supports exempt items, items with specific price thresholds, and items taxed at reduced rates.

Line items with product tax codes use the following format when submitting them in your request:

line_items[unique_key][product_tax_code]=21000
line_items[unique_key][unit_price]=5
line_items[unique_key][quantity]=3
line_items[unique_key][discount]=1.00

The product_tax_code is one of our supported Tax Categories. The product_tax_code value can be omitted if you don’t know the categorization or if the item should always be treated as taxable.

Supporting multiple merchants with multiple nexus addresses

For Marketplaces and other e-commerce platforms that support multiple merchants, the Enhanced API provides the ability to pass in merchant-specific nexus information. For example, if you have a merchant with locations in 3 different states, you can pass in the address information for each of those states, thereby allowing TaxJar to detect nexus and provide the appropriate tax rates.

This does require that you, the e-commerce platform, enable merchants to store their multi-location nexus information on your platform.

Nexus addresses use the following format when submitting them in your request:

nexus_addresses[unique_key][country]=US
nexus_addresses[unique_key][state]=MO
nexus_addresses[unique_key][city]=Lake Ozark
nexus_addresses[unique_key][zip]=65049
nexus_addresses[unique_key][street]=1123 Main
          

City, zip and street are optional parameters, though may be necessary if you fail to pass in a ship-from address with the order.

The nexus_addresses parameters are optional and need only be used for merchants who do not have their own TaxJar accounts which might contain their nexus information.

Supporting VAT and International sales

TaxJar currently provides support for Canada and European Union VAT calculations, including support for reduced and super­reduced rates based on product tax codes. Simply pass in the country code using the ISO 3166­1 alpha­2 standard for both from and to addresses:

from_country=DE
to_country=FR
          

Sourcing for EU VAT

By default, all EU orders are treated as being sourced in the country of origin. There are two exceptions:

  1. For certain product categories (e.g. 30070, Software as a Service”,) sourcing will change to destination per EU VAT rules
  2. If you pass in a nexus_address parameter that matches the country of delivery, we will change sourcing to be destination_based (e.g. nexus_addresses[unique_key][country]=FR).

Note: TaxJar does not support EU sales thresholds to determine changes in sourcing (because it it hard for us to know total sales across countries for a single API call. Hence, we allow you, the developer/platform, to pass in a nexus_address parameter to voluntarily change sourcing (a supported EU VAT option.)

Parameters

Parameter Parameter Name Description
line_items Line Items
unit_price Unit Price Individual item price
quantity Quantity How many of the items were sold
discount Discount Discount to be applied before tax to the item subtotal (unit_price*qty)
product_tax_code Product Tax Code Tax code to classify the item into a tax category, or 99999 for always exempt.
nexus_addresses Nexus Addresses
country Required
state Required
city optional
zip Recommend to provide postal code for all addresses
street optional

Example requests via curl

Request with mixed order of line items with different tax rules at state and county level
curl --globoff -X GET -H "Authorization: Token token="your_api_key_here"" "https://api.taxjar.com/v1/sales_tax?amount=215.30&from_city=Delmar&from_state=NY&from_zip=12054&line_items[awesomepants][quantity]=1&line_items[awesomepants][unit_price]=150&line_items[awesomepants][product_tax_code]=20010&line_items[tshirt][quantity]=3&line_items[tshirt][unit_price]=19.95&line_items[tshirt][product_tax_code]=20010&shipping=5.45&to_city=Mahopac&to_state=NY&to_zip=10541"

Example Query Parameters

{
            to_city: 'City Name', to_zip: '07446',
            to_state: 'NJ', to_country: 'US',
            from_zip:'07446', from_state: 'NJ', from_country: 'US',
            amount: 34.37, shipping: 5.45,
            to_state: state,
            line_items: {
                "clothing_item" => {
                  unit_price: 2.99,
                  quantity: 5,
                  discount: 4.00,
                  product_tax_code: 20010
                },
                "1202" => {
                  unit_price: 5.99,
                  quantity: 3
                }
              },
            nexus_addresses: {
              "MyAddress" => {
                country: 'US',
                state: 'MO',
                city: 'Lake Ozark',
                zip: '65049',
                street: '1123 Main'
              },
              "CA-1" => {
                country: 'US',
                state: 'CA',
                city: 'The Hills',
                zip: '90210-1234',
                street: '1123 Main'
              },
              "NJ-1" => {
                country: 'US',
                state: 'NJ',
                city: 'Ramsey',
                zip: '07446-1234',
                street: '1123 Main'
              }
            }
          }

Responses

The Enhanced Smart Sales Tax API provides complete detail for each order call, with sales tax amounts at the order and item level. In addition, we respond with taxable sales and sales tax collected at each jurisdiction level.

              {
              "order_total_amount": 215.3,
              "amount_to_collect": 15.63,
              "has_nexus": true,
              "freight_taxable": true,
              "tax_source": "destination",
              "breakdown": {
                "shipping": {
                  "state_amount": 0.22,
                  "state_sales_tax_rate": 0.04,
                  "county_amount": 0.22,
                  "county_tax_rate": 0.04,
                  "city_amount": 0,
                  "city_tax_rate": 0,
                  "special_district_amount": 0.02,
                  "special_tax_rate": 0.00375
                  },
                "items": {
                  "awesomepants": {
                    "state_taxable_amount": 150,
                    "state_sales_tax_rate": 0.04,
                    "county_taxable_amount": 150,
                    "county_tax_rate": 0.04,
                    "city_taxable_amount": 0,
                    "city_tax_rate": 0,
                    "special_district_taxable_amount": 150,
                    "special_tax_rate": 0.00375
                    },
                  "tshirt": {
                    "state_taxable_amount": 0,
                    "state_sales_tax_rate": 0,
                    "county_taxable_amount": 59.85,
                    "county_tax_rate": 0.04,
                    "city_taxable_amount": 0,
                    "city_tax_rate": 0,
                    "special_district_taxable_amount": 59.85,
                    "special_tax_rate": 0.00375
                    }
                },
                "state_taxable_amount": 155.45,
                "state_tax_collectable": 6.22,
                "county_taxable_amount": 215.3,
                "county_tax_collectable": 8.61,
                "city_taxable_amount": 0,
                "city_tax_collectable": 0,
                "special_district_taxable_amount": 215.3,
                "special_district_tax_collectable": 0.8
                }
              }

HTTP Status Codes

The Enhanced Smart Sales Tax API has an additional status code for line_items:

HTTP Status Code Description
203 For line item requests, this status code indicates that the order amount provided and the shipping plus item level totals calculated by the API do not match. Check that the amount is correct and that the line_items provided in the request are correct. For detailing information, check the accompanying HTTP warning header or msg parameter appended to the API’s response.

Tax Category

The TaxJar Product Tax Category API returns a list of support codes to use to identify line items for the Sales Tax API calculation. In order to use the API, an API Token is required to be passed in the request header.

Endpoint

https://api.taxjar.com/tax_categories

Supported Tax Categories

Product Tax Code Description
99999 Other Exempt, item is to be treated as always exempt.
20010 Clothing; normal clothing for human use.
40030 Food & Groceries; uncooked or unheated food for human consumption
51020 Prescription drugs; for human use
51010 Non-prescription drugs; for human use
31000 Digital Goods
30070 Software as a Service

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

https://api.taxjar.com/locations/<zip code>/<city name>?country=country_code

Example

Try it

Request

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

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 United States (US) lookups but required for Canada (CA)

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