taxjar-ruby 2.5.0 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1bfb85c8da4a0794eaa7fb2634d811d6e1d48d1d
-  data.tar.gz: 8ac52df47adcebb45a240649322bd80820d8298b
+SHA256:
+  metadata.gz: 59f7440e50a1552f055f03501341b8883c960d9e85d50de6817ec7b7ca3908a1
+  data.tar.gz: 74712431ab3d1ad24fdfd064aa61cbdf53f5b47061d6eb61e032405ca9e2a539
 SHA512:
-  metadata.gz: 49c6eb22aa02d983f00e2fb33cdcc98b7958fda8d3d0cf2d6dc28a32098075ec8c76f1ac93d7a24354677fac3df9f4483735164e035588f904bd498a3d290b8a
-  data.tar.gz: 9783ad5245bb139312e63ccaa560f080e649d439daf4006c5c5e3aec854e3e174169bb383a2f204ca66f6e72ab73d3a61362ad69ea2db1c823c50e7255e6a7f3
+  metadata.gz: 73aa9395d63a8b078699b23dcac7e97555831de2846db337e5ea32861fc6f3722589c6c0437eb7c8349d2f53614227f54cb11506d94370dbbac15f8c49fd7ea5
+  data.tar.gz: 95d3fb22ef2bcbf85fd5e256eb628765f8f1698ebedd5527b9f3fbc952357aa0fe6b3e04f87727dc4493c5feb7741ca309e73d3d93d1337c780083fc0cd6f8eb

data/.travis.yml

@@ -1,16 +1,11 @@
 language: ruby
 
 rvm:
- - "2.0"
- - "2.1"
- - "2.2"
  - "2.3"
  - "2.4"
  - "2.5"
  - "2.6"
+ - "2.7"
+ - "3.0"
 
 script: bundle exec rspec
-
-before_install:
- - gem uninstall -v '>= 2' -i $(rvm gemdir)@global -ax bundler || true
- - gem install bundler -v '< 2'

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [3.0.2] - 2021-03-18
+- Re-classify `HTTP::ConnectionError` and other `HTTP::Error` types as `Taxjar::Error`
+
+## [3.0.1] - 2021-03-16
+- Throw a `Taxjar::Error` exception for any non-successful HTTP response
+
+## [3.0.0] - 2020-04-03
+- Add information to custom user agent for debugging and informational purposes
+- Update required Ruby version from 2.0 to 2.3 or higher
+- Update HTTP (The Gem) to version 4.3
+- Relax bundler (development dependency) version requirements
+
+## [2.6.1] - 2019-10-23
+- Parse all responses as JSON and improve error handling for non-JSON [#51](https://github.com/taxjar/taxjar-ruby/pull/51)
+
+## [2.6.0] - 2019-07-09
+- Support `exemption_type` param for order-level exempt transactions
+
 ## [2.5.0] - 2019-06-19
 - Support `provider` param for marketplace exempt transactions
 - Add proxy support when instantiating client
@@ -31,11 +49,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Update minimum required Ruby version to 2.0
 - Update HTTP (The Gem) to 2.2
 
-[Unreleased]: https://github.com/taxjar/taxjar-ruby/compare/v2.5.0...HEAD
+[Unreleased]: https://github.com/taxjar/taxjar-ruby/compare/v3.0.2...HEAD
+[3.0.2]: https://github.com/taxjar/taxjar-ruby/compare/v3.0.1...v3.0.2
+[3.0.1]: https://github.com/taxjar/taxjar-ruby/compare/v3.0.0...v3.0.1
+[3.0.0]: https://github.com/taxjar/taxjar-ruby/compare/v2.6.1...v3.0.0
+[2.6.1]: https://github.com/taxjar/taxjar-ruby/compare/v2.6.0...v2.6.1
+[2.6.0]: https://github.com/taxjar/taxjar-ruby/compare/v2.5.0...v2.6.0
 [2.5.0]: https://github.com/taxjar/taxjar-ruby/compare/v2.4.1...v2.5.0
 [2.4.1]: https://github.com/taxjar/taxjar-ruby/compare/v2.4.0...v2.4.1
 [2.4.0]: https://github.com/taxjar/taxjar-ruby/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/taxjar/taxjar-ruby/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/taxjar/taxjar-ruby/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/taxjar/taxjar-ruby/compare/v2.0.0...v2.1.0
-[2.0.0]: https://github.com/taxjar/taxjar-ruby/compare/v1.7.1...v2.0.0
+[2.0.0]: https://github.com/taxjar/taxjar-ruby/compare/v1.7.1...v2.0.0

data/README.md

@@ -1,15 +1,33 @@
-# TaxJar Sales Tax API for Ruby [![RubyGems](http://img.shields.io/gem/v/taxjar-ruby.svg?style=flat-square)](https://rubygems.org/gems/taxjar-ruby) [![Build Status](http://img.shields.io/travis/taxjar/taxjar-ruby.svg?style=flat-square)](https://travis-ci.org/taxjar/taxjar-ruby)
+# TaxJar Sales Tax API for Ruby [![RubyGems](https://img.shields.io/gem/v/taxjar-ruby.svg?style=flat-square)](https://rubygems.org/gems/taxjar-ruby) [![Build Status](https://img.shields.io/travis/taxjar/taxjar-ruby.svg?style=flat-square)](https://travis-ci.org/taxjar/taxjar-ruby)
 
-<a href="http://developers.taxjar.com"><img src="http://www.taxjar.com/img/TJ_logo_color_office_png.png" alt="TaxJar" width="220"></a>
+<a href="https://developers.taxjar.com"><img src="https://www.taxjar.com/img/TJ_logo_color_office_png.png" alt="TaxJar" width="220"></a>
 
-A Ruby interface to the TaxJar [Sales Tax API](https://developers.taxjar.com/api/reference/). 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.
+A Ruby interface to the TaxJar [Sales Tax API](https://developers.taxjar.com/api/reference/?ruby). 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](http://developers.taxjar.com/api/#introduction)
+* This wrapper supports 100% of the [TaxJar API](https://developers.taxjar.com/api/#introduction)
 * Data returned from API calls are mapped to Ruby objects
 
+<hr>
+
+[Supported Ruby Versions](#supported-ruby-versions)<br>
+[Gem Dependencies](#gem-dependencies)<br>
+[Installation](#installation)<br>
+[Authentication](#authentication)<br>
+[Usage](#usage)<br>
+[Custom Options](#custom-options)<br>
+[Sandbox Environment](#sandbox-environment)<br>
+[Error Handling](#error-handling)<br>
+[Tests](#tests)<br>
+[More Information](#more-information)<br>
+[License](#license)<br>
+[Support](#support)<br>
+[Contributing](#contributing)
+
+<hr>
+
 ## Supported Ruby Versions
 
-Ruby 2.0 or greater
+Ruby 2.3 or greater
 
 ## Gem Dependencies
 
@@ -53,7 +71,35 @@ You're now ready to use TaxJar! [Check out our quickstart guide](https://develop
 
 ## Usage
 
-### List all tax categories
+[`categories` - List all tax categories](#list-all-tax-categories-api-docs)<br>
+[`tax_for_order` - Calculate sales tax for an order](#calculate-sales-tax-for-an-order-api-docs)<br>
+[`list_orders` - List order transactions](#list-order-transactions-api-docs)<br>
+[`show_order` - Show order transaction](#show-order-transaction-api-docs)<br>
+[`create_order` - Create order transaction](#create-order-transaction-api-docs)<br>
+[`update_order` - Update order transaction](#update-order-transaction-api-docs)<br>
+[`delete_order` - Delete order transaction](#delete-order-transaction-api-docs)<br>
+[`list_refunds` - List refund transactions](#list-refund-transactions-api-docs)<br>
+[`show_refund` - Show refund transaction](#show-refund-transaction-api-docs)<br>
+[`create_refund` - Create refund transaction](#create-refund-transaction-api-docs)<br>
+[`update_refund` - Update refund transaction](#update-refund-transaction-api-docs)<br>
+[`delete_refund` - Delete refund transaction](#delete-refund-transaction-api-docs)<br>
+[`list_customers` - List customers](#list-customers-api-docs)<br>
+[`show_customer` - Show customer](#show-customer-api-docs)<br>
+[`create_customer` - Create customer](#create-customer-api-docs)<br>
+[`update_customer` - Update customer](#update-customer-api-docs)<br>
+[`delete_customer` - Delete customer](#delete-customer-api-docs)<br>
+[`rates_for_location` - List tax rates for a location (by zip/postal code)](#list-tax-rates-for-a-location-by-zippostal-code-api-docs)<br>
+[`nexus_regions` - List nexus regions](#list-nexus-regions-api-docs)<br>
+[`validate_address` - Validate an address](#validate-an-address-api-docs)<br>
+[`validate` - Validate a VAT number](#validate-a-vat-number-api-docs)<br>
+[`summary_rates` - Summarize tax rates for all regions](#summarize-tax-rates-for-all-regions-api-docs)
+
+<hr>
+
+
+### List all tax categories <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-list-tax-categories))_</small>
+
+> 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
 
@@ -92,79 +138,9 @@ client.categories
 ]
 ```
 
-### List tax rates for a location (by zip/postal code)
-
-#### Definition
-
-```ruby
-client.rates_for_location
-```
-
-#### Example Request
-
-```ruby
-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
-
-```ruby
-#<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 <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#post-calculate-sales-tax-for-an-order))_</small>
 
-### Calculate Sales tax for an order
+> Shows the sales tax that should be collected for a given order.
 
 #### Definition
 
@@ -179,24 +155,25 @@ require 'taxjar'
 client = Taxjar::Client.new(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 => '90002',
-    :to_city => 'Los Angeles',
+    :to_zip => '94303',
     :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}]
+    :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}]
 })
 ```
 
@@ -204,44 +181,63 @@ client.tax_for_order({
 
 ```ruby
 #<Taxjar::Tax:0x00000a @attrs={
-  :order_total_amount => 16.5,
-  :amount_to_collect => 1.35,
-  :has_nexus => true,
-  :freight_taxable => false,
+  :taxable_amount => 0,
   :tax_source => 'destination',
+  :shipping => 0,
+  :rate => 0,
+  :order_total_amount => 267.9
   :jurisdictions => #<Taxjar::Jurisdictions:0x00000a @attrs={
-    :country => 'US',
     :state => 'CA',
-    :county => 'LOS ANGELES',
-    :city => 'LOS ANGELES'
+    :county => 'SAN MATEO',
+    :country => 'US',
+    :city => 'EAST PALO ALTO'
   }>,
+  :has_nexus => true,
+  :freight_taxable => false,
   :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,
+    :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 => [
       #<Taxjar::BreakdownLineItem:0x00000a @attrs={
+        :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',
-        :state_taxable_amount => 15,
-        :state_sales_tax_rate => 0.065,
-        :county_taxable_amount => 15,
-        :county_tax_rate => 0.01,
+        :county_taxable_amount => 0,
+        :county_tax_rate => 0,
+        :county_amount => 0,
+        :combined_tax_rate => 0,
         :city_taxable_amount => 0,
         :city_tax_rate => 0,
-        :special_district_taxable_amount => 15,
-        :special_tax_rate => 0.015
+        :city_amount => 0,
       }>
-    ]
+    ],
+    :county_taxable_amount => 0,
+    :county_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
+### List order transactions <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-list-order-transactions))_</small>
+
+> Lists existing order transactions created through the API.
 
 #### Definition
 
@@ -255,8 +251,8 @@ client.list_orders
 require 'taxjar'
 client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
 
-client.list_orders({:from_transaction_date => '2014/01/01',
-                    :to_transaction_date => '2015/05/30'})
+client.list_orders({:from_transaction_date => '2015/05/01',
+                    :to_transaction_date => '2015/05/31'})
 ```
 
 #### Example Response
@@ -265,7 +261,9 @@ client.list_orders({:from_transaction_date => '2014/01/01',
 ['20', '21', '22']
 ```
 
-### Show order transaction
+### Show order transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-show-an-order-transaction))_</small>
+
+> Shows an existing order transaction created through the API.
 
 #### Definition
 
@@ -291,12 +289,12 @@ client.show_order('123')
   :transaction_date => '2015-05-14T00:00:00Z',
   :transaction_reference_id => nil,
   :from_country => 'US',
-  :from_zip => 93107,
+  :from_zip => '93107',
   :from_state => 'CA',
   :from_city => 'SANTA BARBARA',
   :from_street => '1281 State St',
   :to_country => 'US',
-  :to_zip => 90002,
+  :to_zip => '90002',
   :to_state => 'CA',
   :to_city => 'LOS ANGELES',
   :to_street => '123 Palm Grove Ln',
@@ -318,7 +316,9 @@ client.show_order('123')
 }>
 ```
 
-### Create order transaction
+### Create order transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#post-create-an-order-transaction))_</small>
+
+> Creates a new order transaction.
 
 #### Definition
 
@@ -334,25 +334,27 @@ 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',
+    :transaction_date => '2015/05/15',
     :from_country => 'US',
-    :from_zip => '93101',
+    :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 => '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}]
+    :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}]
 })
 ```
 
@@ -360,39 +362,44 @@ order = client.create_order({
 
 ```ruby
 #<Taxjar::Order:0x00000a @attrs={
-  :transaction_id => '20',
+  :transaction_id => '123',
   :user_id => 11836,
-  :transaction_date => '2015-05-14T00:00:00Z',
+  :provider => 'api',
+  :transaction_date => '2015-05-15T00:00:00Z',
   :transaction_reference_id => nil,
+  :customer_id => nil,
+  :exemption_type => nil,
   :from_country => 'US',
-  :from_zip => 93101,
+  :from_zip => '94025',
   :from_state => 'CA',
-  :from_city => 'SANTA BARBARA',
-  :from_street => '1218 State St',
+  :from_city => 'MENLO PARK',
+  :from_street => '2825 Sand Hill Rd',
   :to_country => 'US',
-  :to_zip => 90002,
+  :to_zip => '94303',
   :to_state => 'CA',
-  :to_city => 'LOS ANGELES',
-  :to_street => '123 Palm Grove Ln',
-  :amount => 16.5,
-  :shipping => 1.5,
-  :sales_tax => 0.95,
+  :to_city => 'PALO ALTO',
+  :to_street => '5230 Newell Rd',
+  :amount => 267.9,
+  :shipping => 0,
+  :sales_tax => 0,
   :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
+      :product_identifier => nil,
+      :product_tax_code => '19005',
+      :description => 'Legal Services',
+      :unit_price => 535.8,
+      :discount => 267.9,
+      :sales_tax => 0
     }
   ]
 }>
 ```
 
-### Update order transaction
+### Update order transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#put-update-an-order-transaction))_</small>
+
+> Updates an existing order transaction created through the API.
 
 #### Definition
 
@@ -408,14 +415,28 @@ 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}]
+    :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
+      }
+    ]
 })
 ```
 
@@ -425,37 +446,52 @@ order = client.update_order({
 #<Taxjar::Order:0x00000a @attrs={
   :transaction_id => '123',
   :user_id => 11836,
-  :transaction_date => '2015-05-14T00:00:00Z',
+  :provider => 'api',
+  :transaction_date => '2015-05-15T00:00:00Z',
   :transaction_reference_id => nil,
+  :customer_id => nil,
+  :exemption_type => nil,
   :from_country => 'US',
-  :from_zip => 93101,
+  :from_zip => '94025',
   :from_state => 'CA',
-  :from_city => 'SANTA BARBARA',
-  :from_street => '1218 State St',
+  :from_city => 'MENLO PARK',
+  :from_street => '2825 Sand Hill Rd',
   :to_country => 'US',
-  :to_zip => 90002,
+  :to_zip => '94303',
   :to_state => 'CA',
-  :to_city => 'LOS ANGELES',
-  :to_street => '123 Palm Grove Ln',
-  :amount => 17,
-  :shipping => 2,
-  :sales_tax => 0.95,
+  :to_city => 'PALO ALTO',
+  :to_street => '5230 Newell Road',
+  :amount => 283.6,
+  :shipping => 5,
+  :sales_tax => 1.04,
   :line_items => [
     {
       :id => '1',
       :quantity => 1,
-      :product_identifier => '12-34243-0',
+      :product_identifier => nil,
+      :product_tax_code => '19005',
+      :description => 'Legal Services',
+      :unit_price => 535.8,
+      :discount => 267.9,
+      :sales_tax => 0
+    },
+    {
+      :id => '2',
+      :quantity => 2,
+      :product_identifier => nil,
       :product_tax_code => nil,
-      :description => 'Heavy Widget',
-      :unit_price => 15,
-      :discount => 0,
-      :sales_tax => 0.95
+      :description => 'Hoberman Switch Pitch',
+      :unit_price => 10.7,
+      :discount => 10.7,
+      :sales_tax => 1.04
     }
   ]
 }>
 ```
 
-### Delete order transaction
+### Delete order transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#delete-delete-an-order-transaction))_</small>
+
+> Deletes an existing order transaction created through the API.
 
 #### Definition
 
@@ -478,37 +514,31 @@ client.delete_order('123')
 #<Taxjar::Order:0x00000a @attrs={
   :transaction_id => '123',
   :user_id => 11836,
-  :transaction_date => '2015-05-14T00:00:00Z',
+  :provider => 'api',
+  :transaction_date => nil,
   :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
-    }
-  ]
+  :customer_id => nil,
+  :exemption_type => nil,
+  :from_country => nil,
+  :from_zip => nil,
+  :from_state => nil,
+  :from_city => nil,
+  :from_street => nil,
+  :to_country => nil,
+  :to_zip => nil,
+  :to_state => nil,
+  :to_city => nil,
+  :to_street => nil,
+  :amount => nil,
+  :shipping => nil,
+  :sales_tax => nil,
+  :line_items => []
 }>
 ```
 
-### Listing refund transactions
+### List refund transactions <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-list-refund-transactions))_</small>
+
+> Lists existing refund transactions created through the API.
 
 #### Definition
 
@@ -522,17 +552,19 @@ client.list_refunds
 require 'taxjar'
 client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
 
-client.list_refunds({:from_transaction_date => '2014/01/01',
-                     :to_transaction_date => '2015/05/30'})
+client.list_refunds({:from_transaction_date => '2015/05/01',
+                     :to_transaction_date => '2015/05/31'})
 ```
 
 #### Example Response
 
 ```ruby
-['203', '204', '205']
+['20-refund', '21-refund', '22-refund']
 ```
 
-### Show refund transaction
+### Show refund transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-show-a-refund-transaction))_</small>
+
+> Shows an existing refund transaction created through the API.
 
 #### Definition
 
@@ -546,30 +578,33 @@ client.show_refund
 require 'taxjar'
 client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
 
-client.show_refund('321')
+client.show_refund('20-refund')
 ```
 
 #### Example Response
 
 ```ruby
 #<Taxjar::Refund:0x00000a @attrs={
-  :transaction_id => '321',
+  :transaction_id => '20-refund',
   :user_id => 11836,
-  :transaction_date => '2015-06-14T00:00:00Z',
-  :transaction_reference_id => 123,
+  :provider => 'api',
+  :transaction_date => '2015-05-15T00:00:00Z',
+  :transaction_reference_id => '20',
+  :customer_id => nil,
+  :exemption_type => nil,
   :from_country => 'US',
-  :from_zip => 93107,
+  :from_zip => '93107',
   :from_state => 'CA',
   :from_city => 'SANTA BARBARA',
   :from_street => '1218 State St',
   :to_country => 'US',
-  :to_zip => 90002,
+  :to_zip => '90002',
   :to_state => 'CA',
   :to_city => 'LOS ANGELES',
   :to_street => '123 Palm Grove Ln',
-  :amount => 17,
-  :shipping => 2,
-  :sales_tax => 0.95,
+  :amount => -17,
+  :shipping => -2,
+  :sales_tax => -0.95,
   :line_items => [
     {
       :id => '1',
@@ -577,15 +612,17 @@ client.show_refund('321')
       :product_identifier => '12-34243-0',
       :product_tax_code => nil,
       :description => 'Heavy Widget',
-      :unit_price => 15,
+      :unit_price => -15,
       :discount => 0,
-      :sales_tax => 0.95
+      :sales_tax => -0.95
     }
   ]
 }>
 ```
 
-### Create refund transaction
+### Create refund transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#post-create-a-refund-transaction))_</small>
+
+> Creates a new refund transaction.
 
 #### Definition
 
@@ -600,27 +637,41 @@ require 'taxjar'
 client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
 
 refund = client.create_refund({
-    :transaction_id => '321',
-    :transaction_date => '2015/05/14',
+    :transaction_id => '123-refund',
     :transaction_reference_id => '123',
+    :transaction_date => '2015/05/15',
     :from_country => 'US',
-    :from_zip => '93107',
+    :from_zip => '94025',
     :from_state => 'CA',
-    :from_city => 'Santa Barbara',
-    :from_street => '1218 State St',
+    :from_city => 'Menlo Park',
+    :from_street => '2825 Sand Hill Rd',
     :to_country => 'US',
-    :to_zip => '90002',
+    :to_zip => '94303',
     :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}]
+    :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
+      }
+    ]
 })
 ```
 
@@ -628,39 +679,54 @@ refund = client.create_refund({
 
 ```ruby
 #<Taxjar::Refund:0x00000a @attrs={
-  :transaction_id => '321',
+  :transaction_id => '123-refund',
   :user_id => 11836,
-  :transaction_date => '2015-06-14T00:00:00Z',
+  :provider => 'api',
+  :transaction_date => '2015-05-15T00:00:00Z',
   :transaction_reference_id => '123',
+  :customer_id => nil,
+  :exemption_type => nil,
   :from_country => 'US',
-  :from_zip => 93107,
+  :from_zip => '94025',
   :from_state => 'CA',
-  :from_city => 'SANTA BARBARA',
-  :from_street => '1218 State St',
+  :from_city => 'MENLO PARK',
+  :from_street => '2825 Sand Hill Rd',
   :to_country => 'US',
-  :to_zip => 90002,
+  :to_zip => '94303',
   :to_state => 'CA',
-  :to_city => 'LOS ANGELES',
-  :to_street => '123 Palm Grove Ln',
-  :amount => 16.5,
-  :shipping => 1.5,
-  :sales_tax => 0.95,
+  :to_city => 'PALO ALTO',
+  :to_street => '5230 Newell Road',
+  :amount => -5.35,
+  :shipping => -0,
+  :sales_tax => -0.52,
   :line_items => [
     {
       :id => '1',
       :quantity => 1,
-      :product_identifier => '12-34243-0',
-      :product_tax_code => nil,
-      :description => 'Heavy Widget',
-      :unit_price => 15,
+      :product_identifier => nil,
+      :product_tax_code => '19005',
+      :description => 'Legal Services',
+      :unit_price => 0,
       :discount => 0,
-      :sales_tax => 0.95
+      :sales_tax => 0
+    },
+    {
+      :id => '2',
+      :quantity => 1,
+      :product_identifier => nil,
+      :product_tax_code => nil,
+      :description => 'Hoberman Switch Pitch',
+      :unit_price => 0,
+      :discount => -5.35,
+      :sales_tax => -0.52
     }
   ]
 }>
 ```
 
-### Update refund transaction
+### Update refund transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#put-update-a-refund-transaction))_</small>
+
+> Updates an existing refund transaction created through the API.
 
 #### Definition
 
@@ -675,15 +741,10 @@ 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}]
+  :transaction_id => '123-refund',
+  :transaction_reference_id => '123',
+  :amount => -10.35,
+  :shipping => -5
 })
 ```
 
@@ -691,39 +752,54 @@ refund = client.update_refund({
 
 ```ruby
 #<Taxjar::Refund:0x00000a @attrs={
-  :transaction_id => '321',
+  :transaction_id => '123-refund',
   :user_id => 11836,
-  :transaction_date => '2015-06-14T00:00:00Z',
+  :provider => 'api',
+  :transaction_date => '2015-05-15T00:00:00Z',
   :transaction_reference_id => '123',
+  :customer_id => nil,
+  :exemption_type => nil,
   :from_country => 'US',
-  :from_zip => 93107,
+  :from_zip => '94025',
   :from_state => 'CA',
-  :from_city => 'SANTA BARBARA',
-  :from_street => '1218 State St',
+  :from_city => 'MENLO PARK',
+  :from_street => '2825 Sand Hill Rd',
   :to_country => 'US',
-  :to_zip => 90002,
+  :to_zip => '94303',
   :to_state => 'CA',
-  :to_city => 'LOS ANGELES',
-  :to_street => '123 Palm Grove Ln',
-  :amount => 17.95,
-  :shipping => 2,
-  :sales_tax => 0.95,
+  :to_city => 'PALO ALTO',
+  :to_street => '5230 Newell Road',
+  :amount => -10.35,
+  :shipping => -5,
+  :sales_tax => 0,
   :line_items => [
     {
       :id => '1',
       :quantity => 1,
-      :product_identifier => '12-34243-9',
-      :product_tax_code => nil,
-      :description => 'Heavy Widget',
-      :unit_price => 15,
+      :product_identifier => nil,
+      :product_tax_code => '19005',
+      :description => 'Legal Services',
+      :unit_price => 0,
       :discount => 0,
-      :sales_tax => 0.95
+      :sales_tax => 0
+    },
+    {
+      :id => '2',
+      :quantity => 1,
+      :product_identifier => nil,
+      :product_tax_code => nil,
+      :description => 'Hoberman Switch Pitch',
+      :unit_price => 0,
+      :discount => -5.35,
+      :sales_tax => -0.52
     }
   ]
 }>
 ```
 
-### Delete refund transaction
+### Delete refund transaction <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#delete-delete-a-refund-transaction))_</small>
+
+> Deletes an existing refund transaction created through the API.
 
 #### Definition
 
@@ -737,46 +813,40 @@ client.delete_refund
 require 'taxjar'
 client = Taxjar::Client.new(api_key: '48ceecccc8af930bd02597aec0f84a78')
 
-client.delete_refund('321')
+client.delete_refund('123-refund')
 ```
 
 #### Example Response
 
 ```ruby
 #<Taxjar::Refund:0x00000a @attrs={
-  :transaction_id => '321',
+  :transaction_id => '123-refund',
   :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
-    }
-  ]
+  :provider => 'api',
+  :transaction_date => nil,
+  :transaction_reference_id => nil,
+  :customer_id => nil,
+  :exemption_type => nil,
+  :from_country => nil,
+  :from_zip => nil,
+  :from_state => nil,
+  :from_city => nil,
+  :from_street => nil,
+  :to_country => nil,
+  :to_zip => nil,
+  :to_state => nil,
+  :to_city => nil,
+  :to_street => nil,
+  :amount => nil,
+  :shipping => nil,
+  :sales_tax => nil,
+  :line_items => []
 }>
 ```
 
-### List customers
+### List customers <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-list-customers))_</small>
+
+> Lists existing customers created through the API.
 
 #### Definition
 
@@ -799,7 +869,9 @@ client.list_customers
 ['123', '124', '125']
 ```
 
-### Show customer
+### Show customer <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-show-a-customer))_</small>
+
+> Shows an existing customer created through the API.
 
 #### Definition
 
@@ -841,7 +913,9 @@ client.show_customer('123')
 }>
 ```
 
-### Create customer
+### Create customer <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#post-create-a-customer))_</small>
+
+> Creates a new customer.
 
 #### Definition
 
@@ -902,7 +976,9 @@ customer = client.create_customer({
 }>
 ```
 
-### Update customer
+### Update customer <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#put-update-a-customer))_</small>
+
+> Updates an existing customer created through the API.
 
 #### Definition
 
@@ -955,7 +1031,9 @@ customer = client.update_customer({
 }>
 ```
 
-### Delete customer
+### Delete customer <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#delete-delete-a-customer))_</small>
+
+> Deletes an existing customer created through the API.
 
 #### Definition
 
@@ -978,16 +1056,7 @@ client.delete_customer('123')
 #<Taxjar::Customer @attrs={
   :customer_id => "123",
   :exemption_type => "wholesale",
-  :exempt_regions => [
-    [0] {
-      :country => "US",
-      :state => "FL"
-    },
-    [1] {
-      :country => "US",
-      :state => "PA"
-    }
-  ],
+  :exempt_regions => [],
   :name => "Dunder Mifflin Paper Company",
   :country => "US",
   :state => "PA",
@@ -997,7 +1066,85 @@ client.delete_customer('123')
 }>
 ```
 
-### List nexus regions
+### List tax rates for a location (by zip/postal code) <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-show-tax-rates-for-a-location))_</small>
+
+> 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](#calculate-sales-tax-for-an-order-api-docs).
+
+#### Definition
+
+```ruby
+client.rates_for_location
+```
+
+#### Example Request
+
+```ruby
+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
+
+```ruby
+#<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
+}>
+```
+
+### List nexus regions <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-list-nexus-regions))_</small>
+
+> Lists existing nexus locations for a TaxJar account.
 
 #### Definition
 
@@ -1039,7 +1186,48 @@ nexus_regions = client.nexus_regions
 ]
 ```
 
-### Validate a VAT number
+### Validate an address <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#post-validate-an-address))_</small>
+
+> Validates a customer address and returns back a collection of address matches. **Address validation requires a [TaxJar Plus](https://www.taxjar.com/plus/) subscription.**
+
+#### Definition
+
+```ruby
+client.validate_address
+```
+
+#### Example Request
+
+```ruby
+require 'taxjar'
+client = Taxjar::Client.new(api_key: '9e0cd62a22f451701f29c3bde214')
+
+addresses = client.validate_address({
+  :country => 'US',
+  :state => 'AZ',
+  :zip => '85297',
+  :city => 'Gilbert',
+  :street => '3301 Greenfield Rd'
+})
+```
+
+#### Example Response
+
+```ruby
+[
+  #<Taxjar::Address:0x00000a @attrs={
+    :zip => '85297-2176',
+    :street => '3301 S Greenfield Rd',
+    :state => 'AZ',
+    :country => 'US',
+    :city => 'Gilbert'
+  }>
+]
+```
+
+### Validate a VAT number <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-validate-a-vat-number))_</small>
+
+> Validates an existing VAT identification number against [VIES](http://ec.europa.eu/taxation_customs/vies/).
 
 #### Definition
 
@@ -1076,7 +1264,11 @@ validation = client.validate({
 }>
 ```
 
-### Summarize tax rates for all regions
+### Summarize tax rates for all regions <small>_([API docs](https://developers.taxjar.com/api/reference/?ruby#get-summarize-tax-rates-for-all-regions))_</small>
+
+> 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](#calculate-sales-tax-for-an-order-api-docs).
 
 #### Definition
 
@@ -1156,7 +1348,7 @@ client.tax_for_order({ timeout: 30 })
 
 ## Sandbox Environment
 
-You can easily configure the client to use the [TaxJar Sandbox](https://developers.taxjar.com/api/reference/#sandbox-environment):
+You can easily configure the client to use the [TaxJar Sandbox](https://developers.taxjar.com/api/reference/?ruby#sandbox-environment):
 
 ```ruby
 require 'taxjar'
@@ -1208,7 +1400,7 @@ $ rspec
 
 ## More Information
 
-More information can be found on [TaxJar Developers](http://developers.taxjar.com).
+More information can be found on [TaxJar Developers](https://developers.taxjar.com).
 
 ## License