Ziptax Sales Tax
Verified@ericlakich
npx machina-cli add skill @ericlakich/ziptax --openclawZipTax Sales Tax Lookup
Setup
Set ZIPTAX_API_KEY env variable with your API key from https://platform.zip.tax (DEVELOP > API Keys).
Free tier gives 100 calls/month. Never share your API key publicly.
Quick Start
Address Lookup (most accurate)
curl -s "https://api.zip-tax.com/request/v60?address=200+Spectrum+Center+Drive+Irvine+CA+92618" \
-H "X-API-KEY: $ZIPTAX_API_KEY"
Postal Code Lookup
curl -s "https://api.zip-tax.com/request/v60?postalcode=92618" \
-H "X-API-KEY: $ZIPTAX_API_KEY"
Lat/Lng Lookup
curl -s "https://api.zip-tax.com/request/v60?lat=33.6525&lng=-117.7479" \
-H "X-API-KEY: $ZIPTAX_API_KEY"
Workflow
- Determine lookup type: address (best), lat/lng, or postal code
- Use v60 (latest) for full jurisdiction breakdowns; use v10 for simple combined rate
- Make GET request to
https://api.zip-tax.com/request/v60with auth header - Check
metadata.response.code— 100 means success - Read
taxSummaries[0].ratefor total sales tax rate - Read
baseRatesarray for state/county/city/district breakdown - Check
service.taxableandshipping.taxablefor service/freight taxability
Key Points
- Address > Postal code: Address gives one exact result; postal code returns all rates in that ZIP
- Auth: Header
X-API-KEYor query paramkey - Rate format: Decimal (0.0775 = 7.75%)
- Response code 100 = success; check
metadata.response.code - Metrics endpoint (
/account/metrics) does not count against quota
Bundled Resources
scripts/lookup.sh— CLI wrapper for quick lookups. Run with--address,--lat/--lng,--postalcode, or--metricsreferences/api-reference.md— Full API reference with all endpoints, response schemas, code samples, response codes, and SDK links. Read when you need endpoint details or response field definitions.
Overview
Look up U.S. sales tax rates via the ZipTax API, including taxability details for services and freight and TICs. It supports address-level, lat/lng, and postal-code lookups across 12,000+ jurisdictions, with jurisdiction-level breakdowns. Useful for integrating tax data into apps and tracking account usage.
How This Skill Works
Make a GET request to https://api.zip-tax.com/request/v60 with your API key in the X-API-KEY header (or as a key query parameter). Use v60 for full jurisdiction breakdowns or v10 for a simple combined rate, then check metadata.response.code (100 means success). Extract the total rate from taxSummaries[0].rate and the breakdown from baseRates; check service.taxable and shipping.taxable for service and freight taxability.
When to Use It
- When a user asks for the exact sales tax rate for a given U.S. address
- When calculating tax for orders based on address, ZIP, or coordinates
- When you need jurisdiction-level tax breakdowns (state, county, city, district)
- When determining use tax vs sales tax for a transaction
- When integrating tax data into an application and tracking account usage
Quick Start
- Step 1: Determine lookup type (address, lat/lng, or postal code)
- Step 2: Call https://api.zip-tax.com/request/v60 with your API key (X-API-KEY) or key param
- Step 3: Check metadata.response.code for 100 and read taxSummaries[0].rate and baseRates for breakdown
Best Practices
- Use address-level lookups for the most precise rate; use postal codes when only area-level rates are acceptable
- Prefer v60 for full jurisdiction breakdowns; use v10 for a quick, simple rate
- Authenticate with the X-API-KEY header or pass key as a query parameter and keep keys secure
- Verify success with metadata.response.code = 100; read taxSummaries[0].rate for total rate and baseRates for breakdown
- Use the /account/metrics endpoint for usage data (does not count against quota) to monitor consumption
Example Use Cases
- Estimate the sales tax rate for an address: 200 Spectrum Center Drive, Irvine, CA 92618
- Fetch all rates for a ZIP code: 92618 to understand state/county/city/district taxes
- Lookup tax for a warehouse lat/lng: lat=33.6525, lng=-117.7479
- Determine whether services or freight are taxable in a given jurisdiction
- Embed ZipTax data in an e-commerce app to auto-calculate taxes during checkout
