TaxJar Sales Tax API for Ruby
A Ruby interface to the TaxJar Sales Tax API. TaxJar makes sales tax filing easier for online sellers and merchants. See local jurisdictional tax reports, get payment reminders, and more. You can use our API to access TaxJar API endpoints, which can get information on sales tax rates, categories or upload transactions.
- This wrapper supports 100% of SmartCalcs v2
- Data returned from API calls are mapped to Ruby objects
Supported Ruby Versions
Ruby 2.0 or greater
Gem Dependencies
Installing this gem also bundles the following dependencies:
- http - Fast Ruby HTTP client with a chainable API and full streaming support.
- addressable - Replacement for the URI implementation that is part of Ruby's standard library. It more closely conforms to the relevant RFCs and adds support for IRIs and URI templates.
- memoizable - Memoize method return values.
- model_attribute - Type casted attributes for non-ActiveRecord models. Forked to handle floats and more types.
Installation
Add this line to your application's Gemfile:
gem 'taxjar-ruby', require: 'taxjar'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install taxjar-ruby
Authentication
Generate an API token from TaxJar. Copy and paste your API token when instantiating a new client:
require 'taxjar'
client = Taxjar::Client.new(api_key: 'YOUR_API_TOKEN')
You're now ready to use TaxJar! Check out our quickstart guide to get up and running quickly.
Usage
List all tax categories
Definition
client.categories
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.categories
Example Response
[
#<Taxjar::Category:0x00000a @attrs={
:name => 'Digital Goods',
:product_tax_code => 31000,
:description => 'Digital products transferred electronically.'
}>,
#<Taxjar::Category:0x00000a @attrs={
:name => 'Clothing',
:product_tax_code => 20010,
:description => 'All human wearing apparel suitable for general use'
}>,
#<Taxjar::Category:0x00000a @attrs={
:name => 'Non-Prescription',
:product_tax_code => 51010,
:description => 'Drugs for human use without a prescription'
}>
]
List tax rates for a location (by zip/postal code)
Definition
client.rates_for_location
Example Request
require 'taxjar'
client = Taxjar::Client.new(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
#<Taxjar::Rate:0x00000a @attrs={
:zip => '90002',
:state => 'CA',
:state_rate => 0.065,
:county => 'LOS ANGELES',
:county_rate => 0.01,
:city => 'WATTS',
:city_rate => 0,
:combined_district_rate => 0.015,
:combined_rate => 0.09,
:freight_taxable => false
}>
#<Taxjar::Rate:0x00000a @attrs={
:zip => 'V5K0A1',
:city => 'Vancouver',
:state => 'BC',
:country => 'CA',
:combined_rate => 0.12,
:freight_taxable => true
}>
#<Taxjar::Rate:0x00000a @attrs={
:country => 'FI',
:name => 'Finland',
:standard_rate => 0.24,
:reduced_rate => nil,
:super_reduced_rate => nil,
:parking_rate => nil,
:distance_sale_threshold => nil,
:freight_taxable => true
}>
Calculate Sales tax for an order
Definition
client.tax_for_order
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.tax_for_order({
:to_country => 'US',
:to_zip => '90002',
:to_city => 'Los Angeles',
:to_state => 'CA',
:from_country => 'US',
:from_zip => '92093',
:from_city => 'San Diego',
:amount => 15,
:shipping => 1.5,
:nexus_addresses => [{:address_id => 1,
:country => 'US',
:zip => '93101',
:state => 'CA',
:city => 'Santa Barbara',
:street => '1218 State St.'}],
:line_items => [{:quantity => 1,
:unit_price => 15,
:product_tax_code => 20010}]
})
Example Response
#<Taxjar::Tax:0x00000a @attrs={
:order_total_amount => 16.5,
:amount_to_collect => 1.35,
:has_nexus => true,
:freight_taxable => false,
:tax_source => 'destination',
:jurisdictions => #<Taxjar::Jurisdictions:0x00000a @attrs={
:country => 'US',
:state => 'CA',
:county => 'LOS ANGELES',
:city => 'LOS ANGELES'
}>,
:breakdown => #<Taxjar::Breakdown:0x00000a @attrs={
:state_taxable_amount => 15,
:state_tax_collectable => 0.98,
:county_taxable_amount => 15,
:county_tax_collectable => 0.15,
:city_taxable_amount => 0,
:city_tax_collectable => 0,
:special_district_taxable_amount => 15,
:special_district_tax_collectable => 0.22,
:line_items => [
#<Taxjar::BreakdownLineItem:0x00000a @attrs={
:id => '1',
:state_taxable_amount => 15,
:state_sales_tax_rate => 0.065,
:county_taxable_amount => 15,
:county_tax_rate => 0.01,
:city_taxable_amount => 0,
:city_tax_rate => 0,
:special_district_taxable_amount => 15,
:special_tax_rate => 0.015
}>
]
}>
}>
List order transactions
Definition
client.list_orders
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.list_orders({:from_transaction_date => '2014/01/01',
:to_transaction_date => '2015/05/30'})
Example Response
['20', '21', '22']
Show order transaction
Definition
client.show_order
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.show_order('123')
Example Response
#<Taxjar::Order:0x00000a @attrs={
:transaction_id => '123',
:user_id => 11836,
:transaction_date => '2015-05-14T00:00:00Z',
:transaction_reference_id => nil,
: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 => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-0',
:product_tax_code => nil,
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
Create order transaction
Definition
client.create_order
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
order = client.create_order({
:transaction_id => '123',
:transaction_date => '2015/05/14',
:from_state => 'CA',
:from_city => 'Santa Barbara',
:from_street => '1218 State St',
:from_country => 'US',
:from_zip => '93101',
:to_country => 'US',
:to_state => 'CA',
:to_city => 'Los Angeles',
:to_street => '123 Palm Grove Ln',
:to_zip => '90002',
:amount => 16.5,
:shipping => 1.5,
:sales_tax => 0.95,
:line_items => [{:quantity => 1,
:product_identifier => '12-34243-9',
:description => 'Fuzzy Widget',
:unit_price => 15,
:sales_tax => 0.95}]
})
Example Response
#<Taxjar::Order:0x00000a @attrs={
:transaction_id => '20',
:user_id => 11836,
:transaction_date => '2015-05-14T00:00:00Z',
:transaction_reference_id => nil,
:from_country => 'US',
:from_zip => 93101,
: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 => 16.5,
:shipping => 1.5,
:sales_tax => 0.95,
:line_items => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-9',
:product_tax_code => nil,
:description => 'Fuzzy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
Update order transaction
Definition
client.update_order
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
order = client.update_order({
:transaction_id => '123',
:amount => 17,
:shipping => 2,
:line_items => [{:quantity => 1,
:product_identifier => '12-34243-0',
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95}]
})
Example Response
#<Taxjar::Order:0x00000a @attrs={
:transaction_id => '123',
:user_id => 11836,
:transaction_date => '2015-05-14T00:00:00Z',
:transaction_reference_id => nil,
:from_country => 'US',
:from_zip => 93101,
: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 => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-0',
:product_tax_code => nil,
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
Delete order transaction
Definition
client.delete_order
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.delete_order('123')
Example Response
#<Taxjar::Order:0x00000a @attrs={
:transaction_id => '123',
:user_id => 11836,
:transaction_date => '2015-05-14T00:00:00Z',
:transaction_reference_id => nil,
:from_country => 'US',
:from_zip => 93101,
: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 => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-0',
:product_tax_code => nil,
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
Listing refund transactions
Definition
client.list_refunds
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.list_refunds({:from_transaction_date => '2014/01/01',
:to_transaction_date => '2015/05/30'})
Example Response
['203', '204', '205']
Show refund transaction
Definition
client.show_refund
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.show_refund('321')
Example Response
#<Taxjar::Refund:0x00000a @attrs={
:transaction_id => '321',
:user_id => 11836,
:transaction_date => '2015-06-14T00:00:00Z',
:transaction_reference_id => 123,
: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 => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-0',
:product_tax_code => nil,
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
Create refund transaction
Definition
client.create_refund
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
refund = client.create_refund({
:transaction_id => '321',
:transaction_date => '2015/05/14',
:transaction_reference_id => '123',
: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 => 16.5,
:shipping => 1.5,
:sales_tax => 0.95,
:line_items => [{:quantity => 1,
:product_identifier => '12-34243-9',
:description => 'Fuzzy Widget',
:unit_price => 15,
:sales_tax => 0.95}]
})
Example Response
#<Taxjar::Refund:0x00000a @attrs={
:transaction_id => '321',
:user_id => 11836,
:transaction_date => '2015-06-14T00:00:00Z',
:transaction_reference_id => '123',
: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 => 16.5,
:shipping => 1.5,
:sales_tax => 0.95,
:line_items => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-0',
:product_tax_code => nil,
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
Update refund transaction
Definition
client.update_refund
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
refund = client.update_refund({
:transaction_id => '321',
:amount => 17,
:shipping => 2,
:sales_tax => 0.95,
:line_items => [{:quantity => 1,
:product_identifier => '12-34243-9',
:description => 'Heavy Widget',
:unit_price => 15,
:sales_tax => 0.95}]
})
Example Response
#<Taxjar::Refund:0x00000a @attrs={
:transaction_id => '321',
:user_id => 11836,
:transaction_date => '2015-06-14T00:00:00Z',
:transaction_reference_id => '123',
: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.95,
:shipping => 2,
:sales_tax => 0.95,
:line_items => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-9',
:product_tax_code => nil,
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
Delete refund transaction
Definition
client.delete_refund
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.delete_refund('321')
Example Response
#<Taxjar::Refund:0x00000a @attrs={
:transaction_id => '321',
:user_id => 11836,
:transaction_date => '2015-06-14T00:00:00Z',
:transaction_reference_id => '123',
: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.95,
:shipping => 2,
:sales_tax => 0.95,
:line_items => [
{
:id => '1',
:quantity => 1,
:product_identifier => '12-34243-9',
:product_tax_code => nil,
:description => 'Heavy Widget',
:unit_price => 15,
:discount => 0,
:sales_tax => 0.95
}
]
}>
List customers
Definition
client.list_customers
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.list_customers
Example Response
['123', '124', '125']
Show customer
Definition
client.show_customer
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.show_customer('123')
Example Response
#<Taxjar::Customer @attrs={
:customer_id => "123",
:exemption_type => "wholesale",
:exempt_regions => [
[0] {
:country => "US",
:state => "FL"
},
[1] {
:country => "US",
:state => "PA"
}
],
:name => "Dunder Mifflin Paper Company",
:country => "US",
:state => "PA",
:zip => "18504",
:city => "Scranton",
:street => "1725 Slough Avenue"
}>
Create customer
Definition
client.create_customer
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
customer = 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
#<Taxjar::Customer @attrs={
:customer_id => "123",
:exemption_type => "wholesale",
:exempt_regions => [
[0] {
:country => "US",
:state => "FL"
},
[1] {
:country => "US",
:state => "PA"
}
],
:name => "Dunder Mifflin Paper Company",
:country => "US",
:state => "PA",
:zip => "18504",
:city => "Scranton",
:street => "1725 Slough Avenue"
}>
Update customer
Definition
client.update_customer
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
customer = client.update_customer({
: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'
})
Example Response
#<Taxjar::Customer @attrs={
:customer_id => "123",
:exemption_type => "wholesale",
:exempt_regions => [
[0] {
:country => "US",
:state => "NY"
}
],
:name => "Sterling Cooper",
:country => "US",
:state => "NY",
:zip => "10010",
:city => "New York",
:street => "405 Madison Ave"
}>
Delete customer
Definition
client.delete_customer
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
client.delete_customer('123')
Example Response
#<Taxjar::Customer @attrs={
:customer_id => "123",
:exemption_type => "wholesale",
:exempt_regions => [
[0] {
:country => "US",
:state => "FL"
},
[1] {
:country => "US",
:state => "PA"
}
],
:name => "Dunder Mifflin Paper Company",
:country => "US",
:state => "PA",
:zip => "18504",
:city => "Scranton",
:street => "1725 Slough Avenue"
}>
List nexus regions
Definition
client.nexus_regions
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '9e0cd62a22f451701f29c3bde214')
nexus_regions = client.nexus_regions
Example Response
[
#<Taxjar::NexusRegion:0x00000a @attrs={
:country_code => 'US',
:country => 'United States',
:region_code => 'CA',
:region => 'California'
}>,
#<Taxjar::NexusRegion:0x00000a @attrs={
:country_code => 'US',
:country => 'United States',
:region_code => 'NY',
:region => 'New York'
}>,
#<Taxjar::NexusRegion:0x00000a @attrs={
:country_code => 'US',
:country => 'United States',
:region_code => 'WA',
:region => 'Washington'
}>
]
Validate a VAT number
Definition
client.validate
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '9e0cd62a22f451701f29c3bde214')
validation = client.validate({
:vat => 'FR40303265045'
})
Example Response
#<Taxjar::Validation:0x00000a @attrs={
:valid => true,
:exists => true,
:vies_available => true,
:vies_response => {
: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
Definition
client.summary_rates
Example Request
require 'taxjar'
client = Taxjar::Client.new(api_key: '9e0cd62a22f451701f29c3bde214')
summarized_rates = client.summary_rates
Example Response
[
#<Taxjar::SummaryRate:0x00000a @attrs={
:country_code => 'US',
:country => 'United States',
:region_code => 'CA',
:region => 'California',
:minimum_rate => {
:label => 'State Tax',
:rate => 0.065
},
:average_rate => {
:label => 'Tax',
:rate => 0.0827
}
}>,
#<Taxjar::SummaryRate:0x00000a @attrs={
:country_code => 'CA',
:country => 'Canada',
:region_code => 'BC',
:region => 'British Columbia',
:minimum_rate => {
:label => 'GST',
:rate => 0.05
},
:average_rate => {
:label => 'PST',
:rate => 0.12
}
}>,
#<Taxjar::SummaryRate:0x00000a @attrs={
:country_code => 'UK',
:country => 'United Kingdom',
:region_code => nil,
:region => nil,
:minimum_rate => {
:label => 'VAT',
:rate => 0.2
},
:average_rate => {
:label => 'VAT',
:rate => 0.2
}
}>
]
Custom Options
Pass a hash to any API method above for the following options:
Timeouts
Set request timeout in seconds:
client.tax_for_order({ timeout: 30 })
Sandbox Environment
You can easily configure the client to use the TaxJar Sandbox:
require 'taxjar'
client = Taxjar::Client.new(api_key: 'YOUR_SANDBOX_API_TOKEN', 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
})
Error Handling
When invalid data is sent to TaxJar or we encounter an error, we’ll throw a Taxjar::Error
with the HTTP status code and error message. To catch these exceptions, refer to the example below. Click here for a list of common error response classes.
require 'taxjar'
client = Taxjar::Client.new(api_key: '9e0cd62a22f451701f29c3bde214')
begin
order = client.create_order({
:transaction_date => '2015/05/14',
:to_country => 'US',
:to_state => 'CA',
:to_zip => '90002',
:amount => 17.45,
:shipping => 1.5,
:sales_tax => 0.95
})
rescue Taxjar::Error => e
# <Taxjar::Error::NotAcceptable: transaction_id is missing>
puts e.class.name
puts e.
end
Tests
An RSpec test suite is available to ensure API functionality:
$ git clone git://github.com/taxjar/taxjar-ruby.git
$ bundle install
$ rspec
More Information
More information can be found on TaxJar Developers.
License
TaxJar is released under the MIT License.
Support
Bug reports and feature requests should be filed on the GitHub issue tracking page.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new pull request