TaxJar Sales Tax API for Node
npm install taxjarOfficial Node client for Sales Tax API v2. For the API documentation, please visit https://developers.taxjar.com/api/reference/.
Requirements
Installation
Authentication
Usage
Custom Options
Sandbox Environment
Error Handling
Testing
- Node.js v10.0 and later.
``
npm install taxjar
`javascript
// CommonJS Import
const Taxjar = require('taxjar');
// ES6 Import
// Using TypeScript? Pass esModuleInterop in tsconfig.json
// https://www.typescriptlang.org/docs/handbook/compiler-options.html
import Taxjar from 'taxjar';
const client = new Taxjar({
apiKey: process.env.TAXJAR_API_KEY
});
`
_Warning: Never expose your API token in client-side JavaScript. This is insecure and could put your TaxJar account at risk._
You're now ready to use TaxJar! Check out our quickstart guide to get up and running quickly.
categories - List all tax categories
taxForOrder - Calculate sales tax for an order
listOrders - List order transactions
showOrder - Show order transaction
createOrder - Create order transaction
updateOrder - Update order transaction
deleteOrder - Delete order transaction
listRefunds - List refund transactions
showRefund - Show refund transaction
createRefund - Create refund transaction
updateRefund - Update refund transaction
deleteRefund - Delete refund transaction
listCustomers - List customers
showCustomer - Show customer
createCustomer - Create customer
updateCustomer - Update customer
deleteCustomer - Delete customer
ratesForLocation - List tax rates for a location (by zip/postal code)
nexusRegions - List nexus regions
validateAddress - Validate an address
validate - Validate a VAT number
summaryRates - Summarize tax rates for all regions
> The TaxJar API provides product-level tax rules for a subset of product categories. These categories are to be used for products that are either exempt from sales tax in some jurisdictions or are taxed at reduced rates. You need not pass in a product tax code for sales tax calculations on product that is fully taxable. Simply leave that parameter out.
`javascript`
client.categories().then(res => {
res.categories; // Array of categories
});
> Shows the sales tax that should be collected for a given order.
`javascript`
client.taxForOrder({
from_country: 'US',
from_zip: '07001',
from_state: 'NJ',
from_city: 'Avenel',
from_street: '305 W Village Dr',
to_country: 'US',
to_zip: '07446',
to_state: 'NJ',
to_city: 'Ramsey',
to_street: '63 W Main St',
amount: 16.50,
shipping: 1.5,
line_items: [
{
id: '1',
quantity: 1,
product_tax_code: '31000',
unit_price: 15.0,
discount: 0
}
]
}).then(res => {
res.tax; // Tax object
res.tax.amount_to_collect; // Amount to collect
});
> Lists existing order transactions created through the API.
`javascript`
client.listOrders({
from_transaction_date: '2015/05/01',
to_transaction_date: '2015/05/31'
}).then(res => {
res.orders; // Orders object
});
> Shows an existing order transaction created through the API.
`javascript`
client.showOrder('123').then(res => {
res.order; // Order object
});
> Creates a new order transaction.
`javascript`
client.createOrder({
transaction_id: '123',
transaction_date: '2015/05/14',
from_country: 'US',
from_zip: '92093',
from_state: 'CA',
from_city: 'La Jolla',
from_street: '9500 Gilman Drive',
to_country: 'US',
to_zip: '90002',
to_state: 'CA',
to_city: 'Los Angeles',
to_street: '123 Palm Grove Ln',
amount: 17.45,
shipping: 1.5,
sales_tax: 0.95,
line_items: [
{
id: '1',
quantity: 1,
product_identifier: '12-34243-9',
description: 'Fuzzy Widget',
unit_price: 15.0,
discount: 0,
sales_tax: 0.95
}
]
}).then(res => {
res.order; // Order object
});
> Updates an existing order transaction created through the API.
`javascript`
client.updateOrder({
transaction_id: '123',
amount: 17.45,
shipping: 1.5,
line_items: [
{
quantity: 1,
product_identifier: '12-34243-0',
description: 'Heavy Widget',
unit_price: 15.0,
discount: 0.0,
sales_tax: 0.95
}
]
}).then(res => {
res.order; // Order object
});
> Deletes an existing order transaction created through the API.
`javascript`
client.deleteOrder('123').then(res => {
res.order; // Order object
});
> Lists existing refund transactions created through the API.
`javascript`
client.listRefunds({
from_transaction_date: '2015/05/01',
to_transaction_date: '2015/05/31'
}).then(res => {
res.refunds; // Refunds object
});
> Shows an existing refund transaction created through the API.
`javascript`
client.showRefund('123-refund').then(res => {
res.refund; // Refund object
});
> Creates a new refund transaction.
`javascript`
client.createRefund({
transaction_id: '123-refund',
transaction_reference_id: '123',
transaction_date: '2015/05/14',
from_country: 'US',
from_zip: '92093',
from_state: 'CA',
from_city: 'La Jolla',
from_street: '9500 Gilman Drive',
to_country: 'US',
to_zip: '90002',
to_state: 'CA',
to_city: 'Los Angeles',
to_street: '123 Palm Grove Ln',
amount: -17.45,
shipping: -1.5,
sales_tax: -0.95,
line_items: [
{
id: '1',
quantity: 1,
product_identifier: '12-34243-9',
description: 'Fuzzy Widget',
unit_price: -15.0,
discount: -0,
sales_tax: -0.95
}
]
}).then(res => {
res.refund; // Refund object
});
> Updates an existing refund transaction created through the API.
`javascript`
client.updateRefund({
transaction_id: '123-refund',
transaction_reference_id: '123',
amount: -17.95,
shipping: -2.0,
line_items: [
{
id: '1',
quantity: 1,
product_identifier: '12-34243-0',
description: 'Heavy Widget',
unit_price: -15.0,
discount: -0,
sales_tax: -0.95
}
]
}).then(res => {
res.refund; // Refund object
});
> Deletes an existing refund transaction created through the API.
`javascript`
client.deleteRefund('123-refund').then(res => {
res.refund; // Refund object
});
> Lists existing customers created through the API.
`javascript`
client.listCustomers().then(res => {
res.customers; // Customers object
});
> Shows an existing customer created through the API.
`javascript`
client.showCustomer('123').then(res => {
res.customer; // Customer object
});
> Creates a new customer.
`javascript`
client.createCustomer({
customer_id: '123',
exemption_type: 'wholesale',
name: 'Dunder Mifflin Paper Company',
exempt_regions: [
{
country: 'US',
state: 'FL'
},
{
country: 'US',
state: 'PA'
}
],
country: 'US',
state: 'PA',
zip: '18504',
city: 'Scranton',
street: '1725 Slough Avenue'
}).then(res => {
res.customer; // Customer object
});
> Updates an existing customer created through the API.
`javascript`
client.updateCustomer({
customer_id: '123',
exemption_type: 'wholesale',
name: 'Sterling Cooper',
exempt_regions: [
{
country: 'US',
state: 'NY'
}
],
country: 'US',
state: 'NY',
zip: '10010',
city: 'New York',
street: '405 Madison Ave'
}).then(res => {
res.customer; // Customer object
});
> Deletes an existing customer created through the API.
`javascript`
client.deleteCustomer('123').then(res => {
res.customer; // Customer object
});
> Shows the sales tax rates for a given location.
>
> Please note this method only returns the full combined rate for a given location. It does not support nexus determination, sourcing based on a ship from and ship to address, shipping taxability, product exemptions, customer exemptions, or sales tax holidays. We recommend using taxForOrder to accurately calculate sales tax for an order.
`javascript`
client.ratesForLocation('90002').then(res => {
res.rate; // Rate object
});
> Lists existing nexus locations for a TaxJar account.
`javascript`
client.nexusRegions().then(res => {
res.regions; // Array of nexus regions
});
> Validates a customer address and returns back a collection of address matches. Address validation requires a TaxJar Plus subscription.
`javascript`
client.validateAddress({
country: 'US',
state: 'AZ',
zip: '85297',
city: 'Gilbert',
street: '3301 South Greenfield Rd'
}).then(res => {
res.addresses; // Array of address matches
});
> Validates an existing VAT identification number against VIES.
`javascript`
client.validate({
vat: 'FR40303265045'
}).then(res => {
res.validation; // Validation object
});
> Retrieve minimum and average sales tax rates by region as a backup.
>
> This method is useful for periodically pulling down rates to use if the TaxJar API is unavailable. However, it does not support nexus determination, sourcing based on a ship from and ship to address, shipping taxability, product exemptions, customer exemptions, or sales tax holidays. We recommend using taxForOrder to accurately calculate sales tax for an order.
`javascript`
client.summaryRates().then(res => {
res.summary_rates; // Array of summarized rates
});
header with the desired version string.
`javascript
client.setApiConfig('headers', {
'x-api-version': '2020-08-07'
});
`Sandbox Environment
You can easily configure the client to use the TaxJar Sandbox:
javascript
// CommonJS Import
const Taxjar = require('taxjar');// ES6 Import
import Taxjar from 'taxjar';
const client = new Taxjar({
apiKey: process.env.TAXJAR_SANDBOX_API_KEY,
apiUrl: Taxjar.SANDBOX_API_URL
});
`For testing specific error response codes, pass the custom
header:`javascript
client.setApiConfig('headers', {
'X-TJ-Expected-Response': '422'
});
`Error Handling
javascript
client.taxForOrder({
from_country: 'US',
from_zip: '07001',
from_state: 'NJ',
from_city: 'Avenel',
from_street: '305 W Village Dr',
to_country: 'US',
to_zip: '07446',
to_state: 'NJ',
to_city: 'Ramsey',
to_street: '63 W Main St',
amount: 16.50,
shipping: 1.5,
line_items: [
{
id: '1',
quantity: 1,
product_tax_code: '31000',
unit_price: 15.0,
discount: 0,
sales_tax: 0.95
}
]
}).then(res => {
res.tax; // Tax object
res.tax.amount_to_collect; // Amount to collect
}).catch(err => {
err.detail; // Error detail
err.status; // Error status code
});
`In TypeScript, you may want to first check the error's type before handling:
ts
client.taxForOrder(/ ... /)
.catch(err => {
if (err instanceof Taxjar.Error) {
err.detail; // Error detail
err.status; // Error status code
} else {
// handle non-taxjar error
}
});
`Testing
npm test
To validate API methods in the TaxJar sandbox environment, pass the following environment variables:
TAXJAR_API_URL="https://api.sandbox.taxjar.com" \
TAXJAR_API_KEY="9e0cd62a22f451701f29c3bde214" \
npm test