> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taxcloud.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taxcloud.com/_mcp/server.

# 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 working record you build as the customer shops. While it exists, you can retrieve it through the [Get Cart](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/get-cart) endpoint, and it is cached for up to 180 days from its last update. When you convert it into an order, the cart is removed and the order becomes the record. 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)

```py
import requests

connection_id = "your-connection-id"
api_key = "your-api-key"

url = f"https://api.v3.taxcloud.com/tax/connections/{connection_id}/carts"
headers = {
    "X-API-KEY": api_key,
    "Content-Type": "application/json"
}

payload = {
    "items": [
        {
            "currency": { "currencyCode": "USD" },
            "customerId": "customer-453",
            "destination": {
                "city": "Minneapolis",
                "line1": "323 Washington Ave N",
                "state": "MN",
                "zip": "55401-2427"
            },
            "origin": {
                "city": "Minneapolis",
                "line1": "323 Washington Ave N",
                "state": "MN",
                "zip": "55401-2427"
            },
            "lineItems": [
                {
                    "index": 0,
                    "itemId": "item-1",
                    "price": 10.75,
                    "quantity": 1.5,
                    "tic": 0
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

```

### Sample Response

```py
{
  "connectionId": "your-connection-id",
  "items": [
    {
      "cartId": "ce4a…ccefdd",
      "customerId": "customer-453",
      "destination": {
        "city": "Minneapolis",
        "state": "MN",
        "zip": "55401"
      },
      "origin": {
        "city": "Minneapolis",
        "state": "MN"
      },
      "lineItems": [
        {
          "itemId": "item-1",
          "price": 10.75,
          "quantity": 1.5,
          "tax": {
            "rate": 0.09025,
            "amount": 1.46
          }
        }
      ]
    }
  ]
}
```

### 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](https://docs.taxcloud.com/guides/workflows/real-time-api/handle-exemptions)).

## 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](https://app.taxcloud.com/tic).

## 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](https://docs.taxcloud.com/guides/workflows/real-time-api/handle-exemptions) 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](https://docs.taxcloud.com/guides/workflows/real-time-api/convert-carts-to-orders) once you’re comfortable with the cart response.