Self-Managed Cart Calculation

POST /merchant/cart/calculate serves both compliance models. When the merchantId you send belongs to a self-managed merchant, Ziptax calculates the tax itself with its own rate engine — no TaxCloud connection and no merchant credentials are involved. When it belongs to a TaxCloud-connected merchant, the cart is forwarded to TaxCloud instead; that path is documented in Cart Tax Calculation.

You do not choose the engine. Ziptax routes on the merchant’s compliance model, so you send the same request body either way and never branch on merchant type when building a request.

Calculation only

Self-managed cart calculation is stateless. Nothing is persisted: no cart is stored, no order can be created from the result, and no exemption certificates are held. It answers one question — how much tax is due on these line items, right now — and returns.

Every other Merchant Transactions endpoint returns 403 for a self-managed merchant:

Not supported on this path in this release:

Endpoint

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

Request body

The request contract is identical to the TaxCloud path. The limits below are the ones enforced on the self-managed path.

Cart object

Address object

US addresses only.

Line item object

Taxability codes

This is the one place where the same request body means different things for the two merchant models. On the self-managed path, tic is interpreted as a Ziptax taxability code — the same vocabulary the rate endpoints and the TIC catalog use. TaxCloud’s own codes are not interpreted here.

Shipping and handling

Whether freight and handling are taxable depends on the state the tax is sourced to. Ziptax resolves this from the state’s freight taxability rule, the same shipping.taxable value the rate endpoints return.

A non-taxable shipping line is still returned, with tax.rate and tax.amount set to 0. Do not infer non-taxability from a missing line — every line item you send comes back.

Which address the tax is based on

Ziptax picks the sourcing address from the cart’s origin and destination:

1. Origin and destination are in different states → tax is based on the destination.
2. Same state, and that state is origin-sourced (the state’s sourcingRules.value is O) → tax is based on the origin.
3. Otherwise → tax is based on the destination.

Most states are destination-sourced. A handful source intrastate sales to the origin, which is why an in-state sale can be taxed at the ship-from rate. See Collection Requirements and Nexus for background.

If one of the two addresses cannot be resolved, Ziptax falls back to the other and continues. If neither resolves, the request fails with the corresponding error code.

Rounding

For each line item:

subtotal  = price × quantity
taxAmount = subtotal × effectiveRate

Both tax.rate and tax.amount are rounded independently to 5 decimal places (half away from zero). Rates are returned as decimal fractions, so 0.08875 means 8.875%.

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": "9f4c1e2a-7b3d-4c5e-8a91-2f6b0d4e7c13",
>
    "transactionDate": "2026-08-04T14:00:00Z",
>
    "items": [
>
      {
>
        "cartId": "my-cart-1",
>
        "customerId": "customer-453",
>
        "currency": { "currencyCode": "USD" },
>
        "origin": { "line1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "state": "CA", "zip": "94043" },
>
        "destination": { "line1": "350 5th Ave", "city": "New York", "state": "NY", "zip": "10118" },
>
        "lineItems": [
>
          { "index": 0, "itemId": "sku-1", "price": 10.75, "quantity": 1.5, "tic": 0 },
>
          { "index": 1, "itemId": "ship", "price": 8.95, "quantity": 1, "tic": 10001 }
>
        ]
>
      }
>
    ]
>
  }'

Response

Returns the submitted carts with tax computed per line item.

1
{
2
  "transactionDate": "2026-08-04T14:00:00Z",
3
  "items": [
4
    {
5
      "cartId": "my-cart-1",
6
      "customerId": "customer-453",
7
      "currency": { "currencyCode": "USD" },
8
      "origin": { "line1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "state": "CA", "zip": "94043", "countryCode": "US" },
9
      "destination": { "line1": "350 5th Ave", "city": "New York", "state": "NY", "zip": "10118", "countryCode": "US" },
10
      "lineItems": [
11
        {
12
          "index": 0,
13
          "itemId": "sku-1",
14
          "tic": 0,
15
          "price": 10.75,
16
          "originalPrice": 10.75,
17
          "quantity": 1.5,
18
          "tax": { "rate": 0.08875, "amount": 1.43109 }
19
        },
20
        {
21
          "index": 1,
22
          "itemId": "ship",
23
          "tic": 10001,
24
          "price": 8.95,
25
          "originalPrice": 8.95,
26
          "quantity": 1,
27
          "tax": { "rate": 0.08875, "amount": 0.79431 }
28
        }
29
      ]
30
    }
31
  ]
32
}

How the response differs from the TaxCloud path

originalPrice is kept and set equal to price deliberately, so a parser that handles the TaxCloud response works unchanged on a self-managed response.

cartId is not durable

Nothing is stored. cartId exists so you can correlate a response with the request that produced it and trace it in your own logs. It is not a handle to a saved cart:

• You cannot pass it to order/create-from-cart — that endpoint returns 403 for self-managed merchants.
• Recalculating the same cart produces a fresh calculation, not a lookup.

If you need the tax figures later, store the response on your side.

Worked examples

Interstate sale, general goods plus shipping. Ship-from Mountain View, CA to New York, NY. The states differ, so tax is based on the destination. New York treats freight as taxable, so the shipping line is taxed at the same combined rate.

Intrastate sale in an origin-sourced state. Ship-from Austin, TX to Houston, TX. Same state, and Texas sources this sale to the origin, so the Austin rate applies even though the goods ship to Houston.

Non-taxable freight with separately stated handling. Destination in a state whose freight rule is L — freight is exempt when separately stated, but the labor portion is taxable.

Errors

A single invalid cart fails the whole request — partial results are not returned, since a checkout cannot act on a half-calculated cart. Errors identify the failing cart by cartId (or its index) and, where it applies, the itemId.

Error codes

Failures from the rate engine map to these response codes:

Usage, limits, and entitlements

Geo request limits include the standard overage allowance. See Account Metrics to track usage against your plan, and Rate Limiting & Errors for backoff guidance.

Nexus is your responsibility on this path

Deciding where a merchant must collect stays with you and the merchant. Use Nexus Management and Economic Thresholds to track where a merchant has physical or economic nexus, and call this endpoint for the states where they have determined they need to collect. See Collection Requirements and Nexus for how obligations arise.

This is the same division of responsibility as the general-purpose rate endpoints. If you want registration, filing, and remittance handled for the merchant as well, that is the TaxCloud-connected model.

Moving a merchant between models

A self-managed merchant can be invited to TaxCloud later, which converts them to the connected model. Two things change for cart calculation when that happens, and neither is retroactive:

1. The engine changes. Calculations run through TaxCloud from that point on. Rates for the same cart may differ from what the Ziptax engine returned before, which shows up as a discontinuity in your own reporting. Keep the calculation results you stored under each model distinguishable.
2. tic values change meaning. Switch shipping lines from 10001 to TaxCloud’s shipping codes when the merchant becomes connected. See Taxability codes.

Merchants are never migrated between models automatically.

Related