TaxCloud Sales Tax Calculation Service

TaxCloud is a free hosted service that calculates the sales tax due on your transactions. Using TaxCloud is as easy as calculating real-time shipping, a common feature in most shopping carts today. When you calculate real-time shipping, your website sends a request to the shipper to determine the cost of shipping at a certain speed to a particular location. TaxCloud works the same way.

When a customer is ready to check out, TaxCloud sends your website the sales tax amount based on the origin, destination, and class of goods. Your website displays that sales tax amount and adds it on to the customer’s total. The customer finishes checking out, and your website notifies TaxCloud that the purchase was completed, allowing us to keep record the transaction for you.

TaxCloud operates on a real-time web services API.

See for more information and to sign up for a free account

Getting Started

  1. Create a TaxCloud merchant account at

  2. Add a website to your TaxCloud account. This will generate an API ID and API Key that you will

need to use the service.

  1. Optional - create a USPS ID to use the address verification service. It is recommended to verify

each address to get the nine digit zip code. This allows TaxCloud to determine the most accurate rate.

  1. Add the TaxCloud gem to your application.

  2. Call the TaxCloud web services to calculate sales tax.

Using the web services

TaxCloud's API is build as a standard SOAP web service. This gem is not required to use TaxCloud. It is meant to give examples of how to use the service.

TaxCloud determines a sales tax rate based on the merchant's origin address, the customer's shipping address and the type of project. There are three main services that will need to be integrated: verify_address(), lookup(), and authorized_and_capture().

This process is designed with a shopping cart checkout in mind, but it can be used for other applications. In a shopping cart the process would be to verify the customer's shipping address, and then call lookup() with the addresses and the items in the shopping cart. This will return the tax to apply to each item in the cart. Shipping is also included in the calculation as it can sometimes be taxable.

Once the tax has been added to the order and you are ready to complete the transaction the authorized_and_captured() service is called and the transaction details are recorded.

You can reverse a cancelled order by calling the returned() service.

There are also services available to look up the TIC codes available in the TaxCloud system. The Taxability Identifier Codes define the type of product being sold so that the correct tax can be applied. More information is available at:


The lib directory contains a number of 'services' which makes it easy to call the TaxCloud services. Each service represents one of the web services described above. They can be called from any point in your application by passing in a few parameters. All the required classes are included.


The included RSpec tests demonstrate how to use the services. You will need to configure your TaxCloud API ID, API Key and USPS ID in helper.rb to run the tests.


You can contact [email protected] with any questions you may have.

Description of Contents

|-- lib
|   |-- response
|   |-- service
|   |--
|-- spec
|   |-- service


Includes TaxCloud specific classes, service classes and example response classes.


Unit tests which demonstrate how to integrate with the TaxCloud services.