Merchant Compliance

Cart Tax Calculation

Calculate sales tax for a cart of items on behalf of a connected merchant.

Calculate the tax due on a cart of items for one of your connected merchants. Use this before you record an order so you can display an accurate tax total at checkout. The calculation reflects the merchant’s own compliance configuration (registrations, product rules, and exemptions).

This is the merchant-scoped cart calculation at /merchant/cart/calculate. It is different from the general-purpose /calculate/cart rate-lookup endpoint, which is not tied to a merchant.

Endpoint

1POST https://api.zip-tax.com/merchant/cart/calculate

Request body

FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant whose TaxCloud connection is used. Must be owned by the calling account. Consumed for routing and not forwarded.
itemsarray of CartYesThe carts to calculate tax for (1–100). Most integrations send a single cart.
transactionDatestring (RFC3339 date-time)NoThe datetime the carts are calculated for, e.g. 2026-07-13T14:00:00Z. Defaults to the current time.

Cart object

FieldTypeRequiredDescription
cartIdstring (1–50 chars)NoYour identifier for this cart. If omitted, one is generated and returned; either way, pass it to order/create-from-cart to record the sale.
customerIdstring (1–50 chars)YesYour identifier for the customer in your own system. Used to match exemption certificates and order history.
originAddressYesThe ship-from address of the sale. Used with destination to determine sourcing and the applicable jurisdictions.
destinationAddressYesThe ship-to address of the sale. Tax is generally calculated for this address in destination-sourced states.
currencyobjectYes{ "currencyCode": "USD" }. The currency object itself is required; the inner currencyCode (ISO 4217 code the prices are denominated in, USD or CAD) defaults to USD when omitted.
lineItemsarray of Line itemYesThe line items in the cart. Tax is calculated and returned per item.
deliveredBySellerbooleanNoWhether the seller delivers the order directly (own vehicles) rather than via common carrier. Affects taxability of delivery charges in some states.
discountsDiscountsNoOptional line-item and order-level discounts. If omitted, prices are used as is.
exemptionobjectNo{ "exemptionId": "...", "isExempt": true }. Reference an exemption certificate by id (isExempt is then assumed true), or set isExempt directly.

Address object

FieldTypeRequiredDescription
line1string (1–128 chars)YesFirst line of the address: street number and name, PO Box, or building. Values longer than 50 characters are truncated.
line2string (max 128 chars)NoSecond line, if any (apartment, suite, unit). Values longer than 50 characters are truncated.
citystring (1–50 chars)YesCity or post-town.
statestringYesTwo-letter state or province abbreviation, e.g. MN, CA, ON.
zipstring (1–16 chars)YesPostal or ZIP code. Five-digit (55401) and ZIP+4 (55401-2427) formats are accepted.
countryCodestringNoISO 3166-1 alpha-2 country code: US or CA. Defaults to US.

Line item object

FieldTypeRequiredDescription
indexinteger (0–500)YesZero-based position of the item within the cart. Each item must have a unique index.
itemIdstring (1–50 chars)YesYour unique identifier for the line item (e.g. SKU or line reference). Used to match items in later order, refund, and discount operations.
pricenumber (≥ 0)YesUnit price of the item in the cart’s currency. When discounts are provided, this must be the pre-discount (original) price.
quantitynumber (0–99999.9999)YesQuantity of the item. Fractional quantities are allowed. For larger quantities, send a single line with quantity 1 and the extended (total) amount as the price.
ticinteger (0–100000)NoTaxability Information Code classifying the product for product-specific tax rules (e.g. 11010 for shipping). Defaults to 0 (general tangible goods).
productIdstringNoID of the product in the merchant’s TaxCloud product catalog. Must match an existing catalog product when provided.

Discounts object

FieldTypeRequiredDescription
lineItemDiscountsarrayNoDiscounts applied to specific line items, before any order-level discount. Each entry is { "itemId": "...", "type": "percentage" | "amount", "value": 0.1 } and must reference a valid itemId from lineItems.
orderDiscountobjectNo{ "type": "percentage" | "amount", "value": 0.1 }. Applied to the whole order after line-item discounts. Shipping items (TICs 11010–11015) and Colorado retail delivery fees (TIC 11098) are excluded.

For percentage discounts, value is a decimal fraction between 0 and 1 (0.1 = 10% off); for amount discounts it is a fixed currency amount. When you provide discounts, line-item prices must be pre-discount originals — if your prices are already discounted, omit the discounts field.

Example

$curl -X POST "https://api.zip-tax.com/merchant/cart/calculate" \
>  -H "X-API-KEY: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
>    "transactionDate": "2026-07-13T14:00:00Z",
>    "items": [
>      {
>        "cartId": "cart-2026-000123",
>        "customerId": "customer-453",
>        "currency": { "currencyCode": "USD" },
>        "origin": { "line1": "1 Market St", "city": "San Francisco", "state": "CA", "zip": "94105" },
>        "destination": { "line1": "200 Spectrum Center Dr", "city": "Irvine", "state": "CA", "zip": "92618" },
>        "lineItems": [
>          { "index": 0, "itemId": "sku-1001", "price": 49.99, "quantity": 2, "tic": 0 }
>        ]
>      }
>    ]
>  }'

Response

Returns the calculated carts with tax computed per line item.

FieldTypeDescription
connectionIdstringThe TaxCloud connection the calculation ran under.
transactionDatestring (RFC3339 date-time)The datetime the carts were calculated for.
itemsarrayOne calculated cart per submitted cart, in the same order.
items[].cartIdstringIdentifier of the calculated cart. Pass it to order/create-from-cart.
items[].customerIdstringYour customer identifier, as submitted.
items[].deliveredBySellerbooleanWhether the seller delivers the order directly, as submitted.
items[].origin / items[].destinationAddressThe addresses, as submitted.
items[].exemptionobjectThe exemption information applied to the calculation.
items[].currencyobjectThe currency the prices and tax amounts are denominated in.
items[].lineItems[].indexintegerZero-based position of the item within the cart.
items[].lineItems[].itemIdstringYour line item identifier, as submitted.
items[].lineItems[].ticinteger or nullThe TIC the item was calculated under.
items[].lineItems[].pricenumberThe unit price tax was calculated on (discounted, when discounts applied).
items[].lineItems[].originalPricenumberThe original pre-discount unit price, as submitted.
items[].lineItems[].quantitynumberQuantity of the item.
items[].lineItems[].tax.ratenumberThe combined tax rate applied, as a decimal fraction (e.g. 0.08125 = 8.125%).
items[].lineItems[].tax.amountnumberThe calculated tax amount for the line item.
1{
2  "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
3  "transactionDate": "2026-07-13T14:00:00Z",
4  "items": [
5    {
6      "cartId": "cart-2026-000123",
7      "customerId": "customer-453",
8      "deliveredBySeller": false,
9      "origin": { "line1": "1 Market St", "city": "San Francisco", "state": "CA", "zip": "94105", "countryCode": "US" },
10      "destination": { "line1": "200 Spectrum Center Dr", "city": "Irvine", "state": "CA", "zip": "92618", "countryCode": "US" },
11      "exemption": { "exemptionId": null, "isExempt": null },
12      "currency": { "currencyCode": "USD" },
13      "lineItems": [
14        {
15          "index": 0,
16          "itemId": "sku-1001",
17          "tic": 0,
18          "price": 49.99,
19          "originalPrice": 49.99,
20          "quantity": 2,
21          "tax": { "rate": 0.0775, "amount": 7.75 }
22        }
23      ]
24    }
25  ]
26}

If you do not receive a response, it is safe to call cart/calculate again, calculation has no lasting side effect. Do not, however, retry order or refund writes blindly. See Retries and idempotency.

Orders

Turn a calculated cart into a recorded order.

Merchant Transactions

Shared conventions, errors, and usage.