taxjar / taxjar-python

Sales Tax API Client for Python 2.6+ / Python 3+

TaxJar Sales Tax API for Python

Official Python client for the TaxJar API. For the API documentation, please visit https://developers.taxjar.com/api.

• This wrapper supports 100% of the TaxJar API Version 2
• Data returned from API calls are mapped to Python objects

---

Supported Python Versions
Package Dependencies
Getting Started
Authentication
Usage
Custom Options
Sandbox Environment
Tests
Contributing

---

Supported Python Versions

Python 2.7+ or Python 3.4+

Package Dependencies

TaxJar uses the following dependencies as specified in setup.py:

• Requests HTTP library for making RESTful requests to the TaxJar API.
• jsonobject Simple JSON object mapping for Python.

Getting Started

We recommend installing TaxJar via PyPI using pip. Before authenticating, get your API key from TaxJar. Run the following command in your terminal:

pip install taxjar

Authentication

To authenticate with our API, import the taxjar package and instantiate a new API client:

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

You're now ready to use TaxJar! Check out our quickstart guide to get up and running quickly.

Usage

categories - List all tax categories
tax_for_order - Calculate sales tax for an order
list_orders - List order transactions
show_order - Show order transaction
create_order - Create order transaction
update_order - Update order transaction
delete_order - Delete order transaction
list_refunds - List refund transactions
show_refund - Show refund transaction
create_refund - Create refund transaction
update_refund - Update refund transaction
delete_refund - Delete refund transaction
list_customers - List customers
show_customer - Show customer
create_customer - Create customer
update_customer - Update customer
delete_customer - Delete customer
rates_for_location - List tax rates for a location (by zip/postal code)
nexus_regions - List nexus regions
validate_address - Validate an address
validate - Validate a VAT number
summary_rates - Summarize tax rates for all regions

---

List all tax categories (API docs)

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.

Definition

client.categories

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.categories()

Example Response

[
  <TaxJarCategory {
    'product_tax_code': '31000',
    'name': 'Digital Goods',
    'description': 'Digital products transferred electronically, meaning obtained by the purchaser by means other than tangible storage media.'
  }>,
  <TaxJarCategory {
    'product_tax_code': '20010',
    'name': 'Clothing',
    'description': ' All human wearing apparel suitable for general use'
  }>,
  <TaxJarCategory {
    'product_tax_code': '51010',
    'name': 'Non-Prescription',
    'description': 'Drugs for human use without a prescription'
  }>
]

Calculate sales tax for an order (API docs)

Shows the sales tax that should be collected for a given order.

Definition

client.tax_for_order

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.tax_for_order({
  'from_country': 'US',
  'from_zip': '94025',
  'from_state': 'CA',
  'from_city': 'Menlo Park',
  'from_street': '2825 Sand Hill Rd',
  'to_country': 'US',
  'to_zip': '94303',
  'to_state': 'CA',
  'to_city': 'Palo Alto',
  'to_street': '5230 Newell Road',
  'amount': 267.9,
  'shipping': 0,
  'nexus_addresses': [{
    'country': 'US',
    'state': 'CA'
  }],
  'line_items': [{
    'id': '1',
    'quantity': 1,
    'product_tax_code': '19005',
    'unit_price': 535.8,
    'discount': 267.9
  }]
})

Example Response

<TaxJarTax {
    'taxable_amount': 0,
    'tax_source': 'destination',
    'shipping': 0,
    'rate': 0,
    'order_total_amount': 267.9,
    'jurisdictions': <TaxJarJurisdictions {
        'state': 'CA',
        'county': 'SAN MATEO',
        'country': 'US',
        'city': 'EAST PALO ALTO'
    }>,
    'has_nexus': True,
    'freight_taxable': False,
    'breakdown': <TaxJarBreakdown {
        'taxable_amount': 0,
        'tax_collectable': 0,
        'state_taxable_amount': 0,
        'state_tax_rate': 0,
        'state_tax_collectable': 0,
        'special_tax_rate': 0,
        'special_district_taxable_amount': 0,
        'special_district_tax_collectable': 0,
        'line_items': [<TaxJarBreakdownLineItem {
            'taxable_amount': 0,
            'tax_collectable': 0,
            'state_taxable_amount': 0,
            'state_sales_tax_rate': 0,
            'state_amount': 0,
            'special_tax_rate': 0,
            'special_district_taxable_amount': 0,
            'special_district_amount': 0,
            'id': '1',
            'county_taxable_amount': 0,
            'county_tax_rate': 0,
            'county_amount': 0,
            'combined_tax_rate': 0,
            'city_taxable_amount': 0,
            'city_tax_rate': 0,
            'city_amount': 0
        }>],
        'county_taxable_amount': 0,
        'county_tax_rate': 0,
        'county_tax_collectable': 0,
        'combined_tax_rate': 0,
        'county_tax_collectable': 0,
        'combined_tax_rate': 0,
        'city_taxable_amount': 0,
        'city_tax_rate': 0,
        'city_tax_collectable': 0
    }>,
    'amount_to_collect': 0
}>

List order transactions (API docs)

Lists existing order transactions created through the API.

Definition

client.list_orders

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.list_orders({
  'from_transaction_date': '2016/01/01',
  'to_transaction_date': '2017/01/01'
})

Example Response

['20', '21', '22']

Show order transaction (API docs)

Shows an existing order transaction created through the API.

Definition

client.show_order

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.show_order('123')

Example Response

<TaxJarOrder {
    'transaction_id': '123',
    'user_id': 11836,
    'transaction_date': '2015-05-14T00:00:00Z',
    'transaction_reference_id': None,
    'from_country': 'US',
    'from_zip': '93107',
    'from_state': 'CA',
    'from_city': 'SANTA BARBARA',
    'from_street': '1281 State St',
    'to_country': 'US',
    'to_zip': '90002',
    'to_state': 'CA',
    'to_city': 'LOS ANGELES',
    'to_street': '123 Palm Grove Ln',
    'amount': 17,
    'shipping': 2,
    'sales_tax': '0.95',
    'line_items': [<TaxJarLineItem {
        'id': '1',
        'quantity': 1,
        'product_identifier': '12-34243-0',
        'product_tax_code': None,
        'description': 'Heavy Widget',
        'unit_price': 15,
        'discount': 0,
        'sales_tax': 0.95
    }>]
}>

Create order transaction (API docs)

Creates a new order transaction.

Definition

client.create_order

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.create_order({
    'transaction_id': '123',
    'transaction_date': '2015/05/15',
    'from_country': 'US',
    'from_zip': '94025',
    'from_state': 'CA',
    'from_city': 'Menlo Park',
    'from_street': '2825 Sand Hill Rd',
    'to_country': 'US',
    'to_zip': '94303',
    'to_state': 'CA',
    'to_city': 'Palo Alto',
    'to_street': '5230 Newell Road',
    'amount': 267.9,
    'shipping': 0,
    'sales_tax': 0,
    'line_items': [{
        'id: '1',
        'quantity': 1,
        'description': 'Legal Services',
        'product_tax_code': '19005',
        'unit_price': 535.8,
        'discount': 267.9,
        'sales_tax': 0
    }]
})

Example Response

<TaxJarOrder {
    'transaction_id': '123',
    'user_id': 11836,
    'provider': 'api',
    'transaction_date': '2015-05-15T00:00:00Z',
    'transaction_reference_id': None,
    'customer_id': None,
    'exemption_type': None,
    'from_country': 'US',
    'from_zip': '94025',
    'from_state': 'CA',
    'from_city': 'MENLO PARK,
    'from_street': '2825 Sand Hill Rd',
    'to_country': 'US',
    'to_zip': '94303',
    'to_state': 'CA',
    'to_city': 'PALO ALTO',
    'to_street': '5230 Newell Road',
    'amount': 267.9,
    'shipping': 0,
    'sales_tax': 0,
    'line_items': [<TaxJarLineItem {
        'id': '1',
        'quantity': 1
        'product_identifier': None,
        'product_tax_code': '19005',
        'description': 'Legal Services',
        'unit_price': 535.8,
        'discount': 267.9,
        'sales_tax': 0
    }>]
}>

Update order transaction (API docs)

Updates an existing order transaction created through the API.

Definition

client.update_order

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.update_order('123', {
    'amount': 283.6,
    'shipping': 5,
    'sales_tax': 1.04,
    'line_items': [
        {
            'id': '1',
            'quantity': 1,
            'description': 'Legal Services',
            'product_tax_code': '19005',
            'unit_price': 535.8,
            'discount': 267.9,
            'sales_tax': 0
        },
        {
            'id': '2',
            'quantity': 2,
            'description': 'Hoberman Switch Pitch',
            'unit_price': 10.7,
            'discount': 10.7,
            'sales_tax': 1.04
        }
    ]
})

Example Response

<TaxJarOrder {
    'transaction_id': '123',
    'user_id': 11836,
    'provider': 'api',
    'transaction_date': '2015-05-15T00:00:00Z',
    'transaction_reference_id': None,
    'customer_id': None,
    'exemption_type': None,
    'from_country': 'US',
    'from_zip': '94025',
    'from_city': 'MENLO PARK',
    'from_street': '2825 Sand Hill Rd',
    'to_country': 'US',
    'to_zip': '94303',
    'to_state': 'CA',
    'to_city': 'PALO ALTO',
    'to_street': '5230 Newell Road',
    'amount': 283.6,
    'shipping': 5,
    'sales_tax': 1.04,
    'line_items': [
        <TaxJarLineItem {
            'id': '1',
            'quantity': 1,
            'product_identifier': None,
            'product_tax_code': '19005',
            'description': 'Legal Services',
            'unit_price': 535.8,
            'discount': 267.9,
            'sales_tax': 0
        }>,
        <TaxJarLineItem {
            'id': '2',
            'quantity': 2,
            'product_identifier': None,
            'product_tax_code': None,
            'description': 'Hoberman Switch Pitch',
            'unit_price': 10.7,
            'discount': 10.7,
            'sales_tax': 1.04
        }>
    ]
}>

Delete order transaction (API docs)

Deletes an existing order transaction created through the API.

Definition

client.delete_order

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.delete_order('123')

Example Response

<TaxJarOrder {
  'transaction_id': '123',
  'user_id': 11836,
  'provider': 'api',
  'transaction_date': None,
  'transaction_reference_id': None,
  'customer_id': None,
  'exemption_type': None,
  'from_country': None,
  'from_zip': None,
  'from_state': None,
  'from_city': None,
  'from_street': None,
  'to_country': None,
  'to_zip': None,
  'to_state': None
  'to_city': None,
  'to_street': None,
  'amount': None,
  'shipping': None,
  'sales_tax': None,
  'line_items': []
}>

List refund transactions (API docs)

Lists existing refund transactions created through the API.

Definition

client.list_refunds

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.list_refunds({
  'from_transaction_date': '2015/05/01',
  'to_transaction_date': '2015/05/31'
})

Example Response

['20-refund', '21-refund', '22-refund']

Show refund transaction (API docs)

Shows an existing refund transaction created through the API.

Definition

client.show_refund

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.show_refund('20-refund')

Example Response

<TaxJarRefund {
    'transaction_id': '20-refund',
    'user_id': 11836,
    'provider': 'api',
    'transaction_date': '2015-05-15T00:00:00Z',
    'transaction_reference_id': '20',
    'customer_id': None,
    'exemption_type': None,
    'from_country': 'US',
    'from_zip': '93107',
    'from_state': 'CA',
    'from_city': 'SANTA BARBARA',
    'from_street': '1218 State St',
    'to_country': 'US',
    'to_zip': '90002',
    'to_state': 'CA',
    'to_city': 'LOS ANGELES',
    'to_street': '123 Palm Grove Ln',
    'amount': -17,
    'shipping': -2,
    'sales_tax': -0.95,
    'line_items': [<TaxJarLineItem {
        'id': '1',
        'quantity': 1,
        'product_identifier': '12-34243-0',
        'product_tax_code': None,
        'description': 'Heavy Widget',
        'unit_price': -15,
        'discount': 0,
        'sales_tax': -0.95,
    }>]
}>

Create refund transaction (API docs)

Creates a new refund transaction.

Definition

client.create_refund

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.create_refund({
    'transaction_id': '123-refund',
    'transaction_reference_id': '123',
    'transaction_date': '2015-05-15',
    'from_country': 'US',
    'from_zip': '94025',
    'from_state': 'CA',
    'from_city': 'Menlo Park',
    'from_street': '2825 Sand Hill Rd',
    'to_country': 'US',
    'to_zip': '94303',
    'to_state': 'CA',
    'to_city': 'Palo Alto',
    'to_street': '5230 Newell Road',
    'amount': -5.35,
    'shipping': -0,
    'sales_tax': -0.52,
    'line_items': [
        {
            'id': '1',
            'quantity': 1,
            'description': 'Legal Services',
            'product_tax_code': '19005',
            'unit_price': -0,
            'discount': -0,
            'sales_tax': -0
        },
        {
            'id': '2',
            'quantity': 1,
            'description': 'Hoberman Switch Pitch',
            'unit_price': -0,
            'discount': -5.35,
            'sales_tax': -0.52
        }
    ]
})

Example Response

<TaxJarRefund {
    'transaction_id': '123-refund',
    'user_id': 11836,
    'provider': 'api',
    'transaction_date': '2015-05-15T00:00:00Z',
    'transaction_reference_id': '123',
    'customer_id': None,
    'exemption_type': None,
    'from_country': 'US',
    'from_zip': '94025',
    'from_state': 'CA',
    'from_city': 'MENLO PARK',
    'from_street': '2825 Sand Hill Rd',
    'to_country': 'US',
    'to_zip': '94303',
    'to_state': 'CA',
    'to_city': 'PALO ALTO',
    'to_street': '5230 Newell Road',
    'amount': -5.35,
    'shipping': -0,
    'sales_tax': -0.52,
    'line_items': [
        <TaxJarLineItem {
            'id': '1',
            'quantity': 1,
            'product_identifier': None,
            'product_tax_code': '19005',
            'description': 'Legal Services',
            'unit_price': 0,
            'discount': 0,
            'sales_tax': 0
        }>,
        <TaxJarLineItem {
            'id': '2',
            'quantity': 1,
            'product_identifier': None,
            'product_tax_code': None,
            'description': 'Hoberman Switch Pitch',
            'unit_price': 0,
            'discount': -5.35,
            'sales_tax': -0.52
        }>
    ]
}>

Update refund transaction (API docs)

Updates an existing refund transaction created through the API.

Definition

client.update_refund

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.update_refund('123-refund', {
  'transaction_reference_id': '123',
  'amount': -10.35,
  'shipping': -5,
})

Example Response

<TaxJarRefund {
    'transaction_id': '123-refund',
    'user_id': 11836,
    'provider': 'api',
    'transaction_date': '2015-05-15T00:00:00Z',
    'transaction_reference_id': '123',
    'customer_id': None,
    'exemption_type': None,
    'from_country': 'US',
    'from_zip': '94025',
    'from_state': 'CA',
    'from_city': 'MENLO PARK',
    'from_street': '2825 Sand Hill Rd',
    'to_country': 'US',
    'to_zip': '94303',
    'to_state': 'CA',
    'to_city': 'PALO ALTO',
    'to_street': '5230 Newell Road',
    'amount': -10.35,
    'shipping': -5,
    'sales_tax': 0,
    'line_items': [
        <TaxJarLineItem {
            'id': '1',
            'quantity': 1,
            'product_identifier': None,
            'product_tax_code': '19005',
            'description': 'Legal Services',
            'unit_price': 0,
            'discount': 0,
            'sales_tax': 0
        }>,
        <TaxJarLineItem {
            'id': '2',
            'quantity': 1,
            'product_identifier': None,
            'product_tax_code': None,
            'description': 'Hoberman Switch Pitch',
            'unit_price': 0,
            'discount': -5.35,
            'sales_tax': -0.52
        }>
    ]
}>

Delete refund transaction (API docs)

Deletes an existing refund transaction created through the API.

Definition

client.delete_refund

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.delete_refund('123-refund')

Example Response

<TaxJarRefund {
  'transaction_id': '123-refund',
  'user_id': 11836,
  'provider': 'api',
  'transaction_date': None,
  'transaction_reference_id': None,
  'customer_id': None,
  'exemption_type': None,
  'from_country': None,
  'from_zip': None,
  'from_state': None,
  'from_city': None,
  'from_street': None,
  'to_country': None,
  'to_zip': None,
  'to_state': None,
  'to_city': None,
  'to_street': None,
  'amount': None,
  'shipping': None,
  'sales_tax': None,
  'line_items': []
}>

List customers (API docs)

Lists existing customers created through the API.

Definition

client.list_customers

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.list_customers()

Example Response

['123', '124', '125']

Show customer (API docs)

Shows an existing customer created through the API.

Definition

client.show_customer

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.show_customer('123')

Example Response

<TaxJarCustomer {
  'customer_id': '123',
  'exemption_type': 'wholesale',
  'exempt_regions': [<TaxJarExemptRegion {
    'country': 'US',
    'state': 'FL'
  }>, <TaxJarExemptRegion {
    'country': 'US',
    'state': 'PA'
  }>],
  'name': 'Dunder Mifflin Paper Company',
  'country': 'US',
  'state': 'PA',
  'zip': '18504',
  'city': 'Scranton',
  'street': '1725 Slough Avenue'
}>

Create customer (API docs)

Creates a new customer.

Definition

client.create_customer

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.create_customer({
  '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'
})

Example Response

<TaxJarCustomer {
  'customer_id': '123',
  'exemption_type': 'wholesale',
  'exempt_regions': [<TaxJarExemptRegion {
    'country': 'US',
    'state': 'FL'
  }>, <TaxJarExemptRegion {
    'country': 'US',
    'state': 'PA'
  }>],
  'name': 'Dunder Mifflin Paper Company',
  'country': 'US',
  'state': 'PA',
  'zip': '18504',
  'city': 'Scranton',
  'street': '1725 Slough Avenue'
}>

Update customer (API docs)

Updates an existing customer created through the API.

Definition

client.update_customer

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.update_customer('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'
})

Example Response

<TaxJarCustomer {
  'customer_id': '123',
  'exemption_type': 'wholesale',
  'exempt_regions': [<TaxJarExemptRegion {
    'country': 'US',
    'state': 'NY'
  }>],
  'name': 'Sterling Cooper',
  'country': 'US',
  'state': 'NY',
  'zip': '10010',
  'city': 'New York',
  'street': '405 Madison Ave'
}>

Delete customer (API docs)

Deletes an existing customer created through the API.

Definition

client.delete_customer

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.delete_customer('123')

Example Response

<TaxJarCustomer {
  'customer_id': '123',
  'exemption_type': 'wholesale',
  'exempt_regions': [<TaxJarExemptRegion {
    'country': 'US',
    'state': 'FL'
  }>, <TaxJarExemptRegion {
    'country': 'US',
    'state': 'PA'
  }>],
  'name': 'Dunder Mifflin Paper Company',
  'country': 'US',
  'state': 'PA',
  'zip': '18504',
  'city': 'Scranton',
  'street': '1725 Slough Avenue'
}>

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

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 tax_for_order to accurately calculate sales tax for an order.

Definition

client.rates_for_location

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

# United States (ZIP+4)
rates = client.rates_for_location('90404-3370')

# United States (ZIP w/ Optional Params)
rates = client.rates_for_location('90404', {
  'city': 'SANTA MONICA',
  'country': 'US'
})

# International Examples (Requires City and Country)
rates = client.rates_for_location('V5K0A1', {
  'city': 'VANCOUVER',
  'country': 'CA'
})

rates = client.rates_for_location('00150', {
  'city': 'HELSINKI',
  'country': 'FI'
})

Example Response

<TaxJarRate {
  'city': 'SANTA MONICA',
  'zip': '90404',
  'combined_district_rate': 0.025,
  'state_rate': 0.0625,
  'city_rate': 0,
  'county': 'LOS ANGELES',
  'state': 'CA',
  'combined_rate': 0.0975,
  'county_rate': 0.01,
  'freight_taxable': False
}>

List nexus regions (API docs)

Lists existing nexus locations for a TaxJar account.

Definition

client.nexus_regions

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

nexus_regions = client.nexus_regions()

Example Response

[
  <TaxJarRegion {
    'country_code': 'US',
    'country': 'United States',
    'region_code': 'CA',
    'region': 'California'
  }>,
  <TaxJarRegion {
    'country_code': 'US',
    'country': 'United States',
    'region_code': 'NY',
    'region': 'New York'
  }>,
  <TaxJarRegion {
    'country_code': 'US',
    'country': 'United States',
    'region_code': 'WA',
    'region': 'Washington'
  }>
]

Validate an address (API docs)

Validates a customer address and returns back a collection of address matches. Address validation requires a TaxJar Plus subscription.

Definition

client.validate_address

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.validate_address({
    'country': 'US',
    'state': 'AZ',
    'zip': '85297',
    'city': 'Gilbert',
    'street': '3301 South Greenfield Rd'
})

Example Response

[
    <TaxJarAddress {
        'zip': '85297-2176',
        'street': '3301 S Greenfield Rd',
        'state': 'AZ',
        'country': 'US',
        'city': 'Gilbert'
    }>
]

Validate a VAT number (API docs)

Validates an existing VAT identification number against VIES.

Definition

client.validate

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.validate({
  'vat': 'FR40303265045'
})

Example Response

<TaxJarValidation {
  'valid': True,
  'exists': True,
  'vies_available': True,
  'vies_response': <TaxJarViesResponse {
    'country_code': 'FR',
    'vat_number': '40303265045',
    'request_date': '2016-02-10',
    'valid': True,
    'name': 'SA SODIMAS',
    'address': "11 RUE AMPERE\n26600 PONT DE L ISERE"
  }>
}>

Summarize tax rates for all regions (API docs)

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 tax_for_order to accurately calculate sales tax for an order.

Definition

client.summary_rates

Example Request

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78')

client.summary_rates()

Example Response

[
  <TaxJarSummaryRate {
    'average_rate': <TaxJarAverageRate {
      'rate': 0.0827,
      'label': 'Tax'
    }>,
    'region_code': 'CA',
    'minimum_rate': <TaxJarMinimumRate {
      'rate': 0.065,
      'label': 'State Tax'
    }>,
    'country': 'US',
    'region': 'California',
    'country_code': 'US'
  }>,
  <TaxJarSummaryRate {
    'average_rate': <TaxJarAverageRate {
      'rate': 0.12,
      'label': 'PST'
    }>,
    'region_code': 'BC',
    'minimum_rate': <TaxJarMinimumRate {
      'rate': 0.05,
      'label': 'GST'
    }>,
    'country': 'Canada',
    'region': 'British Columbia',
    'country_code': 'CA'
  }>,
  <TaxJarSummaryRate {
    'average_rate': <TaxJarAverageRate {
      'rate': 0.2,
      'label': 'VAT'
    }>,
    'region_code': None,
    'minimum_rate': <TaxJarMinimumRate {
      'rate': 0.2,
      'label': 'VAT'
    }>,
    'country': 'United Kingdom',
    'region': None,
    'country_code': 'UK'
  }>
]

Custom Options

Pass additional parameters when instantiating the client for the following options:

Timeouts

Set request timeout in seconds (default is 5 seconds):

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78', options={'timeout':30})

Sandbox Environment

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

import taxjar
client = taxjar.Client(api_key='48ceecccc8af930bd02597aec0f84a78', api_url='https://api.sandbox.taxjar.com')

For testing specific error response codes, pass the custom X-TJ-Expected-Response header:

client.set_api_config('headers', {
    'X-TJ-Expected-Response': '422'
})

Tests

A unittest test suite is available to ensure API functionality:

$ python -m unittest discover tests

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new pull request

taxjar-python's Issues

JSONDecodeError when calling tax_for_order

There have been 2 brief occasions in the past week where we've received JSONDecodeErrors when calling the tax_for_order endpoint:

  File "taxjar/client.py", line 43, in tax_for_order
    return self.responder(request)
  File "taxjar/response.py", line 7, in from_request
    return TaxJarResponse().data_from_request(request)
  File "taxjar/response.py", line 10, in data_from_request
    response = request.json()
  File "requests/models.py", line 910, in json
    return complexjson.loads(self.text, **kwargs)
  File "json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
  File "json/decoder.py", line 337, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
  File "json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Both occasions were very brief (under 45 seconds) so it's not been possible to reproduce the issue. It seems similar to #9. It could be that the API is returning non-JSON data in some situations.

`caniusepython3` don't see taxjar library

Here is what I see in console output.

>>> caniusepython3 -r requirements.txt

Finding and checking dependencies ...
[ERROR] Failed to get external data for https://www.red-dove.com/pypi/projects/T/taxjar/project.json: HTTP Error 404: Not Found
Traceback (most recent call last):
  File "~/venv3/lib/python3.6/site-packages/distlib/util.py", line 913, in _get_external_data
    resp = urlopen(url)
  File "/usr/lib/python3.6/urllib/request.py", line 223, in urlopen
    return opener.open(url, data, timeout)
  File "/usr/lib/python3.6/urllib/request.py", line 532, in open
    response = meth(req, response)
  File "/usr/lib/python3.6/urllib/request.py", line 642, in http_response
    'http', request, response, code, msg, hdrs)
  File "/usr/lib/python3.6/urllib/request.py", line 570, in error
    return self._call_chain(*args)
  File "/usr/lib/python3.6/urllib/request.py", line 504, in _call_chain
    result = func(*args)
  File "/usr/lib/python3.6/urllib/request.py", line 650, in http_error_default
    raise HTTPError(req.full_url, code, msg, hdrs, fp)
urllib.error.HTTPError: HTTP Error 404: Not Found
[WARNING] taxjar not found

I know, that in documentation you shown that python 3+ is supporting but still this may help.

Exclude Empty Attributes from Responses

Currently jsonobject includes unused attributes set to None in API responses. For example, an EU /v2/taxes calculation will return empty Canada attributes.

We may need to fork jsonobject and provide our own package which excludes empty attributes by default. There's a PR open for this in the original repo.

taxjar.exceptions.TaxJarResponseError: 422 Unprocessable Entity on client.create_order

Python 3.9 Support: Incompatible dependency `jsonobject`

There is no immediate Python 3.9 support planned for jsonobject library.
dimagi/jsonobject#176

Is there a possibility to replace jsonobject in the future? The library looks like it hasn't been updated since python 3.6.

EDIT:

jsonobject==0.9.9 should be compatible with python 3.9 now.

Cannot install on Python 3.10

Since jsonobject can't be compiled and installed on Python 3.10, this package can't be installed neither. ERPNext depends on this library, so it can't be used on Python 3.10, too 😃
Do you consider using Pydantic instead of jsonobject for your data models?

Can't run on Windows - module 'os' has no attribute 'uname'

Hi
I've tried to run the API client on Windows 10 and looks like it's not supported. Could you please add Window implementation too?

File "C:\Programs\Python\Python36\lib\site-packages\taxjar\client.py", line 173, in _get_user_agent
platform = ' '.join(os.uname())
AttributeError: module 'os' has no attribute 'uname'

Thank you

getting JSONDecodeError when Too Many Requests error

I'm getting an unexpected JSONDecodeError when making too many requests:

  File "taxjar/client.py", line 34, in rates_for_location
    return self.responder(request)
  File "taxjar/response.py", line 7, in from_request
    return TaxJarResponse().data_from_request(request)
  File "taxjar/response.py", line 10, in data_from_request
    response = request.json()
  File "requests/models.py", line 896, in json
    return complexjson.loads(self.text, **kwargs)
  File "json/__init__.py", line 319, in loads
    return _default_decoder.decode(s)
  File "json/decoder.py", line 342, in decode
    raise JSONDecodeError("Extra data", s, end) 

Unexpected ValueError exception raised from inside the library when address is wrong

  File "/srv/<clipped>tax.py", line 243, in tax
    tax_info = client.tax_for_order(payload)
  File "/home/vagrant/venv/nauman/lib/python2.7/site-packages/taxjar/client.py", line 28, in tax_for_order
    return self.responder(request)
  File "/home/vagrant/venv/nauman/lib/python2.7/site-packages/taxjar/response.py", line 7, in from_request
    return TaxJarResponse().data_from_request(request)
  File "/home/vagrant/venv/nauman/lib/python2.7/site-packages/taxjar/response.py", line 12, in data_from_request
    (type_name, values), = response.items()
ValueError: too many values to unpack

https://github.com/taxjar/taxjar-python/blob/master/taxjar/response.py#L12

There appears to be an unexpected exception being raised from with-in the library. While it was the client sending bad data (wrong state for city in the to address fields), having the library throw one of the expected exceptions and providing the proper error message is what we would've expected.

Encountered error while trying to install package. jsonobject

Windows 10, using pip to install, I see this:

Microsoft Windows [Version 10.0.19043.1706]
(c) Microsoft Corporation. All rights reserved.

C:\WINDOWS\system32>pip install taxjar
Collecting taxjar
  Using cached taxjar-2.0.0-py3-none-any.whl
Requirement already satisfied: requests>=2.13.0 in c:\users\jarad\appdata\roaming\python\python37\site-packages (from taxjar) (2.25.1)
Collecting jsonobject>=0.9.10
  Using cached jsonobject-2.0.0.tar.gz (402 kB)
  Preparing metadata (setup.py) ... done
Requirement already satisfied: six in c:\python37\lib\site-packages (from jsonobject>=0.9.10->taxjar) (1.14.0)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in c:\users\jarad\appdata\roaming\python\python37\site-packages (from requests>=2.13.0->taxjar) (1.25.11)
Requirement already satisfied: certifi>=2017.4.17 in c:\users\jarad\appdata\roaming\python\python37\site-packages (from requests>=2.13.0->taxjar) (2020.12.5)
Requirement already satisfied: idna<3,>=2.5 in c:\users\jarad\appdata\roaming\python\python37\site-packages (from requests>=2.13.0->taxjar) (2.10)
Requirement already satisfied: chardet<5,>=3.0.2 in c:\users\jarad\appdata\roaming\python\python37\site-packages (from requests>=2.13.0->taxjar) (4.0.0)
Building wheels for collected packages: jsonobject
  Building wheel for jsonobject (setup.py) ... error
  error: subprocess-exited-with-error

  × python setup.py bdist_wheel did not run successfully.
  │ exit code: 1
  ╰─> [23 lines of output]
      Warning: 'classifiers' should be a list, got type 'tuple'
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build\lib.win-amd64-3.7
      creating build\lib.win-amd64-3.7\jsonobject
      copying jsonobject\exceptions.py -> build\lib.win-amd64-3.7\jsonobject
      copying jsonobject\__init__.py -> build\lib.win-amd64-3.7\jsonobject
      running build_ext
      building 'jsonobject.api' extension
      creating build\temp.win-amd64-3.7
      creating build\temp.win-amd64-3.7\Release
      creating build\temp.win-amd64-3.7\Release\jsonobject
      C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\BIN\x86_amd64\cl.exe /c /nologo /Ox /W3 /GL /DNDEBUG /MD -Ic:\python37\include -Ic:\python37\include "-IC:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\INCLUDE" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\ucrt" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\shared" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\um" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\winrt" /Tcjsonobject/api.c /Fobuild\temp.win-amd64-3.7\Release\jsonobject/api.obj
      api.c
      C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\BIN\x86_amd64\link.exe /nologo /INCREMENTAL:NO /LTCG /DLL /MANIFEST:EMBED,ID=2 /MANIFESTUAC:NO /LIBPATH:c:\python37\libs /LIBPATH:c:\python37\PCbuild\amd64 "/LIBPATH:C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\LIB\amd64" "/LIBPATH:C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\ucrt\x64" "/LIBPATH:C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\um\x64" /EXPORT:PyInit_api build\temp.win-amd64-3.7\Release\jsonobject/api.obj /OUT:build\lib.win-amd64-3.7\jsonobject\api.cp37-win_amd64.pyd /IMPLIB:build\temp.win-amd64-3.7\Release\jsonobject\api.cp37-win_amd64.lib
      api.obj : warning LNK4197: export 'PyInit_api' specified multiple times; using first specification
         Creating library build\temp.win-amd64-3.7\Release\jsonobject\api.cp37-win_amd64.lib and object build\temp.win-amd64-3.7\Release\jsonobject\api.cp37-win_amd64.exp
      Generating code
      Finished generating code
      LINK : fatal error LNK1158: cannot run 'rc.exe'
      error: command 'C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\VC\\BIN\\x86_amd64\\link.exe' failed with exit status 1158
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for jsonobject
  Running setup.py clean for jsonobject
Failed to build jsonobject
Installing collected packages: jsonobject, taxjar
  Running setup.py install for jsonobject ... error
  error: subprocess-exited-with-error

  × Running setup.py install for jsonobject did not run successfully.
  │ exit code: 1
  ╰─> [23 lines of output]
      Warning: 'classifiers' should be a list, got type 'tuple'
      running install
      running build
      running build_py
      creating build
      creating build\lib.win-amd64-3.7
      creating build\lib.win-amd64-3.7\jsonobject
      copying jsonobject\exceptions.py -> build\lib.win-amd64-3.7\jsonobject
      copying jsonobject\__init__.py -> build\lib.win-amd64-3.7\jsonobject
      running build_ext
      building 'jsonobject.api' extension
      creating build\temp.win-amd64-3.7
      creating build\temp.win-amd64-3.7\Release
      creating build\temp.win-amd64-3.7\Release\jsonobject
      C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\BIN\x86_amd64\cl.exe /c /nologo /Ox /W3 /GL /DNDEBUG /MD -Ic:\python37\include -Ic:\python37\include "-IC:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\INCLUDE" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\ucrt" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\shared" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\um" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\winrt" /Tcjsonobject/api.c /Fobuild\temp.win-amd64-3.7\Release\jsonobject/api.obj
      api.c
      C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\BIN\x86_amd64\link.exe /nologo /INCREMENTAL:NO /LTCG /DLL /MANIFEST:EMBED,ID=2 /MANIFESTUAC:NO /LIBPATH:c:\python37\libs /LIBPATH:c:\python37\PCbuild\amd64 "/LIBPATH:C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\LIB\amd64" "/LIBPATH:C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\ucrt\x64" "/LIBPATH:C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\um\x64" /EXPORT:PyInit_api build\temp.win-amd64-3.7\Release\jsonobject/api.obj /OUT:build\lib.win-amd64-3.7\jsonobject\api.cp37-win_amd64.pyd /IMPLIB:build\temp.win-amd64-3.7\Release\jsonobject\api.cp37-win_amd64.lib
      api.obj : warning LNK4197: export 'PyInit_api' specified multiple times; using first specification
         Creating library build\temp.win-amd64-3.7\Release\jsonobject\api.cp37-win_amd64.lib and object build\temp.win-amd64-3.7\Release\jsonobject\api.cp37-win_amd64.exp
      Generating code
      Finished generating code
      LINK : fatal error LNK1158: cannot run 'rc.exe'
      error: command 'C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\VC\\BIN\\x86_amd64\\link.exe' failed with exit status 1158
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: legacy-install-failure

× Encountered error while trying to install package.
╰─> jsonobject

note: This is an issue with the package mentioned above, not pip.
hint: See above for output from the failure.

Need to pass customer_id as parameter when update customer from API to taxjar

Definition: Need to pass customer_id as parameter when update customer from API to taxjar

Explanation: As per the syntax to update customer, it's giving error as response (TypeError: update_customer() missing 1 required positional argument: 'customer_deets'). So i have analyse issue and found that we need to pass customer_id with values to update customer like order/refund update. But in syntax , not defined to pass customer_id as i have read in doc and developer API guide tool also (https://developers.taxjar.com/api/reference/?python#put-update-a-customer).

Steps To Reproduce:

1. Create any customer:
   Example: https://developers.taxjar.com/api/reference/?python#post-create-a-customer
2. Now check that customer created to Taxjar to verify
   Example: https://developers.taxjar.com/api/reference/?python#get-show-a-customer
3. Now change any detail of customer and update customer using given syntax in example link
   Example: https://developers.taxjar.com/api/reference/?python#put-update-a-customer

Solution: Need to pass customer_id in first paramter like order or refund update process.
Example: client.update_customer('123', {'state': 'AR', 'name': 'Sterling Cooper', 'exemption_type': 'other', 'street': '3404 Edgewood Road ', 'country': 'US', 'zip': '72401', 'city': 'Jonesboro', 'customer_id': '123'})

Please find the attached screenshots for more details

I hope it will clear to understand. Also it will helpful to improve workflow and API documantation