Calculate Taxes with Cart

To display sales tax to your customers before they check out, you’ll first build a “cart” using the TaxCloud carts endpoint. This lets you send details like shipping destination, item price, and product type (TIC) and get back a precise tax calculation in real time. The estimate updates as the customer changes quantities, adds items, or enters a new address.

Each cart is a temporary record that lives until you convert it into a final order during checkout. This separation gives you flexibility: customers can add/remove items or change shipping options without triggering filing obligations; those only begin when the cart is turned into an order.

What the API expects

The POST to carts accepts a list of items, where each item represents a delivery scenario: one customer, one shipping address, one origin, one or more line items.

Here’s a simple example with a single delivery:

Sample Request (Python)

1
import requests
2
3
connection_id = "your-connection-id"
4
api_key = "your-api-key"
5
6
url = f"https://api.v3.taxcloud.com/tax/connections/{connection_id}/carts"
7
headers = {
8
    "X-API-KEY": api_key,
9
    "Content-Type": "application/json"
10
}
11
12
payload = {
13
    "items": [
14
        {
15
            "currency": { "currencyCode": "USD" },
16
            "customerId": "customer-453",
17
            "destination": {
18
                "city": "Minneapolis",
19
                "line1": "323 Washington Ave N",
20
                "state": "MN",
21
                "zip": "55401-2427"
22
            },
23
            "origin": {
24
                "city": "Minneapolis",
25
                "line1": "323 Washington Ave N",
26
                "state": "MN",
27
                "zip": "55401-2427"
28
            },
29
            "lineItems": [
30
                {
31
                    "index": 0,
32
                    "itemId": "item-1",
33
                    "price": 10.75,
34
                    "quantity": 1.5,
35
                    "tic": 0
36
                }
37
            ]
38
        }
39
    ]
40
}
41
42
response = requests.post(url, json=payload, headers=headers)
43
print(response.json())

Sample Response

1
{
2
  "connectionId": "your-connection-id",
3
  "items": [
4
    {
5
      "cartId": "ce4a…ccefdd",
6
      "customerId": "customer-453",
7
      "destination": {
8
        "city": "Minneapolis",
9
        "state": "MN",
10
        "zip": "55401"
11
      },
12
      "origin": {
13
        "city": "Minneapolis",
14
        "state": "MN"
15
      },
16
      "lineItems": [
17
        {
18
          "itemId": "item-1",
19
          "price": 10.75,
20
          "quantity": 1.5,
21
          "tax": {
22
            "rate": 0.09025,
23
            "amount": 1.46
24
          }
25
        }
26
      ]
27
    }
28
  ]
29
}

What’s happening here?

• You built a cart for a single customer with a shipping address in Minneapolis.
• You added one line item priced at $10.75, with a quantity of 1.5.
• The response returned the tax rate (9.025%) and tax amount ($1.46).

Common use cases

• Multi-line item cart: Add more entries to lineItems.
• Multi-destination shipments: Not supported within a single cart or order. Create a separate cart/order for each unique destination address.
• Mixed origins: Also not supported in a single cart or order. Create a separate cart/order for each unique origin address.
• Exempt customers: Add an exemption field at the cart level (see exemption guide).

TIC (Taxability Information Code)

Every line item includes a TIC field that tells TaxCloud what kind of product is being sold. The default tic: 0 covers most tangible personal property, but you can look up specialized TICs (e.g. clothing, food, software) in our TIC reference.

Multiple carts

You can POST several carts at once if you need to quote tax for multiple customers or buyers in one go. Each will receive its own cartID in the response.

Troubleshooting

• Got zero tax back? Make sure your destination state is active in your dashboard’s Nexus settings.
• Seeing “invalid TIC”? Double-check that the value is a valid integer from our TIC list.
• Repeated cart changes? You can keep re-sending the full cart, with all line items present, on each endpoint call. We’ll overwrite the old one.

Best practices

• Store the returned cartID so you can convert this quote into a finalized order later.
• Only completed orders are used in tax returns.
• Use different customerIDs to track separate buyers and apply exemptions properly.

Next step

If your store serves tax-exempt buyers, continue to Handling Exemptions at Checkout to attach or auto-match certificates before you finalize the sale. If all of your customers are taxable, you can skip ahead to Convert Carts to Orders once you’re comfortable with the cart response.