Calculate Cart Tax

curl -X POST https://api.zip-tax.com/merchant/cart/calculate \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "items": [
    {
      "currency": {},
      "customerId": "customer-453",
      "destination": {
        "city": "Minneapolis",
        "line1": "323 Washington Ave N",
        "state": "MN",
        "zip": "55401-2427"
      },
      "lineItems": [
        {
          "index": 0,
          "itemId": "item-1",
          "price": 10.75,
          "quantity": 1.5
        }
      ],
      "origin": {
        "city": "Minneapolis",
        "line1": "323 Washington Ave N",
        "state": "MN",
        "zip": "55401-2427"
      }
    }
  ],
  "merchantId": "merchantId"
}'

{
  "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
  "items": [
    {
      "cartId": "my-cart-1",
      "currency": {},
      "customerId": "customer-453",
      "deliveredBySeller": false,
      "destination": {
        "city": "Minneapolis",
        "line1": "323 Washington Ave N",
        "state": "MN",
        "zip": "55401-2427"
      },
      "exemption": {},
      "origin": {
        "city": "Minneapolis",
        "line1": "323 Washington Ave N",
        "state": "MN",
        "zip": "55401-2427"
      },
      "lineItems": [
        {
          "index": 0,
          "itemId": "item-1",
          "originalPrice": 12,
          "price": 10.75,
          "quantity": 1.5,
          "tax": {
            "amount": 1.31,
            "rate": 0.08125
          },
          "tic": 0
        }
      ]
    }
  ],
  "transactionDate": "2024-08-01T14:00:00Z"
}

Available on Enterprise Plan

Forwards a cart to TaxCloud (POST /connections/{connectionId}/carts) using the merchant’s stored credentials and returns TaxCloud’s response verbatim. Additional cart fields (items, transactionDate, destination, …) are relayed unchanged.

Authentication

X-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

itemslist of objectsRequired

The carts to calculate tax for. Most integrations send a single cart; up to 100 carts may be calculated in one call.

merchantIdstringRequired

UUID of the merchant whose TaxCloud connection is used. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud.

transactionDatedatetimeOptional

RFC3339 datetime the carts are calculated for. Defaults to the current time when omitted.

Response

TaxCloud response relayed verbatim.

connectionIdstring

The TaxCloud connection the calculation ran under.

itemslist of objects

One calculated cart per submitted cart, in the same order, with per-line-item tax rates and amounts.

transactionDatedatetime

RFC3339 datetime the carts were calculated for.

Errors

400

Merchant Cart Calculate Body Bad Request Error

401

Merchant Cart Calculate Body Unauthorized Error

403

Merchant Cart Calculate Body Forbidden Error

404

Merchant Cart Calculate Body Not Found Error

413

Merchant Cart Calculate Body Content Too Large Error

422

Merchant Cart Calculate Body Unprocessable Entity Error

429

Merchant Cart Calculate Body Too Many Requests Error

500

Merchant Cart Calculate Body Internal Server Error

502

Merchant Cart Calculate Body Bad Gateway Error

504

Merchant Cart Calculate Body Gateway Timeout Error