> 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. # Create Exemption Certificate POST https://api.zip-tax.com/merchant/cert/create Content-Type: application/json Available on Enterprise PlanForwards to TaxCloud POST /connections/\{connectionId}/exemption-certificates. All certificate fields other than merchantId are relayed unchanged. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate. Reference: https://docs.zip.tax/api-reference/merchant-transactions-tax-cloud/merchant-cert-create ## Authentication - `X-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects an object. - `address` (TaxCloudAddress, required) — Address of the exempt customer. - `customerBusinessType` (enum, required) — The type of business the customer is. - Allowed values: `AccommodationAndFoodServices`, `AgriculturalForestryFishingHunting`, `Construction`, `FinanceAndInsurance`, `InformationPublishingAndCommunications`, `Manufacturing`, `Mining`, `RealEstate`, `RentalAndLeasing`, `RetailTrade`, `TransportationAndWarehousing`, `Utilities`, `WholesaleTrade`, `BusinessServices`, `ProfessionalServices`, `EducationAndHealthCareServices`, `NonprofitOrganization`, `Government`, `NotABusiness`, `Other` - `customerId` (string, required) — Your identifier for the exempt customer. Carts and orders submitted with this customerId can use the certificate. - `customerName` (string, required) — Name of the customer or organization the certificate is issued to. - `merchantId` (string, required) — UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud. - `reason` (enum, required) — The reason the customer is exempt from sales tax. - Allowed values: `FederalGovernment`, `StateOrLocalGovernment`, `TribalGovernment`, `ForeignDiplomat`, `CharitableOrganization`, `EducationalOrganization`, `Resale`, `AgriculturalProduction`, `IndustrialProductionOrManufacturing`, `DirectPayPermit`, `DirectMail`, `Other`, `ReligiousOrganization` - `reasonDescription` (string, required) — Short free-text elaboration of the exemption reason (maximum 20 characters). - `states` (list of TaxCloudExemptState, required) — The states the certificate is valid in, each as a two-letter abbreviation object. - `customerBusinessDescription` (string, optional) — Free-text description of the business. Provide when customerBusinessType is Other. ## Response ### 200 TaxCloud response relayed verbatim. - `accountId` (long, required) — The TaxCloud account id the certificate belongs to. - `address` (TaxCloudAddress, required) — Address of the exempt customer. - `certificateId` (string, required) — TaxCloud's identifier for the exemption certificate. Use it with /merchant/cert/get, /merchant/cert/delete, and as exemptionId on carts and orders. - `connectionId` (string, required) — The TaxCloud connection the certificate belongs to. - `createdDate` (datetime, required) — RFC3339 datetime the certificate was created. - `customerBusinessType` (string, required) — The type of business the customer is (e.g. RetailTrade, Government, NonprofitOrganization). - `customerId` (string, required) — Your identifier for the exempt customer. - `customerName` (string, required) — Name of the customer the certificate was issued to. - `reason` (string, required) — The reason the customer is exempt (e.g. Resale, FederalGovernment, CharitableOrganization). - `reasonDescription` (string, required) — Free-text elaboration of the exemption reason. - `singlePurchase` (boolean, required) — Whether the certificate covers a single purchase only, rather than being a blanket certificate. - `customerBusinessDescription` (string, optional) — Free-text description of the business, present when customerBusinessType is Other. - `disabledAt` (datetime, optional) — RFC3339 datetime the certificate was disabled, or null while it is active. - `states` (list of TaxCloudExemptState, optional) — The states the certificate is valid in. ## Errors ### 400 Merchant Cert Create Body Bad Request Error Bad Request - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 401 Merchant Cert Create Body Unauthorized Error Unauthorized - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 403 Merchant Cert Create Body Forbidden Error Forbidden - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 404 Merchant Cert Create Body Not Found Error Not Found - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 413 Merchant Cert Create Body Content Too Large Error Request Entity Too Large - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 422 Merchant Cert Create Body Unprocessable Entity Error Unprocessable Entity - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 429 Merchant Cert Create Body Too Many Requests Error Too Many Requests - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 500 Merchant Cert Create Body Internal Server Error Internal Server Error - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 502 Merchant Cert Create Body Bad Gateway Error Bad Gateway - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 504 Merchant Cert Create Body Gateway Timeout Error Gateway Timeout - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ## Types ### TaxCloudAddress - `city` (string, required) — City or post-town of the address. - `line1` (string, required) — First line of the address: street number and name, PO Box, or building. Values longer than 50 characters are automatically truncated by TaxCloud. - `state` (string, required) — State, province, or other large territorial division, as a two-letter abbreviation (e.g. MN, CA, ON). - `zip` (string, required) — Postal or ZIP code. Five-digit (55401) and ZIP+4 (55401-2427) formats are accepted for US addresses. - `countryCode` (enum, optional, default: US) — ISO 3166-1 alpha-2 country code of the address. US (United States) or CA (Canada). Defaults to US when omitted. - Allowed values: `US`, `CA` - `line2` (string, optional) — Second line of the address, if any (e.g. apartment, suite, or unit number). Values longer than 50 characters are automatically truncated by TaxCloud. ### TaxCloudExemptState - `abbreviation` (string, required) — Two-letter abbreviation of a state the exemption certificate is valid in. ### ErrorDetail - `location` (string, optional) — Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' - `message` (string, optional) — Error message text - `value` (any, optional) — The value at the given location ## Examples **Request** ```json { "address": { "city": "Minneapolis", "line1": "323 Washington Ave N", "state": "MN", "zip": "55401-2427" }, "customerBusinessType": "AccommodationAndFoodServices", "customerId": "customer-453", "customerName": "Mr. Francis Exempt", "merchantId": "merchantId", "reason": "FederalGovernment", "reasonDescription": "reasonDescription", "states": [ { "abbreviation": "MN" } ] } ``` **Response** ```json { "accountId": 1000000, "address": { "city": "Minneapolis", "line1": "323 Washington Ave N", "state": "MN", "zip": "55401-2427", "countryCode": "US", "line2": "line2" }, "certificateId": "certificateId", "connectionId": "connectionId", "createdDate": "2024-08-01T14:00:00Z", "customerBusinessType": "customerBusinessType", "customerId": "customerId", "customerName": "Mr. Francis Exempt", "reason": "Resale", "reasonDescription": "reasonDescription", "singlePurchase": true, "customerBusinessDescription": "customerBusinessDescription", "disabledAt": "2024-01-15T09:30:00Z", "states": [ { "abbreviation": "MN" } ] } ``` **SDK Code** ```python import requests url = "https://api.zip-tax.com/merchant/cert/create" payload = { "address": { "city": "Minneapolis", "line1": "323 Washington Ave N", "state": "MN", "zip": "55401-2427" }, "customerBusinessType": "AccommodationAndFoodServices", "customerId": "customer-453", "customerName": "Mr. Francis Exempt", "merchantId": "merchantId", "reason": "FederalGovernment", "reasonDescription": "reasonDescription", "states": [{ "abbreviation": "MN" }] } headers = { "X-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.zip-tax.com/merchant/cert/create'; const options = { method: 'POST', headers: {'X-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"address":{"city":"Minneapolis","line1":"323 Washington Ave N","state":"MN","zip":"55401-2427"},"customerBusinessType":"AccommodationAndFoodServices","customerId":"customer-453","customerName":"Mr. Francis Exempt","merchantId":"merchantId","reason":"FederalGovernment","reasonDescription":"reasonDescription","states":[{"abbreviation":"MN"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.zip-tax.com/merchant/cert/create" payload := strings.NewReader("{\n \"address\": {\n \"city\": \"Minneapolis\",\n \"line1\": \"323 Washington Ave N\",\n \"state\": \"MN\",\n \"zip\": \"55401-2427\"\n },\n \"customerBusinessType\": \"AccommodationAndFoodServices\",\n \"customerId\": \"customer-453\",\n \"customerName\": \"Mr. Francis Exempt\",\n \"merchantId\": \"merchantId\",\n \"reason\": \"FederalGovernment\",\n \"reasonDescription\": \"reasonDescription\",\n \"states\": [\n {\n \"abbreviation\": \"MN\"\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-KEY", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.zip-tax.com/merchant/cert/create") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"address\": {\n \"city\": \"Minneapolis\",\n \"line1\": \"323 Washington Ave N\",\n \"state\": \"MN\",\n \"zip\": \"55401-2427\"\n },\n \"customerBusinessType\": \"AccommodationAndFoodServices\",\n \"customerId\": \"customer-453\",\n \"customerName\": \"Mr. Francis Exempt\",\n \"merchantId\": \"merchantId\",\n \"reason\": \"FederalGovernment\",\n \"reasonDescription\": \"reasonDescription\",\n \"states\": [\n {\n \"abbreviation\": \"MN\"\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.zip-tax.com/merchant/cert/create") .header("X-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"address\": {\n \"city\": \"Minneapolis\",\n \"line1\": \"323 Washington Ave N\",\n \"state\": \"MN\",\n \"zip\": \"55401-2427\"\n },\n \"customerBusinessType\": \"AccommodationAndFoodServices\",\n \"customerId\": \"customer-453\",\n \"customerName\": \"Mr. Francis Exempt\",\n \"merchantId\": \"merchantId\",\n \"reason\": \"FederalGovernment\",\n \"reasonDescription\": \"reasonDescription\",\n \"states\": [\n {\n \"abbreviation\": \"MN\"\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.zip-tax.com/merchant/cert/create', [ 'body' => '{ "address": { "city": "Minneapolis", "line1": "323 Washington Ave N", "state": "MN", "zip": "55401-2427" }, "customerBusinessType": "AccommodationAndFoodServices", "customerId": "customer-453", "customerName": "Mr. Francis Exempt", "merchantId": "merchantId", "reason": "FederalGovernment", "reasonDescription": "reasonDescription", "states": [ { "abbreviation": "MN" } ] }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.zip-tax.com/merchant/cert/create"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"address\": {\n \"city\": \"Minneapolis\",\n \"line1\": \"323 Washington Ave N\",\n \"state\": \"MN\",\n \"zip\": \"55401-2427\"\n },\n \"customerBusinessType\": \"AccommodationAndFoodServices\",\n \"customerId\": \"customer-453\",\n \"customerName\": \"Mr. Francis Exempt\",\n \"merchantId\": \"merchantId\",\n \"reason\": \"FederalGovernment\",\n \"reasonDescription\": \"reasonDescription\",\n \"states\": [\n {\n \"abbreviation\": \"MN\"\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "address": [ "city": "Minneapolis", "line1": "323 Washington Ave N", "state": "MN", "zip": "55401-2427" ], "customerBusinessType": "AccommodationAndFoodServices", "customerId": "customer-453", "customerName": "Mr. Francis Exempt", "merchantId": "merchantId", "reason": "FederalGovernment", "reasonDescription": "reasonDescription", "states": [["abbreviation": "MN"]] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.zip-tax.com/merchant/cert/create")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```