> This page is for version v6.0 (default).
> For other versions, use one of these documentation indexes:
> - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt
> - v5.0: https://docs.zip.tax/v-5-0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.zip.tax/llms.txt.
> To look up U.S. and Canadian sales tax rates or account usage from an AI agent or client (Claude Code, Cursor, etc.), connect to the Ziptax MCP server at https://mcp.zip-tax.com/ over Streamable HTTP, with your API key in the X-API-KEY header. Other API endpoints in these docs are REST only. Setup: https://docs.zip.tax/guides/agents-and-llms/mcp-server

# Exempt a Sale

You can use a customer's [exemption certificate](exemption-certificates) when
you calculate cart tax or create an order.

* [Cart calculation](#exempt-a-cart) (`POST /merchant/cart/calculate`) for
  self-managed and TaxCloud-connected merchants.
* [Order creation](#exempt-an-order) (`POST /merchant/order/create`) for
  TaxCloud-connected merchants.
* [Rate lookups](#see-certificates-in-a-rate-lookup) (`GET /request/v60`),
  which report the customer's certificates but never change the rate.

## Ask for an exemption

To request an exemption, add an `exemption` object.

| Request                             | Meaning                                                                                                                                                                     |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ "exemptionId": "01a1f456-..." }` | Use a specific certificate. A Ziptax certificate must belong to the merchant and customer and cover the sale. A connected merchant can also pass a TaxCloud certificate ID. |
| `{ "isExempt": true }`              | Look for a blanket certificate that covers the sale. If no Ziptax certificate matches, self-managed carts are taxed as usual and connected carts go to TaxCloud unchanged.  |

`exemptionId` is the `certificateId` returned by
[`cert/create`](exemption-certificates#create-a-certificate). Letter case and
surrounding spaces do not matter.

Omit `exemption` to calculate tax as usual. A null or empty object,
`isExempt: false` without an ID, and a blank ID without `isExempt: true`
all leave Ziptax's exemption logic inactive.

## How a certificate is matched

Ziptax checks that its certificate covers the sale.

1. It belongs to the merchant, and its `customerId` is exactly the cart's
   `customerId`.
2. It is not disabled.
3. The evaluation date is on or after its `effectiveDate` and on or before its
   `expirationDate`, when those are set.
4. Its `states` include the sale's **destination** state. This is true even
   when the sale is taxed at the origin, such as an in-state sale in an
   origin-sourced state.
5. If it is a single-purchase certificate, it was named by `exemptionId` and its
   `orderNumber` equals the cart's `cartId` (or, on an order, the `orderId`).
   `isExempt: true` never picks a single-purchase certificate.

The **evaluation date** is the calendar day of the request's `transactionDate`,
read in that timestamp's own UTC offset, so `2026-11-30T22:00:00-08:00` is
November 30. Without a `transactionDate`, it is today in UTC.

When `isExempt: true` finds more than one certificate, Ziptax uses the one with
the latest `effectiveDate` (a certificate with none counts as oldest), then the
lowest `certificateId`.

When a certificate applies, **the whole cart is exempt**: every line item,
including shipping and handling. Ziptax does not exempt part of a cart.

## Exempt a cart

Add `exemption` to each cart that should be exempt. This self-managed cart
uses the certificate from [Create a certificate](exemption-certificates#create-a-certificate).
A connected cart uses the same `exemption` object with TaxCloud taxability codes.

#### cURL

```bash
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-11-19T15:30:00Z",
    "items": [
      {
        "cartId": "cart-1001",
        "customerId": "customer-123",
        "currency": { "currencyCode": "USD" },
        "origin": { "line1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "state": "CA", "zip": "94043" },
        "destination": { "line1": "100 Example Ave", "city": "Reno", "state": "NV", "zip": "89501" },
        "exemption": { "exemptionId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71" },
        "lineItems": [
          { "index": 0, "itemId": "sku-1", "price": 120.00, "quantity": 2, "tic": 0 },
          { "index": 1, "itemId": "ship", "price": 15.00, "quantity": 1, "tic": 10001 }
        ]
      }
    ]
  }'
```

For a self-managed merchant, a covered cart comes back with every line at rate
`0` and amount `0`, plus an `exemption` block that says which certificate
applied:

```json
{
  "transactionDate": "2026-11-19T15:30:00Z",
  "items": [
    {
      "cartId": "cart-1001",
      "customerId": "customer-123",
      "origin": { "line1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "state": "CA", "zip": "94043", "countryCode": "US" },
      "destination": { "line1": "100 Example Ave", "city": "Reno", "state": "NV", "zip": "89501", "countryCode": "US" },
      "exemption": {
        "exemptionId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
        "isExempt": false,
        "applied": true,
        "certificateId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
        "reason": "Resale",
        "notAppliedReason": null
      },
      "currency": { "currencyCode": "USD" },
      "lineItems": [
        { "index": 0, "itemId": "sku-1", "tic": 0, "price": 120, "originalPrice": 120, "quantity": 2, "tax": { "rate": 0, "amount": 0 } },
        { "index": 1, "itemId": "ship", "tic": 10001, "price": 15, "originalPrice": 15, "quantity": 1, "tax": { "rate": 0, "amount": 0 } }
      ]
    }
  ]
}
```

### The `exemption` block in the response

A self-managed cart includes these fields when you request an exemption.
Connected carts and orders include them when Ziptax applies its own certificate
and TaxCloud returns the sale as exempt.

| Field              | Type           | Description                                                                                              |
| ------------------ | -------------- | -------------------------------------------------------------------------------------------------------- |
| `exemptionId`      | string or null | The `exemptionId` you sent, or `null`.                                                                   |
| `isExempt`         | boolean        | The `isExempt` you sent (`false` when omitted). On the TaxCloud-connected path this is TaxCloud's value. |
| `applied`          | boolean        | `true` when a certificate covered the cart and it was quoted without tax.                                |
| `certificateId`    | string or null | The certificate that applied.                                                                            |
| `reason`           | string or null | That certificate's [exemption reason](exemption-certificates#exemption-reasons).                         |
| `notAppliedReason` | string or null | Why no certificate applied, or `null` when one did.                                                      |

`notAppliedReason` values:

| Value                      | Meaning                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| `no_matching_certificate`  | No certificate for this customer matched, or the candidates failed for different reasons.   |
| `disabled`                 | The certificate is disabled.                                                                |
| `expired`                  | The evaluation date is after the certificate's `expirationDate`.                            |
| `not_effective`            | The evaluation date is before the certificate's `effectiveDate`.                            |
| `state_not_covered`        | The certificate does not list the destination state.                                        |
| `single_purchase_mismatch` | A single-purchase certificate whose `orderNumber` does not match the `cartId` or `orderId`. |

For an automatic match, send `"exemption": { "isExempt": true }` in place of the
named ID above. If no certificate matches, a self-managed cart returns `200`
with the usual tax amounts and this `exemption` block.

```json
{
  "exemption": {
    "exemptionId": null,
    "isExempt": true,
    "applied": false,
    "certificateId": null,
    "reason": null,
    "notAppliedReason": "no_matching_certificate"
  }
}
```

If you name a certificate and it fails Ziptax's checks, see [Errors](#errors).

### Self-managed merchants

* **Destination state.** The certificate is checked against the state the
  destination address resolves to, not the `state` you sent.
* **No partial results.** The whole request fails if any cart's named
  certificate does not cover it.
* **Billing.** A named certificate that is not found, belongs to another
  customer, or is disabled, expired, or not yet effective is refused before any
  address is looked up, so nothing is billed. `state_not_covered` and
  `single_purchase_mismatch` are known only after the destination is resolved,
  and that lookup is billed. A covered cart still bills its destination lookup.
* **Rate breakdown.** With `taxRateDetail=base`, each line of an exempt cart has
  `"baseRates": []`.
* **Unknown fields.** `exemption` may contain only `exemptionId` (a string) and
  `isExempt` (a boolean). Anything else returns `400`.

See [Self-Managed Cart Calculation](self-managed-cart-calculation#exemptions).

### TaxCloud-connected merchants

TaxCloud does not hold Ziptax certificates, so Ziptax decides the exemption and
tells TaxCloud only that the sale is exempt:

| You send                                                           | What Ziptax does                                                             |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `exemptionId` of a Ziptax certificate that covers the cart         | Forwards the cart to TaxCloud with `"exemption": { "isExempt": true }`.      |
| `exemptionId` of a Ziptax certificate that does not cover the cart | Returns `400 CertificateNotValid`. Nothing is sent to TaxCloud.              |
| `exemptionId` that is not a Ziptax certificate                     | Forwards the cart unchanged, so TaxCloud can apply a certificate it holds.   |
| `isExempt: true` and a Ziptax certificate covers the cart          | Forwards `"exemption": { "isExempt": true }`.                                |
| `isExempt: true` and no Ziptax certificate covers the cart         | Forwards the cart unchanged. TaxCloud may apply one of its own certificates. |

Because TaxCloud receives `isExempt: true` with no certificate id, TaxCloud
records the sale as exempt without a certificate attached ("Exempt, no
certificate"). The certificate itself stays in Ziptax.

On the connected path, the destination state is the `state` you sent. A full
state name is read as its two-letter code.

For a connected cart, use the named request above with the merchant's TaxCloud
taxability codes (for example, `11010` for shipping). If TaxCloud returns the
sale as exempt, Ziptax adds the certificate fields to TaxCloud's `exemption`
object. Requests forwarded as-is, including requests when the Ziptax certificate
store is disabled, return TaxCloud's response unchanged.

```json
{
  "exemption": {
    "exemptionId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
    "isExempt": true,
    "applied": true,
    "certificateId": "01a1f456-1688-7c3e-9b52-4d8e0f6a2c71",
    "reason": "Resale",
    "notAppliedReason": null
  }
}
```

### Record the order

For a connected merchant, create the order from the cart as usual with
[`order/create-from-cart`](orders#create-an-order-from-a-cart). That call is
forwarded unchanged: TaxCloud records the cart exactly as it was calculated,
exemption included, so you do not send the exemption again.

## Exempt an order

[`POST /merchant/order/create`](orders#create-an-order) (TaxCloud-connected
merchants only) follows the same rules as a connected cart. A single-purchase
certificate is matched against the order's `orderId`, and the evaluation date
is the order's `transactionDate`.

## See certificates in a rate lookup

Add `merchantId`, and optionally `customerId`, to a v60 rate lookup to see
which of the merchant's certificates cover the looked-up state. The response
gains an `exemptionDetail` block. Rates are never changed. See
[Exemption certificates on a rate lookup](../rest-api/by-address#exemption-certificates).

## Errors

| HTTP  | Body                                                                               | When it happens                                                                                                                                               |
| ----- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `{"status": "error", "code": "CertificateNotValid", "message": "..."}`             | A named Ziptax certificate belongs to another customer or fails the sale's checks. For self-managed carts, this also covers an ID the merchant does not hold. |
| `400` | `{"status": "error", "message": "..."}`                                            | `exemption` is not a valid object (self-managed), or the request is otherwise invalid.                                                                        |
| `500` | `{"status": "error", "message": "internal error"}`                                 | An internal error prevented the exemption check. This includes an auto-match for a customer with more than 500 stored certificates.                           |
| `503` | `{"status": "error", "message": "exemption certificate storage is not available"}` | The certificate store could not be read. The request fails. Retry with backoff.                                                                               |

On carts, the message starts with the cart's position, for example:

```json
{
  "status": "error",
  "code": "CertificateNotValid",
  "message": "items[0]: exemption certificate does not apply to this cart: state_not_covered"
}
```

A certificate that is not found, or belongs to another customer, gives
`exemption certificate not found for this customer`.

## Related

#### [Exemption Certificates](exemption-certificates)

Create, get, list, and disable certificates.

#### [Self-Managed Cart Calculation](self-managed-cart-calculation)

Cart tax for a self-managed merchant.

#### [Cart Tax Calculation](cart)

Cart tax for a TaxCloud-connected merchant.

#### [Orders](orders)

Record orders for a TaxCloud-connected merchant.