zip.tax API Documentation

zip.tax offers an online look-up service and a developer API for sales tax data by full or partial address or geographic latitude and longitude coordinates.

## Sections
• [Getting Started](https://developers.zip.tax/introduction.md): Ziptax provides both a developer-friendly API and an online lookup tool for precise sales tax data. By using geographic inputs such as a full street address, you can instantly determine the correct sales tax rates for any customer location. The United States alone has more than 12,000 sales tax jurisdictions across 80,000+ geographic boundaries all shifting throughout the year. Door-level accuracy is essential for correct calculation and compliant filings. Ziptax delivers always-current, maintenance-free tax data so you can integrate reliable rates with confidence. Visit https://zip.tax/pricing to view our plan options. Use the documentation below to learn how to make requests in your code language »
• [Rate Request](https://developers.zip.tax/address-level-request-geo-plans.md): The Ziptax API request starts with a geographic identifier. You can provide an address , lat/lng coordinates , or simply a postal-code in the rqeuests. For address and lat/lng requests the API will return a single door-level result. When a postal-code is supplied, the API returns all applicable rates for the postal-code unadjusted for unincorporated areas or specia tax jurisdictions. For most applications a door-level rate is necessary and therefore address or lat/lng should be used. Lookup Methods: By Address By Geographic Latitude and Longitude By Postal Code
  • [By Address](https://developers.zip.tax/address-level-request-geo-plans/by-address.md): API Requests by address will respond with a single door level rate adjusted for unincorporated areas and special tax jurisdictions.
  • [By Lat / Lng](https://developers.zip.tax/address-level-request-geo-plans/by-address-copy.md): API Requests by geographic Latitiude (lat) and Longitude (lng) will respond with a single door level rate adjusted for unincorporated areas and special tax jurisdictions.
  • [By Postal Code](https://developers.zip.tax/address-level-request-geo-plans/by-address-copy-1.md): API Requests by postal code will respond with a structure similar to the v50 and prior response where multiple rates are returned for all applicable tax jurisdictions overlapping the postal code. NOTE : The postal code lookups include multiple applicable rates with no adjustments for unincorporated areas or special tax jurisdictions and will not provide an accuracy equivalent to a door-level rate. Use the Address lookup method for the most accurate rate.
• [Response Codes](https://developers.zip.tax/response-codes.md): The following table represents the application response codes returned in the response object. The table on the right is a comprehensive list of the applicable HTTP Status Codes the API may return. Title Description Response Code Name Description 100 RESPONSE_CODE_SUCCESS Successful API Request. 101 RESPONSE_CODE_INVALID_KEY Key format is not valid or key not found. 102 RESPONSE_CODE_INVALID_STATE The provided State is not in a valid format parsable by the API. 103 RESPONSE_CODE_INVALID_CITY The provided City is not in a valid format parsable by the API. 104 RESPONSE_CODE_INVALID_POSTAL_CODE The provided Postal Code is not in a valid format parsable by the API. 105 RESPONSE_CODE_INVALID_FORMAT Query string format is not valid. 106 RESPONSE_CODE_API_ERROR Unknown API error. 107 RESPONSE_CODE_FEATURE_NOT_ENABLED Requested feature or version not enabled. 108 RESPONSE_CODE_REQUEST_LIMIT_MET API request limit met. 109 RESPONSE_CODE_ADDRESS_INCOMPLETE The provided address is missing, incomplete, or not a valid address. 110 RESPONSE_CODE_NO_RESULT Query parameters valid but no result found. 111 RESPONSE_CODE_INVALID_HISTORICAL The provided historical parameter is not in a valid format. 112 RESPONSE_CODE_INTERNATIONAL_NOT_ENABLED International rates not enabled for this key. 113 RESPONSE_CODE_PRODUCT_RULES_NOT_ENABLED Product rate rules not enabled for key.
• [Product Codes](https://developers.zip.tax/product-codes.md): No matter where you sell, we offer unmatched expertise in calculating sales tax rates and provide precise Taxability Information Codes (TICs) classification for your products. Use our TIC library to properly adjust sales tax rate data for jurisdictions where items may be exempt or partially taxed. When using the taxabilityCode feature with address or lat/lng lookups, a taxability code must be sent as the parameter value. The full list of product codes can be access programmatically at: https://api.zip-tax.com/data/tic The Ziptax API offers two types of taxabilityCode search. The Product Code Search endpoint can be used to send a natural language product description to receive a full list of matches from the TIC data. Alternatively, we offer the Product Code Recommendation endpoint which can be searched using the same natural language input but the response will provide a single AI-powered TIC match.
  • [Product Code Search](https://developers.zip.tax/product-codes/product-code-search.md): The Product Code Search feature provides an API endpoint to get a list of all applicable Product Codes (TICs) based on a natural language product description. The response will return a full list of all matches, ranked and scored by reliability of result. The receive a machine-learning powered recommendation of a single code, review our Product Code Recommendation endpoint.
  • [Product Code Recommendation](https://developers.zip.tax/product-codes/product-code-recommendation.md): The Produce Code Recommendation endpoint uses the same natural language input as the standard Product Code Search with the addition of an AI-powered natural language match to a specific TIC code. This method provides the most accurate recommendation for the TIC code to assign to your product using a natural language product description.
• [Account Metrics](https://developers.zip.tax/account-metrics.md): The account metrics endpoint can be used to pull account usage metrics in real-time.
• [Language SDKs](https://developers.zip.tax/language-sdks.md): To make integrating with the ZipTax Sales Tax API as seamless as possible, we provide dedicated SDKs for the most widely used programming languages. Each SDK is designed to offer idiomatic usage patterns, built-in authentication helpers, streamlined request/response handling, and first-class support for our full tax-calculation, jurisdiction, and lookup workflows. Whether you’re building a high-throughput backend service, a serverless function, or a lightweight script, these libraries help you implement accurate sales tax logic with minimal effort. SDK Docs Go Python Node
  • [Go SDK](https://developers.zip.tax/language-sdks/go-sdk.md): The Go SDK provides a fast, type-safe client tailored for high-performance backend services. It includes well-structured request/response models, automatic handling of API keys, convenient helper functions for tax calculation and jurisdiction lookup, and native support for working with Go contexts. This SDK is ideal for microservices, concurrent processing pipelines, and any environment where efficiency and reliability are primary concerns. Use the code samples here to get started. The Go SDK is currently offered as a Beta product. Please send your comments and suggestions to support@zip.tax. Project Resources GitHub: https://github.com/ZipTax/ziptax-go Go Package: https://pkg.go.dev/github.com/ziptax/ziptax-go Implementation Example 1 Install Bash go get github.com/ziptax/ziptax-go 2 Import Go import ( "context" "fmt" "log" "os" "github.com/ziptax/ziptax-go" ) 3 Configure Client Go client, err := ziptax.NewClient( "your-api-key", ziptax.WithTimeout(60*time.Second), ziptax.WithMaxRetries(5), ziptax.WithRetryWait(2*time.Second, 60*time.Second), ) 4 Get Sales Tax by Address Go ctx := context.Background() response, err := client.GetSalesTaxByAddress(ctx, "200 Spectrum Center Drive, Irvine, CA 92618") if err != nil { log.Fatal(err) } 5 Print Result Go fmt.Printf("Address: %s\n", response.AddressDetail.NormalizedAddress) if len(response.TaxSummaries) > 0 { fmt.Printf("Total Tax Rate: %.4f%%\n", response.TaxSummaries[0].Rate*100) } Full documentation available via our GitHub Project at https://github.com/ZipTax/ziptax-go
  • [Python SDK](https://developers.zip.tax/language-sdks/python-sdk.md): The Python SDK offers a simple, intuitive interface for interacting with the ZipTax API from scripts, data pipelines, and applications. It supports both synchronous and asynchronous usage, includes built-in error handling, and integrates naturally with common Python workflows for data engineering, ETL, and backend services. This SDK is a great fit for teams working in Databricks, AWS Lambda, FastAPI, Django, or other Python-driven environments. Use the code samples here to get started. The Python SDK is currently offered as a Beta product. Please send your comments and suggestions to support@zip.tax. Project Resources GitHub: https://github.com/ZipTax/ziptax-python PyPi: https://pypi.org/project/ziptax-sdk/ Implementation Example 1 Install Bash pip install ziptax-sdk 2 Import Python from ziptax import ZipTaxClient 3 Configure Client Python # With custom configuration client = ZiptaxClient.api_key( "your-api-key-here", timeout=60, # Request timeout in seconds max_retries=5, # Maximum retry attempts retry_delay=2.0, # Base delay between retries ) 4 Get Sales Tax by Address Python # Get sales tax by address response = client.request.GetSalesTaxByAddress( "200 Spectrum Center Drive, Irvine, CA 92618" ) 5 Print the Result Python print(f"Address: {response.addressDetail.normalizedAddress}") if response.tax_summaries: for summary in response.tax_summaries: print(f"{summary.summary_name}: {summary.rate * 100:.2f}%") # Always close the client when done client.close() Full documentation available via our GitHub Project at https://github.com/ZipTax/ziptax-python
  • [Node SDK](https://developers.zip.tax/language-sdks/node-sdk.md): The Node.js SDK delivers a modern, promise-based client optimized for JavaScript and TypeScript applications. It provides ergonomic methods for tax rate lookup, jurisdiction determination, and address-level calculations, with full TypeScript type definitions for strong typing and editor autocomplete. Whether you’re building serverless API endpoints, Next.js applications, or high-volume backend services, the Node SDK makes integrating ZipTax fast and straightforward. Use the code samples here to get started. The Node SDK is currently offered as a Beta product. Please send your comments and suggestions to support@zip.tax. Project Resources GitHub: https://github.com/ZipTax/ziptax-node NPM: https://www.npmjs.com/package/@ziptax/node-sdk Implementation Example 1 Install JavaScript npm install @ziptax/node-sdk 2 Import JavaScript import { ZiptaxError, ZiptaxAPIError, ZiptaxAuthenticationError, ZiptaxValidationError, ZiptaxNetworkError, ZiptaxRateLimitError, } from '@ziptax/node-sdk'; Configure the Client JavaScript const client = new ZiptaxClient({ apiKey: 'your-api-key-here', retryOptions: { maxAttempts: 5, initialDelay: 2000, maxDelay: 30000, backoffMultiplier: 2, shouldRetry: (error, attempt) => { // Custom retry logic return attempt < 3 && error.name === 'ZiptaxNetworkError'; }, }, }); 4 Get Sales Tax by Address JavaScript // Get sales tax rate by address const result = await client.getSalesTaxByAddress({ address: '200 Spectrum Center Drive, Irvine, CA 92618', }); console.log('Total Tax Rate:', result.taxSummaries?.[0]?.rate); console.log('Base Rates:', result.baseRates); Full documentation available via our GitHub Project at https://github.com/ZipTax/ziptax-node
• [RESTful Code Samples](https://developers.zip.tax/code-samples.md): Use the code sample guides below to learn how to integrate the zip.tax API into your application's native code language. To request additional code sample langauges, please send us a message at support@zip.tax
  • [Golang](https://developers.zip.tax/code-samples/python-copy-1.md): This guide walks you through how to set up and use the zip.tax API in a Golang application. Prerequisites Before getting started, ensure you have the following: Basic knowledge of Golang. A Golang development environment. An API key. To subscribe for a new key, please choose a subscription . The guide below uses a Geo level subscription. 1 Install Required Libraries For making HTTP requests, we'll use Golang's standard net/http package. Additionally, we'll use encoding/json for parsing JSON responses. 2 Start the Golang Project Create a new project directory and initialize a new module: Bash mkdir ziptax-golang && cd ziptax-golang go mod init ziptax-golang 3 The Code Here is a complete example of a simple Golang application that queries the zip.tax API for sales tax information. Go package main import ( "encoding/json" "fmt" "log" "net/http" "net/url" ) // // ---------- Response Models for v60 ---------- // type ZipTaxResponse struct { Metadata Metadata `json:"metadata"` BaseRates []BaseRate `json:"baseRates"` Service Adjustment `json:"service"` Shipping Adjustment `json:"shipping"` SourcingRules Adjustment `json:"sourcingRules"` TaxSummaries []TaxSummary `json:"taxSummaries"` AddressDetail AddressDetailV60 `json:"addressDetail"` } type Metadata struct { Version string `json:"version"` Response MetadataResponse `json:"response"` } type MetadataResponse struct { Code int `json:"code"` Name string `json:"name"` Message string `json:"message"` Definition string `json:"definition"` } type BaseRate struct { Rate float64 `json:"rate"` JurType string `json:"jurType"` JurName string `json:"jurName"` JurDescription string `json:"jurDescription"` JurTaxCode *string `json:"jurTaxCode"` // nullable } type Adjustment struct { AdjustmentType string `json:"adjustmentType"` Taxable string `json:"taxable"` Description string `json:"description"` } type TaxSummary struct { Rate float64 `json:"rate"` TaxType string `json:"taxType"` SummaryName string `json:"summaryName"` DisplayRates []DisplayRate `json:"displayRates"` } type DisplayRate struct { Name string `json:"name"` Rate float64 `json:"rate"` } type AddressDetailV60 struct { NormalizedAddress string `json:"normalizedAddress"` Incorporated string `json:"incorporated"` GeoLat float64 `json:"geoLat"` GeoLng float64 `json:"geoLng"` } // // ---------- API Caller ---------- // func getSalesTaxV60(address string, apiKey string) (*ZipTaxResponse, error) { endpoint := fmt.Sprintf( "https://api.zip-tax.com/request/v60?key=%s&address=%s", apiKey, url.QueryEscape(address), ) resp, err := http.Get(endpoint) if err != nil { return nil, fmt.Errorf("failed to make API request: %w", err) } defer resp.Body.Close() if resp.StatusCode != http.StatusOK { return nil, fmt.Errorf("unexpected HTTP status %d", resp.StatusCode) } var result ZipTaxResponse if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { return nil, fmt.Errorf("failed to parse JSON: %w", err) } return &result, nil } // // ---------- Example Main ---------- // func main() { apiKey := "your_api_key_here" address := "200 Spectrum Center Drive, Irvine, CA 92618" taxInfo, err := getSalesTaxV60(address, apiKey) if err != nil { log.Fatalf("Error fetching sales tax: %v", err) } fmt.Println("----- ZipTax API v60 Response -----") fmt.Printf("Normalized Address: %s\n", taxInfo.AddressDetail.NormalizedAddress) fmt.Printf("Coordinates: %f, %f\n", taxInfo.AddressDetail.GeoLat, taxInfo.AddressDetail.GeoLng) // Example: Get the total SALES tax (from taxSummaries) for _, summary := range taxInfo.TaxSummaries { if summary.TaxType == "SALES_TAX" { fmt.Printf("Total Sales Tax: %.2f%%\n", summary.Rate*100) } } } Explanation of the Code API Request: The getSalesTax function constructs a URL with the API key and an address, makes a GET request, and parses the response. Response Parsing: The response JSON is unmarshalled into a Response struct for easy access to sales tax details. Display Results: The main function prints the normalized address, lat/lng, and sales tax rate for the specified address code. You can use any of the Response struct values here to output the data you need. 4 Run the Application Save the code to a file (e.g., main.go), then run the program: Bash go run main.go You should see output similar to this: Plain text Normalized Address: 200 Spectrum Center Dr, Irvine, CA 92618-5003, United States Coordinates: 33.652530, -117.747940 Total Sales Tax: 7.75% Conclusion Integrating the zip.tax API into your Golang application is straightforward. By following this guide, you can enhance your application with accurate sales tax information based on address. For more details, refer to the official documentation above at Getting Started . If you have any questions or feedback, feel free to email us at support@zip.tax . Happy coding!
  • [Python](https://developers.zip.tax/code-samples/python.md): This guide walks you through how to set up and use the zip.tax API in a Python application. Prerequisites Before getting started, ensure you have the following: Basic knowledge of Python. A Python development environment. An API key. To subscribe for a new key, please choose a subscription . The guide below uses a Geo level subscription. 1 Configure the Python Environment For making HTTP requests, we'll use Python's standard requests package. Additionally, we'll use json for parsing JSON responses. These packages should already be available in your Python environment. 2 Start the Python Project Create a new project directory: Bash mkdir ziptax-python && cd ziptax-python 3 The Code Here is a complete example of a simple Python application that queries the zip.tax API for sales tax information. Python import requests import json class Response: def __init__(self, data): metadata = data.get("metadata", {}) response_meta = metadata.get("response", {}) # Backwards-compatible fields self.version = metadata.get("version") self.r_code = response_meta.get("code") # Address detail maps directly from new payload self.address_detail = AddressDetail(data.get("addressDetail", {})) # Build a legacy-style "Result" object from the new v60 structure base_rates = data.get("baseRates", []) tax_summaries = data.get("taxSummaries", []) service = data.get("service", {}) shipping = data.get("shipping", {}) sourcing = data.get("sourcingRules", {}) # Group baseRates by jurType rates_by_type = {} for br in base_rates: jur_type = br.get("jurType") if jur_type: rates_by_type.setdefault(jur_type, []).append(br) def first_rate(jur_type): items = rates_by_type.get(jur_type) or [] return items[0].get("rate") if items else None def first_tax_code(jur_type): items = rates_by_type.get(jur_type) or [] return items[0].get("jurTaxCode") if items else None # Total sales/use rates from taxSummaries sales_rate = None use_rate = None for ts in tax_summaries: if ts.get("taxType") == "SALES_TAX": sales_rate = ts.get("rate") elif ts.get("taxType") == "USE_TAX": use_rate = ts.get("rate") # District-level details district_sales = rates_by_type.get("US_DISTRICT_SALES_TAX") or [] district_use = rates_by_type.get("US_DISTRICT_USE_TAX") or [] result_payload = { # Legacy combined rates "taxSales": sales_rate, "taxUse": use_rate, # Legacy service/freight taxability flags "txbService": service.get("taxable"), "txbFreight": shipping.get("taxable"), # Legacy state/city/county rates "stateSalesTax": first_rate("US_STATE_SALES_TAX"), "stateUseTax": first_rate("US_STATE_USE_TAX"), "citySalesTax": first_rate("US_CITY_SALES_TAX"), "cityUseTax": first_rate("US_CITY_USE_TAX"), "cityTaxCode": first_tax_code("US_CITY_SALES_TAX") or first_tax_code("US_CITY_USE_TAX"), "countySalesTax": first_rate("US_COUNTY_SALES_TAX"), "countyUseTax": first_rate("US_COUNTY_USE_TAX"), "countyTaxCode": first_tax_code("US_COUNTY_SALES_TAX") or first_tax_code("US_COUNTY_USE_TAX"), # Legacy combined district totals "districtSalesTax": sum((br.get("rate") or 0) for br in district_sales) if district_sales else None, "districtUseTax": sum((br.get("rate") or 0) for br in district_use) if district_use else None, # Legacy origin/destination flag "originDestination": sourcing.get("value"), } # Map up to 5 underlying districts to legacy district1..district5 fields for i in range(5): s_br = district_sales[i] if i < len(district_sales) else None u_br = district_use[i] if i < len(district_use) else None idx = i + 1 result_payload[f"district{idx}Code"] = (s_br or u_br or {}).get("jurTaxCode") if (s_br or u_br) else None result_payload[f"district{idx}SalesTax"] = s_br.get("rate") if s_br else None result_payload[f"district{idx}UseTax"] = u_br.get("rate") if u_br else None # Wrap in a list for backwards compatibility self.results = [Result(result_payload)] class Result: def __init__(self, data): self.geo_postal_code = data.get("geoPostalCode") self.geo_city = data.get("geoCity") self.geo_county = data.get("geoCounty") self.geo_state = data.get("geoState") self.tax_sales = data.get("taxSales") self.tax_use = data.get("taxUse") self.txb_service = data.get("txbService") self.txb_freight = data.get("txbFreight") self.state_sales_tax = data.get("stateSalesTax") self.state_use_tax = data.get("stateUseTax") self.city_sales_tax = data.get("citySalesTax") self.city_use_tax = data.get("cityUseTax") self.city_tax_code = data.get("cityTaxCode") self.county_sales_tax = data.get("countySalesTax") self.county_use_tax = data.get("countyUseTax") self.county_tax_code = data.get("countyTaxCode") self.district_sales_tax = data.get("districtSalesTax") self.district_use_tax = data.get("districtUseTax") self.district1_code = data.get("district1Code") self.district1_sales_tax = data.get("district1SalesTax") self.district1_use_tax = data.get("district1UseTax") self.district2_code = data.get("district2Code") self.district2_sales_tax = data.get("district2SalesTax") self.district2_use_tax = data.get("district2UseTax") self.district3_code = data.get("district3Code") self.district3_sales_tax = data.get("district3SalesTax") self.district3_use_tax = data.get("district3UseTax") self.district4_code = data.get("district4Code") self.district4_sales_tax = data.get("district4SalesTax") self.district4_use_tax = data.get("district4UseTax") self.district5_code = data.get("district5Code") self.district5_sales_tax = data.get("district5SalesTax") self.district5_use_tax = data.get("district5UseTax") self.origin_destination = data.get("originDestination") class AddressDetail: def __init__(self, data): self.normalized_address = data.get("normalizedAddress") self.incorporated = data.get("incorporated") self.geo_lat = data.get("geoLat") self.geo_lng = data.get("geoLng") def get_sales_tax(address, api_key): try: # Updated to v60 endpoint api_url = ( f"https://api.zip-tax.com/request/v60" f"?key={api_key}&address={requests.utils.quote(address)}" ) response = requests.get(api_url) if response.status_code != 200: raise Exception(f"Unexpected status code: {response.status_code}") response_data = response.json() return Response(response_data) except Exception as e: print(f"Error fetching sales tax: {e}") return None def main(): api_key = "your_api_key_here" # Replace with your actual API key address = "200 Spectrum Center Dr, Irvine, CA 92618" # Example Address tax_info = get_sales_tax(address, api_key) if tax_info: print(f"Normalized Address: {tax_info.address_detail.normalized_address}") print( f"Address Lat/Lng: " f"{tax_info.address_detail.geo_lat}, {tax_info.address_detail.geo_lng}" ) if tax_info.results and tax_info.results[0].tax_sales is not None: print(f"Rate: {tax_info.results[0].tax_sales * 100:.2f}%") else: print("Rate: N/A") if __name__ == "__main__": main() Explanation of the Code API Request: The get_sales_tax function constructs a URL with the API key and an address, makes a GET request, and parses the response. Response Parsing: The response JSON is unmarshalled for easy access to sales tax details. Display Results: The main function prints the normalized address, lat/lng, and sales tax rate for the specified address code. You can use any of the response values here to output the data you need. 4 Run the Application Save the code to a file (e.g., main.py), then run the program: Bash python main.py You should see output similar to this: Plain text Normalized Address: 200 Spectrum Center Dr, Irvine, CA 92618-5003, United States Address Lat/Lng: 33.652530, -117.747940 Rate: 7.75% Conclusion Integrating the zip.tax API into your Python application is straightforward. By following this guide, you can enhance your application with accurate sales tax information based on address. For more details, refer to the official documentation above at Getting Started . If you have any questions or feedback, feel free to email us at support@zip.tax . Happy coding!
• [Agents & LLMs](https://developers.zip.tax/docs-for-agents-and-llms.md): Modern AI agents, developer copilots, and large language models (LLMs) increasingly rely on machine-readable documentation to understand how to interact with APIs. To support this workflow, ZipTax provides a dedicated LLM reference file that summarizes key API capabilities, endpoints, and usage guidance in a format optimized for AI systems. If you are using AI agents or LLMs to build your application and need to integrate with the ZipTax real-time sales tax API , you should provide the following reference to the model or agent so it can retrieve authoritative integration guidance. LLM reference file Machine Readable OpenAPI Spec This file acts as a machine-readable index of the ZipTax developer documentation and is designed to help AI systems quickly discover the correct endpoints, parameters, and capabilities of the API. Providing this URL to an LLM or agent improves accuracy when generating code, answering developer questions, or orchestrating tax calculations within automated workflows. Check out our Ziptax MCP Server documentation to build Ziptax into your agent directly. Using Claude Desktop or Claude Code? You can add the Ziptax Claude Skill to your environment.
  • [Claude Skill](https://developers.zip.tax/docs-for-agents-and-llms/claude-skill.md): Do you want to add Ziptax as a Claude Skill? Download the SKILL.md file from our public Claude Skill repo on GitHub . Instructions for installing Skills on Claude Desktop: https://support.claude.com/en/articles/12512180-use-skills-in-claude Sample claude_desktop_config.json for the Ziptax MCP Server (requires Node installed locally): JSON { "preferences": { "coworkWebSearchEnabled": true, "coworkScheduledTasksEnabled": false, "ccdScheduledTasksEnabled": false, "sidebarMode": "chat" }, "mcpServers": { "ziptax": { "command": "npx", "args": [ "mcp-remote", "https://mcp.zip-tax.com/?key=<your-api-key>" ] } } } Do you need a Ziptax API key? You can create a free account at https://platform.zip.tax
  • [Machine Readable OpenAPI Spec](https://developers.zip.tax/docs-for-agents-and-llms/machine-readable-openapi-spec.md): The official ZipTax machine-readable API specification is published in the OpenAPI v3 JSON format and is always available at: https://raw.githubusercontent.com/ZipTax/ziptax-reference/main/openapi/openapi.json . This specification is the authoritative source of truth for the ZipTax Sales Tax API , describing all available endpoints, authentication methods (via X-API-KEY ), request parameters, response schemas, and error codes. By using this OpenAPI file, developers, eCommerce platforms, ERP systems, and point-of-sale applications can reliably integrate address-level tax calculation and U.S. sales tax compliance features directly into their software. Automated tools, SDK generators, and AI systems for tax automation should download this openapi.json file and load it into Swagger UI, Redoc, Postman, or openapi-generator to instantly generate client libraries, explore endpoints, and validate integration. AI assistants and autonomous agents looking to handle sales tax calculation , determine shipping tax exemptions , or implement tax compliance workflows can reference this specification to understand the proper request structure, authentication headers, and JSON response formats required by the ZipTax platform. By publishing this eCommerce tax API specification , we ensure that both humans and AI tools can quickly access real-time U.S. sales tax rates , map jurisdiction-specific tax rules , and achieve door-level tax accuracy for online checkouts, ERP integrations, and compliance reporting.
  • [MCP Server for AI Agents](https://developers.zip.tax/docs-for-agents-and-llms/mcp-server-for-ai-agents.md): Overview The ZipTax MCP (Model Context Protocol) Server provides AI agents and LLM-powered applications with direct access to real-time US and Canadian sales tax rate data. MCP is an open standard that enables AI applications to securely connect to external tools and data sources. With the ZipTax MCP Server, AI agents can: Look up sales and use tax rates by postal code, street address, or geographic coordinates Retrieve jurisdiction-level tax breakdowns (state, county, city, and district) Query account usage metrics and quota information Transport The ZipTax MCP Server uses Streamable HTTP transport. Most MCP clients refer to this as the HTTP transport type. Prerequisites A valid ZipTax API key. Get one at platform.zip.tax . Base URL POST https://mcp.zip-tax.com Authentication All requests to the ZipTax MCP Server require a valid API key sent in the request. Two request methods are supported: Header (Recommended) Send your API key directly in the POST Header. EXAMPLE X-API-KEY: your-api-key Query Parameter (option) Alternatively, send your API key as a url parameter key in the request URI. EXAMPLE ?key=your-api-key Note: The X-API-KEY header takes priority if both methods are present. Tools The ZipTax MCP Server exposes two tools. lookup_tax_rate Look up sales and use tax rates for a US or Canadian location. Provide a postal code at minimum, or a full street address for door-level precision. Returns tax rates broken down by jurisdiction (state, county, city, district). Parameters At least one of postalcode , address , or lat / lng is required. Example Response NOTE: The API Response mirrors the response provided in the Rate Request by Address docs. Plain text { "metadata": { "version": "v60", "response": { "code": 100, "name": "RESPONSE_CODE_SUCCESS", "message": "Successful API Request.", "definition": "http://api.zip-tax.com/request/v60/schema" } }, "baseRates": [ { "rate": 0.0725, "jurType": "US_STATE_SALES_TAX", "jurName": "CA", "jurDescription": "US State Sales Tax", "jurTaxCode": "06" }, { "rate": 0.0725, "jurType": "US_STATE_USE_TAX", "jurName": "CA", "jurDescription": "US State Use Tax", "jurTaxCode": "06" }, { "rate": 0.005, "jurType": "US_COUNTY_SALES_TAX", "jurName": "ORANGE", "jurDescription": "US County Sales Tax", "jurTaxCode": "30" }, { "rate": 0.005, "jurType": "US_COUNTY_USE_TAX", "jurName": "ORANGE", "jurDescription": "US County Use Tax", "jurTaxCode": "30" }, { "rate": 0, "jurType": "US_CITY_SALES_TAX", "jurName": "IRVINE", "jurDescription": "US City Sales Tax", "jurTaxCode": null }, { "rate": 0, "jurType": "US_CITY_USE_TAX", "jurName": "IRVINE", "jurDescription": "US City Use Tax", "jurTaxCode": null } ], "service": { "adjustmentType": "SERVICE_TAXABLE", "taxable": "N", "description": "Services non-taxable" }, "shipping": { "adjustmentType": "FREIGHT_TAXABLE", "taxable": "N", "description": "Freight non-taxable" }, "sourcingRules": { "adjustmentType": "ORIGIN_DESTINATION", "description": "Destination Based Taxation", "value": "D" }, "taxSummaries": [ { "rate": 0.0775, "taxType": "SALES_TAX", "summaryName": "Total Base Sales Tax", "displayRates": [ { "name": "Total Rate", "rate": 0.0775 } ] }, { "rate": 0.0775, "taxType": "USE_TAX", "summaryName": "Total Base Use Tax", "displayRates": [ { "name": "Total Rate", "rate": 0.0775 } ] } ], "addressDetail": { "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States", "incorporated": "true", "geoLat": 33.65253, "geoLng": -117.74794 } } get_account_metrics Retrieve account usage metrics and quota information for your ZipTax account. Returns current request counts, limits, and entitlements. This tool takes no parameters. Client Configuration Below are configuration examples for connecting popular MCP clients to the ZipTax MCP Server. Devin In Devin, add the ZipTax MCP integration from the MCP Marketplace, or configure it manually under Settings > MCP Marketplace > Add Your Own with the following configuration: Plain text { "mcpServers": { "ziptax-sales-tax-api": { "transport": "shttp", "url": "https://mcp.zip-tax.com/", "headers": { "X-API-KEY": "$ZIPTAX_API_KEY" } } } } Store your API key as a secret named ZIPTAX_API_KEY in Devin's Secrets Manager. Claude Desktop Add the following to your Claude Desktop MCP configuration file ( claude_desktop_config.json ): Plain text { "mcpServers": { "ziptax": { "type": "http", "url": "https://mcp.zip-tax.com/", "headers": { "X-API-KEY": "your_api_key" } } } } Cursor In Cursor, navigate to Settings > MCP and add a new server: Name: Ziptax MCP Server Type: HTTP URL: https://mcp.zip-tax.com/ Headers: X-API-KEY: your_api_key Generic MCP Client Any MCP client that supports the HTTP (Streamable HTTP) transport can connect to the ZipTax MCP Server. Name: Ziptax MCP Server Type: HTTP URL: https://mcp.zip-tax.com/ Headers: X-API-KEY: your_api_key Replace your_api_key with your ZipTax API key from platform.zip.tax . Error Handling When a request fails, the MCP Server returns an error message in the tool result. Common errors include: For the full list of API response codes, refer to the Response Codes documentation.
• [Ziptax MCP Server Endpoint](https://developers.zip.tax/ziptax-mcp-server-endpoint.md)