Calculate Cart Tax
Calculates sales tax per line item for one or more carts. The request body is the same for every merchant, and Ziptax routes on the merchant’s compliance model.
For a TaxCloud-connected merchant, the cart is forwarded to TaxCloud (POST /connections/{connectionId}/carts) using the merchant’s stored credentials, and TaxCloud’s response is returned verbatim. Additional cart fields (items, transactionDate, destination, …) are relayed unchanged. Requires credentials on file; a connected merchant without valid credentials returns 404.
For a self-managed merchant (status external_compliance), Ziptax calculates the tax in-process with its own rate engine and no TaxCloud call. Three differences matter on that path. (1) Calculation only: nothing is persisted, connectionId is omitted from the response, and the returned cartId is a correlation token that cannot be passed to /merchant/order/create-from-cart. (2) tic uses the Ziptax taxability code vocabulary, not TaxCloud’s: 10001 is shipping and 11000 is handling, while TaxCloud’s shipping codes (11010-11015) and the Colorado retail delivery fee code (11098) carry no special meaning and are taxed as ordinary product codes. (3) discounts, exemption, and deliveredBySeller are rejected with 400 rather than ignored, non-USD currency and countryCode CA are rejected, and a cart is capped at 250 line items.
Every other merchant transaction endpoint returns 403 for a self-managed merchant. See the Self-Managed Cart Calculation guide for the full contract.
Authentication
Request
The carts to calculate tax for. Most integrations send a single cart; up to 100 carts may be calculated in one call.
RFC3339 datetime the carts are calculated for. Defaults to the current time when omitted. Self-managed merchants: a transactionDate in a past month is quoted from that month’s historical rates, and product rate rules and meal tax are applied as in effect on its calendar date in its own offset; a past month whose tax_table rates the running service has not loaded uses the current tax_table rates, while SST states and other dated sources keep the month, and rate rules and meal tax stay dated on its own day; a value that is not an RFC3339 datetime, or a month older than the historical rates, is rejected with 400 before any cart is calculated.
Response
Calculated carts. For a TaxCloud-connected merchant this is TaxCloud’s response relayed verbatim; for a self-managed merchant it is the Ziptax calculation, which has no connectionId, exemption, or deliveredBySeller.