Sales Tax API Client for Node
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

TaxJar Sales Tax API for Node NPM Module Build Status Known Vulnerabilities

Official Node client for Sales Tax API v2. For the API documentation, please visit https://developers.taxjar.com/api/reference/.

Requirements

  • Node.js v4.0 and later.

Installation

npm install taxjar

Authentication

// ES5 Import
const Taxjar = require('taxjar');

// ES6/7 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.

Usage

List all tax categories

client.categories().then(res => {
  res.categories; // Array of categories
});

List tax rates for a location (by zip/postal code)

client.ratesForLocation('90002').then(res => {
  res.rate; // Rate object
});

Calculate sales tax for an order

client.taxForOrder({
  from_country: 'US',
  from_zip: '07001',
  from_state: 'NJ',
  to_country: 'US',
  to_zip: '07446',
  to_state: 'NJ',
  amount: 16.50,
  shipping: 1.5,
  line_items: [
    {
      quantity: 1,
      unit_price: 15.0,
      product_tax_code: 31000
    }
  ]
}).then(res => {
  res.tax; // Tax object
  res.tax.amount_to_collect; // Amount to collect
});

List order transactions

client.listOrders({
  from_transaction_date: '2015/05/01',
  to_transaction_date: '2015/05/31'
}).then(res => {
  res.orders; // Orders object
});

Show order transaction

client.showOrder('123').then(res => {
  res.order; // Order object
});

Create order transaction

client.createOrder({
  transaction_id: '123',
  transaction_date: '2015/05/14',
  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: [
    {
      quantity: 1,
      product_identifier: '12-34243-9',
      description: 'Fuzzy Widget',
      unit_price: 15.0,
      sales_tax: 0.95
    }
  ]
}).then(res => {
  res.order; // Order object
});

Update order transaction

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
});

Delete order transaction

client.deleteOrder('123').then(res => {
  res.order; // Order object
});

List refund transactions

client.listRefunds({
  from_transaction_date: '2015/05/01',
  to_transaction_date: '2015/05/31'
}).then(res => {
  res.refunds; // Refunds object
});

Show refund transaction

client.showRefund('321').then(res => {
  res.refund; // Refund object
});

Create refund transaction

client.createRefund({
  transaction_id: '123',
  transaction_date: '2015/05/14',
  transaction_reference_id: '123',
  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: [
    {
      quantity: 1,
      product_identifier: '12-34243-9',
      description: 'Fuzzy Widget',
      unit_price: 15.0,
      sales_tax: 0.95
    }
  ]
}).then(res => {
  res.refund; // Refund object
});

Update refund transaction

client.updateRefund({
  transaction_id: '123',
  amount: 17.95,
  shipping: 2.0,
  line_items: [
    {
      quantity: 1,
      product_identifier: '12-34243-0',
      description: 'Heavy Widget',
      unit_price: 15.0,
      sales_tax: 0.95
    }
  ]
}).then(res => {
  res.refund; // Refund object
});

Delete refund transaction

client.deleteRefund('123').then(res => {
  res.refund; // Refund object
});

List customers

client.listCustomers().then(res => {
  res.customers; // Customers object
});

Show customer

client.showCustomer('123').then(res => {
  res.customer; // Customer object
});

Create customer

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
});

Update customer

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
});

Delete customer

client.deleteCustomer('123').then(res => {
  res.customer; // Customer object
});

List nexus regions

client.nexusRegions().then(res => {
  res.regions; // Array of nexus regions
});

Validate a VAT number

client.validate({
  vat: 'FR40303265045'
}).then(res => {
  res.validation; // Validation object
});

Summarize tax rates for all regions

client.summaryRates().then(res => {
  res.summary_rates; // Array of summarized rates
});

Sandbox Environment

You can easily configure the client to use the TaxJar Sandbox:

// ES5 Import
const Taxjar = require('taxjar');

// ES6/7 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 X-TJ-Expected-Response header:

client.setApiConfig('headers', {
  'X-TJ-Expected-Response' => '422'
});

Error Handling

client.taxForOrder({
  from_country: 'US',
  from_zip: '07001',
  from_state: 'NJ',
  to_country: 'US',
  to_zip: '07446',
  to_state: 'NJ',
  amount: 16.50,
  shipping: 1.5,
  line_items: [
    {
      quantity: 1,
      unit_price: 15.0,
      product_tax_code: 31000
    }
  ]
}).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
});

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