Lookup Sales Tax

Getting a rate is only part of the job: every request also has to account for jurisdiction boundaries, product-specific tax rules, exemption certificates, holidays, rounding rules and price thresholds. Handling that detail by hand is tedious and easy to get wrong.

The Lookup API solves this by taking an origin address, a destination address, and the cart contents, then returning the exact sales-tax breakdown required for that transaction at that moment. You supply the data; TaxCloud layers on the statutes and returns a ready-to-use result.

This guide walks you through using the Lookup endpoint: authenticating, structuring a request, reading the response, and integrating the call into your checkout flow.

Lookup API Required Parameters

As with all TaxCloud API operations, a valid set of API Credentials are required. You can find your API Credentials in the TaxCloud > Integrations > Integration Name area after signing into TaxCloud.

Lookup API Optional Parameter for Exemption Certificates

TaxCloud supports Exemption Certificates for sales tax exempt entities (schools, churches, governments, non-profits, etc.) as well as sales tax exempt uses (purchase for resale, farming, etc.). Our Lookup API includes an optional exemptCert object parameter. This object parameter can have either:

• A CertificateID property (to apply a previously saved Exemption Certificate from our AddExemptionCertificate API, usually the preferred approach), or;

• A complete Detail property to create a new Exemption Certificate at the time of Lookup.

What is a customerID?

Every Lookup request requires an immutable customer identifier. It is important that this unique customer identifier is sufficient for you to identify the underlying account holder during an audit.

The customerID (unique customer identifier) should not be your customer’s email address or any other piece of Personally Identifiable Information (PII).

A unique customer identifier may not be programmatically available in the first steps of a checkout/order sequence because most commerce platforms do not expose a unique customer identifier until a customer has authenticated (signed in). Most commerce platforms return a “-1” customer identifier if a session has not been authenticated. If your commerce platform restricts programmatic access to a unique customer identifier until after customer sign-in, you must remember to perform a new Lookup request after customer sign-in, using the updated actual unique customer identifier.

What is a cartID?

TaxCloud requires a customer’s shopping cart to be assigned a unique identifier before checkout. That way, TaxCloud can later connect the right Lookup with the right customer shopping cart. This cart identifier (cartID) should be used throughout a customer’s shopping experience, including checkout.

Explicit cartID (Preferred)

An Explicit CartID is usually the unique identifier automatically generated by the shopping cart system when a new customer cart is created. If the shopping cart does not automatically create an identifier, you can use any GUID-generating algorithm to create one. There are two requirements for implementing Explicit CartIDs:

1. The shopping cart system must generate a unique cart identifier before a transaction is completed.

2. You must have the ability to persist (via server-side database or client-side cookie) and reassociate the cartID for each unique customer session.

3. The cardID must always be under 50 characters.

Passive cartID

If the shopping cart system is unable to supply a unique identifier before checkout, the initial lookup can simply omit the cartID parameter and our Lookup API will provide a unique CartID in the Response for the shopping cart system to use in all subsequent requests for the customer’s checkout sequence. The only requirement for implementing Passive CartIDs is that the shopping cart system must have the ability to persist (via server-side database or client-side cookie) and reassociate such cartID for each unique customer session.

What is an Address object?

TaxCloud requires both an origin and a destination address for all Lookup API requests. We understand this may add some complexity to your implementation, but this requirement is necessary to ensure accurate tax calculations based on current compliance standards.

In the US, all interstate (crossing state borders) commerce transactions enjoy consistent tax sourcing rules to the destination of the transaction (the buyer’s shipping address, or billing address for digital goods)—this is called destination sourcing. However, for intrastate (within a single state) transactions, a handful of states source the tax jurisdiction to the origin of the transaction—this is called origin sourcing.

TaxCloud automatically applies the correct tax sourcing rules for each state, so you don’t need to implement them yourself. To do this, the Lookup API requires both the origin and destination addresses. Each address object must be included in the request and provides the following properties:

Example

1
{
2
    "destination": {
3
        "Address1": "162 East Ave",
4
        "Address2": "Third Floor",
5
        "City": "Norwalk",
6
        "State": "CT",
7
        "Zip5": "06851",
8
        "Zip4": "5715"
9
    }
10
}

Important Note About State Abbreviations

It is very important to only pass in two-character state abbreviations in the address objects of a Lookup API request. If you pass in a full state name (for example, “New York” or “South Carolina”) that value will be truncated to the first two characters. Using the examples cited above, “New York” would be truncated to “NE” which is Nebraska, while “South Carolina” would be truncated to “SO” which is not a US state.

If you use our VerifyAddress API, it will automatically correct/update complete state names with the appropriate two-character abbreviation.

The current TaxCloud API does not manage sales tax for non-US jurisdictions. Please do not send VerifyAddress or Lookup requests for non-US destinations.

What is a cartItem?

TaxCloud uses a shopping cart metaphor for orders and order items. When a customer selects an item to purchase, she puts that item in her shopping cart when she presses the “Add to Order” button. Each item in her shopping cart is a unique cart item.

Example

1
{
2
    "cartItems":[
3
        {
4
            "Index": 0,
5
            "ItemID": "prod23523",
6
            "TIC": 20010,
7
            "Price": 21.95,
8
            "Qty": 3
9
        },
10
        {
11
            "Index": 1,
12
            "ItemID": "shipping",
13
            "TIC": 10010,
14
            "Price": 8.45,
15
            "Qty": 1
16
        }
17
    ]
18
}

ItemID ADVISORY:

ItemID values should be the abstract unique identifier assigned to products by your commerce platform or order management system. ItemID values should not be product details, such as a product name or book title.

Why?

ItemIDs are used in conjunction with the assigned TIC during tax audits to determine if a particular product (or service) was properly taxed. ItemIDs should not reveal customer-sensitive information (such as a book title) because your customers’ purchasing activities should be protected from government scrutiny beyond category of goods. As Federal District Court Judge Marsha Pechman wrote in an October 2010 ruling in Amazon v. North Carolina:

The First Amendment protects a buyer from having the expressive content of her purchase of books, music, and audiovisual materials disclosed to the government. Citizens are entitled to receive information and ideas through books, films, and other expressive materials anonymously… The fear of government tracking and censoring one’s reading, listening, and viewing choices chills the exercise of First Amendment rights.

Essentially, for sales tax purposes, states can either obtain:

• Customer Product/Purchase Details, or

• Customer Delivery Address Information

But they cannot get both at the same time. Since address information is inherently required for accurate sales tax sourcing, the state cannot seek product details beyond basic tax category (represented by our TaxCloud TICs).

Example request and response

Request

HTTPS POST api.taxcloud.net/1.0/TaxCloud/Lookup

1
{
2
    "apiLoginID": "XXXXXXX",
3
    "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
    "customerID": "WonderfulCustomer33",
5
    "deliveredBySeller": false,
6
    "destination": {
7
        "Address1": "255 S King St",
8
        "Address2": "18th Floor",
9
        "City": "Seattle",
10
        "State": "WA",
11
        "Zip5": 98104,
12
        "Zip4": 2832
13
    },
14
    "origin": {
15
        "Address1": "162 East Ave # 3",
16
        "City": "Norwalk",
17
        "State": "CT",
18
        "Zip5": 06851,
19
        "Zip4": 5715
20
    },
21
    "cartItems": [
22
        {
23
            "Index": 0,
24
            "ItemID": "prod23523",
25
            "TIC": 20010,
26
            "Price": 21.95,
27
            "Qty": 3
28
        },
29
        {
30
            "Index": 1,
31
            "ItemID": "shipping",
32
            "TIC": 10010,
33
            "Price": 8.45,
34
            "Qty": 1
35
        }
36
    ]
37
}

Response (success)

1
{
2
  "CartID": "B0DABCEE-34EE-4A76-B4C5-B5F32F430B74",
3
  "CartItemsResponse": [
4
    {
5
      "CartItemIndex": 0,
6
      "TaxAmount": 6.65
7
    },
8
    {
9
      "CartItemIndex": 1,
10
      "TaxAmount": 0.85
11
    }
12
  ],
13
  "ResponseType": 3,
14
  "Messages": []
15
}

Response (error)

1
{
2
  "CartID": null,
3
  "CartItemsResponse": [],
4
  "ResponseType": 0,
5
  "Messages": [
6
    {
7
      "ResponseType": 0,
8
      "Message": "The Ship To zip code (98104) is not valid for this state (AL)"
9
    }
10
  ]
11
}

About ResponseTypes and Messages

ResponseType 3 = SUCCESS. If the ResponseType is anything other than 3, the request has failed and your commerce platform should log all errors, not just for development purposes, but more importantly for audit purposes. If the ResponseType is not 3, TaxCloud will provide a Message which will be either a single string message, or an array of string messages. All response messages should be added to your commerce platform error log, and may optionally be presented to the customer.

What’s Next?

After determining the amount of sales tax to collect, the next step is to notify TaxCloud that an order has been Authorized, then Captured, or in a single API call AuthorizedWithCapture. You can proceed to our next guide: Order Completion: The Most Important Step, or you go directly to the AuthorizedWithCapture API documentation.