> 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

# Exemption Certificate Changes

Ziptax now stores new exemption certificates for both merchant types. If your
integration already calls `/merchant/cert/*` or requests exemptions on carts
and orders, review the changes below before switching over.

## What's new

* **Self-managed merchants can use certificates.** The four
  [certificate endpoints](exemption-certificates) no longer return `403` for
  self-managed merchants, and their
  [cart calculations](self-managed-cart-calculation#exemptions) accept an
  `exemption` object.
* **One store for both merchant types.** New certificates are kept in Ziptax
  for TaxCloud-connected merchants too. Nothing is written to TaxCloud.
* **Connected carts and orders apply Ziptax certificates.** When a Ziptax
  certificate covers a cart, Ziptax forwards it to TaxCloud as exempt. See
  [Exempt a Sale](exempt-a-sale#taxcloud-connected-merchants).
* **New certificate fields.** Use `orderNumber` with `singlePurchase`, set an
  `effectiveDate` or `expirationDate`, and add an `identificationNumber` for
  each state.
* **Certificate origin and status.** `source` identifies where the certificate is stored. `status` reports whether it is active, disabled, or expired.
* **Rate lookups can report certificates.** `GET /request/v60` accepts
  `merchantId` and `customerId` and returns an
  [`exemptionDetail` block](../rest-api/by-address#exemption-certificates).

## Breaking changes

| Area                           | Before                                       | Now                                                                                                                | What to do                                                                                   |
| ------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Certificate ids                | TaxCloud certificate ids                     | New certificates get a lowercase UUID                                                                              | Store `certificateId` as an opaque string up to 128 characters. Do not parse it.             |
| Existing TaxCloud certificates | Read and deleted through these endpoints     | Readable with `cert/get` and `cert/list` (`"source": "taxcloud"`); `cert/delete` returns `409`                     | Manage them in TaxCloud, or create a Ziptax certificate and disable the TaxCloud one there.  |
| List cursors                   | TaxCloud's cursor                            | A new opaque cursor                                                                                                | A cursor saved from the old list returns `400` on `cursor`. Start again from the first page. |
| List page size                 | `limit` 0–100, default `20`                  | `limit` 1–100, default `25`                                                                                        | Send `limit` explicitly if you depend on the page size.                                      |
| List sort                      | `sortBy` `createdDate` or `id`, default `id` | Creation order only. `sortBy` accepts `createdDate`, `createdAt`, or `created`; `id` returns `400`                 | Remove `sortBy: "id"`.                                                                       |
| Delete response                | `204 No Content`                             | `200` with the disabled certificate                                                                                | Accept a `200` with a body. Retrying a delete is now safe.                                   |
| Error bodies                   | TaxCloud's error body, passed through        | `{ "status", "message", "errors": [{ "field", "message" }] }` for every `400`, `{ "status", "message" }` otherwise | Update error parsing. See [Errors](exemption-certificates#errors).                           |
| TaxCloud failures              | TaxCloud's status passed through             | TaxCloud's `429` is `503`; other unexpected TaxCloud answers are `502` or `504`                                    | Retry `503` with backoff.                                                                    |
| Certificate object             | Included `connectionId` and `accountId`      | Those fields are gone. Adds `merchantId`, `status`, `source`, and the new fields above                             | See the [certificate object](exemption-certificates#certificate-object).                     |
| Validation                     | Checked by TaxCloud                          | Checked by Ziptax, every invalid field reported at once                                                            | See the field limits in [Create a certificate](exemption-certificates#create-a-certificate). |

## Certificates already in TaxCloud

Certificates created before this release stay in the merchant's TaxCloud
account. They are not copied into Ziptax.

* For a connected merchant with TaxCloud credentials on file, `cert/get` and
  `cert/list` return them, after the merchant's Ziptax certificates in a list.
  `orderNumber`, `effectiveDate`, `expirationDate`, and identification numbers
  are `null` on them.
* They are read-only through Ziptax until certificate sync with TaxCloud is
  available. `cert/delete` returns `409`.
* A cart that names one by `exemptionId` is forwarded to TaxCloud unchanged, so
  TaxCloud applies it as before.
* A self-managed merchant, or a connected merchant without TaxCloud
  credentials, has no TaxCloud certificates to read.

## Checklist

1. Treat `certificateId` as an opaque string. Expect both UUIDs and TaxCloud ids
   for connected merchants.
2. Drop saved list cursors and any `sortBy: "id"`.
3. Handle `200` with a body from `cert/delete`, and `409` for TaxCloud
   certificates.
4. Parse the new error body.
5. For self-managed merchants, stop stripping `exemption` from carts. See
   [Self-Managed Cart Calculation](self-managed-cart-calculation#exemptions).

## Related

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

The certificate endpoints in full.

#### [Exempt a Sale](exempt-a-sale)

Apply a certificate to a cart or order. Find certificates with a v60 rate lookup.