By Address
Door-level sales tax rate for a street address
Look up the single sales tax rate that applies at a specific street address. Ziptax geocodes the address down to the rooftop and returns the rate adjusted for unincorporated areas and special tax jurisdictions, which is the right answer for an actual delivery or point-of-sale location.
Use this method when you have a customer shipping address, a billing address, or a physical storefront. It’s the most accurate lookup option and what we recommend for most integrations.
Endpoint
Send the address in the address query parameter. The full URL-encoded
address is the only required input besides your API key.
Quick example
Parameters
Required
You must also authenticate with your API key via the X-API-KEY header
(recommended) or the key query parameter.
Optional
Plan-gated parameters return a specific response code if your account
doesn’t have the entitlement: countryCode=CAN returns code 112
(rate_loc_can entitlement), taxabilityCode returns code 113
(product_rates entitlement). See the
Response Codes reference for the full
list.
Example response
The full response schema (every field on baseRates, taxSummaries,
shipping, service, productDetail, etc.) is documented in the
API Reference.
Exemption certificates
On /request/v60, add merchantId, and optionally customerId, to see which
of a merchant’s exemption certificates
list the state the lookup resolves to. To apply an exemption at checkout,
send an exemption request on the cart.
When the merchant (narrowed to customerId, if sent) has certificates that
list the looked-up state, the response gains a top-level exemptionDetail
block. The rest of the response is unchanged:
Things to know:
- Rates never change.
baseRates,taxSummaries, and every other field are the same as withoutmerchantId. To quote a sale without tax, apply the certificate on a cart. - US lookups only. Canadian lookups validate the filters and omit
exemptionDetail. A US lookup omits the block if no certificate lists the state. - Rate response cache. A request with
merchantIdbypasses the rate response cache. - Ziptax certificates only. Certificates held in a connected merchant’s TaxCloud account are not included. Addresses and identification numbers are never returned here.
- Errors. Response code
105whencustomerIdis sent withoutmerchantId, whencustomerIdis invalid, whenmerchantIdis invalid or outside your account, or when the certificate read exceeds 500 records. IncludecustomerIdto narrow a merchant-wide lookup. Response code106indicates the certificates could not be read. See Response Codes.
Tips & common pitfalls
URL-encode the address
Addresses contain spaces, commas, and sometimes # or &, all of
which must be percent-encoded. Most HTTP clients do this for you if
you pass the address via a params object; if you’re building URLs by
hand, use your language’s URL encoder.
Partial addresses are OK
You can send just street + ZIP (200 Spectrum Center Dr 92618) or
street + city + state. Ziptax normalizes to the full USPS address
regardless. Check addressDetail.normalizedAddress in the response
if you want to confirm what Ziptax actually geocoded.
Canadian addresses
Set countryCode=CAN to look up Canadian rates. Canadian lookups
are available on Starter, Pro, and Enterprise plans. Accounts without
the rate_loc_can entitlement will get response code 112.
US territory addresses
Set countryCode to a US territory code to look these addresses up
through the US path: PRI (Puerto Rico), ASM (American Samoa),
GUM (Guam), MNP (Northern Mariana Islands), or VIR (U.S. Virgin
Islands). Territories use US ZIP codes and need no extra entitlement.
Rate sourcing (origin vs destination)
Most states use destination-based sourcing, but a handful (e.g.
California’s “modified origin” rule) are more nuanced. Ziptax makes
the correct decision automatically; sourcingRules in the response
tells you which rule was applied.
Single-item rules (Tennessee, Arizona, Florida)
Some states tax a single item differently once its price passes a
threshold. Pass the price of one item in sat_item_total and the
response adds a satTaxDetail object with the tax on that item.
baseRates and taxSummaries don’t change. Requires a geo-enabled key.
For Arizona and Florida, satTaxDetail.singleItemRules lists each rule
that changed the item’s tax, with its threshold, standardRate,
reducedRate, affectedAmount, and taxChange. When no rule changes
the tax (the price is under the threshold, or the city has no
single-item rate), there is no satTaxDetail. The breakdown uses the
location’s standard rates and doesn’t reflect the rate rules of a
taxabilityCode sent with the request. See the API reference for every
field.