Merchant Transactions

Merchant Transactions extend Merchant Management with the day-to-day tax operations your merchants need: calculating tax on a cart, recording and updating orders, storing exemption certificates, and issuing refunds. Every operation runs against a single TaxCloud-connected merchant, so your platform can drive full transaction-level compliance without asking each merchant to integrate separately.

Before you begin

You need two things:

1. A Ziptax API key. See Authentication for where to get one and how to send it.
2. A TaxCloud-connected merchant with compliance credentials on file. Create the merchant and store its credentials as described in TaxCloud-connected merchants. A merchant without valid credentials returns 404 (credentials not found) on every transaction call.

Common conventions

All Merchant Transactions endpoints share the same shape.

Test vs Live environments

Each TaxCloud-connected merchant has two environments: Live (production) and Test (sandbox). By default, every request runs against Live. To run a request against the merchant’s Test environment instead — for example, to validate your integration without creating real orders or affecting tax filings — set the X-ENV header to TEST.

$
curl -X POST "https://api.zip-tax.com/merchant/cart/calculate" \
>
  -H "X-API-KEY: YOUR_API_KEY" \
>
  -H "X-ENV: TEST" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
>
    "items": [
>
      {
>
        "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 } ]
>
      }
>
    ]
>
  }'

X-ENV accepts LIVE (the default) or TEST, and applies to every Merchant Transactions endpoint. Omit it to run against Live.

Operations

The full set of endpoints, and which merchants each one serves:

Every operation except cart calculation stores state — an order, a certificate, a refund — which a self-managed merchant has no compliance account to store it in. Those calls fail fast with 403 rather than returning a misleading 404 credentials not found.

Responses and errors

A successful call returns the requested resource as JSON (a cart calculation, an order, a certificate, or a refund).

Errors come in two shapes:

Ziptax-level errors are returned before the operation runs, when the request can’t be authorized or routed to a valid merchant. They use a simple envelope:

1
{
2
  "status": "error",
3
  "message": "merchant not found"
4
}

Operation-level errors are returned when the request reaches the compliance service but fails validation or processing. They carry more structured detail:

1
{
2
  "status": 422,
3
  "title": "Unprocessable Entity",
4
  "detail": "One or more line items are invalid.",
5
  "error": []
6
}

Usage and rate limits

Merchant Transactions are metered separately from your tax-lookup (rate request) usage. Each transaction call counts as one merchant request against your plan’s merchant allowance, and every call is subject to per-key rate limiting. Exceeding your rate returns 429 with response code 108, the same as the rest of the API. See Rate Limiting & Errors for backoff guidance.

Retries and idempotency

Read operations are safe to retry. Write operations are not retried automatically, and you should not blindly retry them either: a retried create can produce a duplicate order, certificate, or refund.

502 and 504 only arise on the TaxCloud-connected path, where Ziptax calls an upstream service. Cart calculation for a self-managed merchant has no upstream call, so those statuses never appear for it.

Related