Getting Rates with TaxCloud

If you’re looking to retrieve accurate sales tax rates without capturing orders in TaxCloud for tax filing, follow this guide. However, if you are calculating tax rates for orders that need to be captured for filing, see Standard Checkout Flow Integration.

TaxCloud does not currently offer a standalone tax rate lookup endpoint. Instead, TaxCloud uses a cart-based model, which calculates tax dynamically based on the line items and shipping destination. You can simulate a tax calculation by creating a cart, retrieving the tax result, and then abandon the simulated cart. There is no need to convert it into an order if you’re just looking up rates.

This is the recommended and supported method for rate lookup, estimation, and pre-checkout tax previewing.

When and Why to Use This Flow

Use this flow when you:

• Want to show the customer estimated tax before they complete the checkout.
• Need to calculate the correct rate based on product types and destination jurisdictions.
• Don’t intend to capture or report the transaction yet.

Important: Since there’s no standalone endpoint like /rates, this is the only supported way to get accurate, jurisdiction-specific tax estimates from TaxCloud.

Step 1: Create a Cart to Simulate the Transaction

To get a tax rate, simulate a purchase using the Cart API.

This step requires:

• A Cart ID – can be any unique string.
• A Customer ID – also a unique identifier (use “guest” if you don’t have one).
• An array of line items – include price, quantity, and (optionally) TIC codes.
• A destination address – used to determine the tax jurisdiction.

Example Request

1
curl -X POST https://api.v3.taxcloud.com/tax/connections/<connectionID>/carts \
2
     -H "X-API-KEY: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "items": [
6
    {
7
      "currency": {},
8
      "customerId": "customer-453",
9
      "destination": {
10
        "city": "Minneapolis",
11
        "line1": "323 Washington Ave N",
12
        "state": "MN",
13
        "zip": "55401-2427"
14
      },
15
      "lineItems": [
16
        {
17
          "index": 0,
18
          "itemId": "item-1",
19
          "price": 10.75,
20
          "quantity": 1.5
21
        }
22
      ],
23
      "origin": {
24
        "city": "Minneapolis",
25
        "line1": "323 Washington Ave N",
26
        "state": "MN",
27
        "zip": "55401-2427"
28
      }
29
    }
30
  ]
31
}'

Note: If all your products are taxable, use tic: “0” for simplicity. For more accurate calculations, especially for digital goods, clothing, or exempt items, set the appropriate TIC code.

Step 2: Use a Minimal Address (If Needed)

If you’re in an early stage of checkout and don’t have a full address yet, you can still perform a rate lookup using a partial address. The verify address endpoint can help validate this address.

Set “unknown” for fields like address1 or city, but be sure to include state and zip5.

1
"destination": {
2
  "address1": "unknown",
3
  "address2": "unknown",
4
  "city": "unknown",
5
  "state": "CA",
6
  "zip5": "94103"
7
}

TaxCloud will still use this to determine the correct tax jurisdiction. This is especially useful for calculating a default estimate before the user completes their shipping information.

Step 3: Handling Discounts

When offering discounts, you need to make sure the discounted price is reflected in the cart, or the tax amount will be overstated. Please see our handling discount guide here on how to reflect your discounts for the line items or overall cart items.

Step 4**:** Interpreting the Tax Result

Once you send the cart, TaxCloud will return:

• TotalAmount**:** The net price of taxable goods.

• SalesTaxAmount**:** The calculated tax.

• EffectiveRate**:** The derived rate (tax amount ÷ total amount).

These values are usually included in the CreateCart response.

1
{
2
  "amount": 40.00,
3
  "rate": 0.0825
4
}

You can now use this data to:

• Display estimated tax on the checkout page.
• Inform order summaries or invoices.
• Run custom logic (e.g., free shipping if tax is low, etc.).

Best Practices

• Always use real destination ZIP code and state combination to get accurate results. Providing a zip code that is not in your specified state will return an error.
• Use TICs if you’re selling a mix of taxable and non-taxable items.
• If you’re only estimating, do not convert the cart into an order; just abandon it.
• When applying discounts, ensure the final taxable amount reflects the discounted price.
• If you use multiple discounts, aggregate them carefully to avoid rounding issues.

There’s no need to convert a cart to an order. This flow is designed to support accurate tax lookups even during early checkout or estimation stages. This approach ensures you stay compliant and deliver a tax-inclusive user experience, all while using the current capabilities of the TaxCloud platform.