> 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. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server. # Exemption Certificates Exemption certificates record that a merchant's customer is exempt from sales tax in one or more states. Store a certificate so future orders for that customer are treated correctly, then retrieve, list, or delete certificates as needed. All operations act on a single [TaxCloud-connected merchant](taxcloud-connected-merchants) identified by `merchantId`. All endpoints use `POST` and the `X-API-KEY` header. See [Merchant Transactions](transactions) for the shared conventions, error shapes, and usage rules. > **Info** > > Exemption certificates are not available for > [self-managed merchants](self-managed-merchants) — all four operations return > `403`, and their [cart calculations](self-managed-cart-calculation) do not apply > exemptions. Handle exempt customers outside Ziptax for those merchants. ## Create a certificate ```http POST https://api.zip-tax.com/merchant/cert/create ``` | Field | Type | Required | Description | | ----------------------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `merchantId` | string (UUID) | Yes | The connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded. | | `customerId` | string | Yes | Your identifier for the exempt customer. Carts and orders submitted with this `customerId` can use the certificate. | | `customerName` | string | Yes | The customer or organization name as it appears on the certificate. | | `customerBusinessType` | string | Yes | The type of business the customer is. One of the [business type values](#business-types) below. | | `customerBusinessDescription` | string | No | Free-text description of the business. Provide when `customerBusinessType` is `Other`. | | `reason` | string | Yes | The reason for the exemption. One of the [reason values](#exemption-reasons) below. | | `reasonDescription` | string (max 20 chars) | Yes | Short free-text elaboration of the exemption reason. | | `address` | [Address](cart#address-object) | Yes | The customer's address. | | `states` | array of objects | Yes | The states the exemption applies to, each as `{ "abbreviation": "NV" }` with a two-letter state abbreviation. | ### Business types `AccommodationAndFoodServices`, `AgriculturalForestryFishingHunting`, `Construction`, `FinanceAndInsurance`, `InformationPublishingAndCommunications`, `Manufacturing`, `Mining`, `RealEstate`, `RentalAndLeasing`, `RetailTrade`, `TransportationAndWarehousing`, `Utilities`, `WholesaleTrade`, `BusinessServices`, `ProfessionalServices`, `EducationAndHealthCareServices`, `NonprofitOrganization`, `Government`, `NotABusiness`, `Other` ### Exemption reasons `FederalGovernment`, `StateOrLocalGovernment`, `TribalGovernment`, `ForeignDiplomat`, `CharitableOrganization`, `ReligiousOrganization`, `EducationalOrganization`, `Resale`, `AgriculturalProduction`, `IndustrialProductionOrManufacturing`, `DirectPayPermit`, `DirectMail`, `Other` #### cURL ```bash curl -X POST "https://api.zip-tax.com/merchant/cert/create" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "customerId": "cust-5567", "customerName": "Acme Wholesale LLC", "customerBusinessType": "WholesaleTrade", "reason": "Resale", "reasonDescription": "Purchased for resale", "address": { "line1": "500 Industrial Way", "city": "Reno", "state": "NV", "zip": "89502" }, "states": [ { "abbreviation": "NV" }, { "abbreviation": "CA" } ] }' ``` Returns the created [certificate](#certificate-response), including the `certificateId` you use to retrieve or delete it, and which you can reference as `exemptionId` on [carts](cart) and [orders](orders). ## Get a certificate Retrieve a single certificate by its id. ```http POST https://api.zip-tax.com/merchant/cert/get ``` | Field | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------------------------------- | | `merchantId` | string (UUID) | Yes | The connected merchant. | | `certificateId` | string | Yes | The `certificateId` returned when the certificate was created. | #### cURL ```bash curl -X POST "https://api.zip-tax.com/merchant/cert/get" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "certificateId": "cert_7a4b6c8e" }' ``` Returns the [certificate](#certificate-response). ## List certificates List the certificates stored for a merchant, with cursor-based pagination. ```http POST https://api.zip-tax.com/merchant/cert/list ``` | Field | Type | Required | Description | | ------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------- | | `merchantId` | string (UUID) | Yes | The connected merchant. | | `limit` | integer (0–100) | No | Maximum number of certificates per page. Defaults to `20`. | | `cursor` | string | No | Opaque pagination cursor from the `nextCursor` field of a previous response. Omit to start at the first page. | | `ascending` | boolean | No | Whether to sort results in ascending order. Defaults to `false`. | | `sortBy` | string | No | Field to sort by: `createdDate` or `id`. Defaults to `id`. | | `customerId` | string | No | Filter to certificates belonging to this customer. | | `disabled` | boolean | No | Set `true` to list disabled (deleted) certificates instead of active ones. Defaults to `false`. | Returns `{ "items": [...], "limit": 20, "nextCursor": "..." }` where each item is a [certificate](#certificate-response) and `nextCursor` is `null` on the last page. > **Info** > > `cert/get` and `cert/list` are separate endpoints: use `cert/get` to fetch one > certificate by id, and `cert/list` to enumerate a merchant's certificates. ## Delete a certificate Deletes (disables) a certificate so it can no longer be applied to new transactions. Returns `204 No Content` on success. ```http POST https://api.zip-tax.com/merchant/cert/delete ``` | Field | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------------------------------- | | `merchantId` | string (UUID) | Yes | The connected merchant. | | `certificateId` | string | Yes | The `certificateId` returned when the certificate was created. | #### cURL ```bash curl -X POST "https://api.zip-tax.com/merchant/cert/delete" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "certificateId": "cert_7a4b6c8e" }' ``` ## Certificate response `cert/create`, `cert/get`, and each `cert/list` item return the certificate record: | Field | Type | Description | | ----------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `certificateId` | string | Identifier for the certificate. Use with `cert/get`, `cert/delete`, and as `exemptionId` on carts and orders. | | `connectionId` | string | The TaxCloud connection the certificate belongs to. | | `accountId` | integer | The TaxCloud account the certificate belongs to. | | `customerId` | string | Your identifier for the exempt customer. | | `customerName` | string | Name of the customer the certificate was issued to. | | `customerBusinessType` | string | The type of business the customer is. | | `customerBusinessDescription` | string | Free-text description, present when the business type is `Other`. | | `reason` | string | The reason the customer is exempt. | | `reasonDescription` | string | Free-text elaboration of the exemption reason. | | `address` | [Address](cart#address-object) | Address of the exempt customer. | | `states[]` | array | The states the certificate is valid in, each as `{ "abbreviation": "NV" }`. | | `singlePurchase` | boolean | Whether the certificate covers a single purchase only, rather than being a blanket certificate. | | `createdDate` | string (RFC3339 date-time) | When the certificate was created. | | `disabledAt` | string (RFC3339 date-time) or null | When the certificate was disabled, or `null` while it is active. | ## Related #### [Orders](orders) Record orders that honor a customer's exemptions. #### [Merchant Transactions](transactions) Shared conventions, errors, and usage.