How to: Lookup Sales Tax Due

Once you have obtained a valid delivery address you are ready to easily lookup the sales tax due for your customer.

Part 1. Important Points Before We Get Started

Before we jump into the actual Lookup API, there are several critical components of determining how much sales tax to collect which we should review first:

1. First, do you collect sales tax in your customer's state?

This is an important question, but one you do not need to manage on your end because this important question is automatically managed by your TaxCloud account configuration.

2. Where are you shipping from?

This information is important for the handful of states that use what tax experts call origin sourcing (meaning, sales tax is calculated based upon where the order is shipped from). Origin sourcing is only valid or applicable when a shipment does not cross state lines.

Origin Sourcing States
Arizona Illinois Mississippi Missouri New Mexico Ohio
Pennsylvania Tennessee Texas Utah Virgina

The good news: Like the first item, you do not need to keep track of this on your side either. TaxCloud monitors and applies the various states' so-called sourcing rules automatically, but this is exactly why our Lookup API requires an Origin Address.

3. Where are you shipping to?

This is usually the most important piece of information because the Destination Address is the actual point of taxation (except for in-state transactions as mentioned above). This makes sense because the customer at the destination address is also the taxpayer that voted for their local priorities which are funded by their sales tax.

4. What category of goods are you selling?

Finally, you need to know what you are selling by category. This is important because many states exempt certain types of products from taxation. For example, the State of New York exempts Clothing from the state sales tax, but several of the counties do not exempt Clothing from their local sales tax. Shipping charges are another good example — several states exempt shipping charges from sales tax, and some states that ordinarily tax shipping reverse to non-taxable if all the items being purchased are exempt [dizzy].

The good news: Here too, TaxCloud automatically keeps track of all the states' various taxability rules (even in context of other items being purchased or occasional sales tax holidays) using what we refer to as Taxability Information Codes (or "TICs"). All you need to do is choose the category of goods that best describe what you are selling. To be clear, most things sold online are taxable, and so the default TIC is "00000": General Goods — if you cannot find a good description of your product in our TICs, then it is not likely exempt anywhere in the US, and you should use TIC 00000.

Here are a few frequently used TICs:

Frequently Used TICs
00000 General Goods [default if no TIC provided]
11010 Shipping charges (so long as the charge to your customer does not exceed the actual costs charged by your shipper)
11000 Shipping & Handling charges (if the charge to your customer exceeds the actual costs charged by your shipper)
20010 Clothing is apparel suitable for general use
20020 Clothing Accessories are incidental items worn in conjunction with clothing (like jewelry)
30070 Remotely Accessed Software such as "Cloud Computing" or SaaS web services (like TaxCloud)
30050 Prewritten Software delivered by download only (no tangible media shipped)
40030 Food Ingredients are substances sold in liquid, concentrated, solid, frozen, dried, or dehydrated form for ingestion by humans

You can review all of our TICs in our Taxability Codes area within your TaxCloud account or our Taxability Information Codes page.

Part 2. Let's Do This!

Lookup API's Main Parameters

Now that we have covered the most important factors in determining an accurate sales tax amount due, let's take a look at our main Lookup API parameters:

Parameter Description Required
apiLoginID This is your website's API ID Yes
apiKey This is your website's API KEY Yes
customerID The unique identifier for the customer entity making a purchase. This should be your system's internal identifier (usually an integer or GUID). This value should not be a value which could be used to personally identify your customer (such as an email address). Yes
deliveredBySeller (Boolean) Is this purchase going to be delivered by the seller in a seller-owned vehicle and not by common carrier (such as UPS or Fedex)? Yes
cartID The cartID is basically an order identifier, but most e-commerce systems do not issue an immutable order identifier until a customer clicks the final buy now button. This value is very important because you cannot call our Authorized or Captured APIs without providing the same cartID value from the corresponding previous Lookup. If an empty ("") cartID is provided in the Lookup request, TaxCloud will respond with a UUID/GUID which must be used in subsequent API calls for this customer's session. Yes
destination This is the destination address object that represents your customer's delivery address. For digital goods or services, this is your customer's billing/payment address. Yes
origin This is the origin address object that represents the origin address of the shipment (your store or warehouse). Yes
cartItems The cartItems object represents an array of items (each a CartItem) being purchased by the customer. Yes

The Destination & Origin Address Objects

As described above, two address objects are required for a valid Lookup API request: Destination and Origin. The objects have identical parameters:

Parameter Description Required
Address1 This is the numbered street address Yes
Address2 This is a second address line No
City This is the city name No
State This is the two character state abbreviation Yes
Zip5 This is the US zip code Yes
Zip4 This is the Plus4 zip code (Required, but can be empty) Yes

Important Advisory Number 1

Please be sure to pass in the proper two character state abbreviation (i.e., CA, NY, SC, etc.). If your implementation passes in the full state name (i.e., California, New York, South Carolina, etc.) our Lookup API will truncate the State parameter to only the first two characters.

While in many states you could get lucky and the resulting truncated two character abbreviation could actually work (California becomes CA or Massachusetts becomes MA), in several other states you will be less fortunate:

  • New York becomes NE, which is Nebraska, or
  • South Carolina becomes SO, which is either invalid or Somalia!

So, please only send valid two character state abbreviations. The good news here is that if you handed a full state name into our recommended preliminary VerifyAddress API, our VerifyAddress response automatically switches full state names into their proper two-character abbreviations.


The cartItems Object

The cartItems object represents an array of items (each a CartItem) being purchased by the customer. Each cartItem has the following parameters:

Parameter Description Required
ItemID Unique identifier (such as a SKU or GUID) used by your commerce system to uniquely identify a particular product. Yes
Index Zero-based index of the item being purchased. Zero-based means the first item in the cart has an Index of 0, the second item has an index of 1, and so on. Yes
TIC The Taxability Information Code (or TIC) appropriate for the item being purchased. If no TIC is provided, TaxCloud will respond based on the Default TIC configured for the Website in TaxCloud, or 00000 (General taxable goods) if a Default TIC has not been set. No
Price The per-item price of the item being purchased. IMPORTANT: This must be the price to be paid by the customer after application of any discounts or coupons! Yes
Qty This is the quantity count for this item — how many are being purchased? Yes

Important Advisory Number 2

The Price parameter must be the actual price to be paid by the purchaser after any discounts or coupons. This is a legal requirement because the statutory definition of "Sale Price" is:

"Sale Price" means the total amount of consideration paid by a purchaser to a seller for an item.

Sales Tax amounts due must be calculated based on the final Sale Price, after any seller-provided discounts or coupons. If your e-commerce system has any modules or mechanisms that bluntly adjust the Sale Price of any (or all) items, a new Lookup must be performed after the application of such adjustments.


Part 3. The POST

Once you have your parameters assembled, your HTTP POST to https://api.taxcloud.com/1.0/TaxCloud/Lookup is ready to go!

Here is a sample request:

 {
  "apiLoginId": "XXXXXXXXX",
  "apiKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "customerID": "CustomerX",
  "deliveredBySeller": false,
  "cartID": "",
  "destination": {
    "Address1": "162 East Ave # 3",
    "City": "Norwalk",
    "State": "CT",
    "Zip5": "06851",
    "Zip4": "5715"
  },
  "origin": {
    "Address1": "162 East Avenue",
    "City": "Norwalk",
    "State": "CT",
    "Zip5": "06851",
    "Zip4": "5715"
  },
  "cartItems": [
    {
      "Qty": 1,
      "Price": 23.00,
      "TIC": 00000,
      "ItemID": "8LA06052",
      "Index": 0
    },
    {
      "Qty": 1,
      "Price": 9.95,
      "TIC": 11010,
      "ItemID": "SHIPPING",
      "Index": 1
    }
  ]
}

Part 4. The Response

TaxCloud will respond with the CartID and a CartItemsResponse Object which is an array of responseCartItems which will each include the following items:

Key Value
CartItemIndex The CartItemIndex is equal to the Index CartItem parameter passed in.
TaxAmount This is the dollars and cents due, not the sales tax rate.

Normally, the response that comes back from TaxCloud will look like this:

{
  "CartID": "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a",
  "CartItemsResponse": [
    {
      "CartItemIndex": 0,
      "TaxAmount": 1.4605
    },
    {
      "CartItemIndex": 1,
      "TaxAmount": 0.631825
    }
  ],
  "ResponseType": 3,
  "Messages": []
}

Now your customer can complete their purchase, with the correct sales tax automatically calculated.

What About Errors?

IMPORTANT: If the Lookup response ResponseType is not 3, then there was an ERROR completing the Lookup request, and sales tax was not calculated. If there is an error, the Messages array will contain important details about why the request failed. This message should not be ignored, and the Lookup should be corrected before proceeding with the purchase/checkout process.

Part 5. What's Next?

Congratulations are in order. You have now implemented the most complicated aspect of sales tax compliance: getting the correct amount of tax to collect. This is great progress!

Let's review where we are:

  • [x] 1. Address verification (API: VerifyAddress) - Done
  • [x] 2. Tax Amount lookup (API: Lookup) - Done
  • [ ] 3. Order completion (APIs: Authorized and Captured; or AuthorizedWithCapture) - Up Next
  • [ ] 4. Merchandise returns (API: Returned) - On Deck

Next, you should proceed to our how-to guide for The Most Important Step: Order Completion.