Back home
Developer Portal
Build with Byte Orca
Public API contracts for sales tax calculation and transaction ingestion, with implementation-ready examples.
POST API
Sales Tax Rate API
Look up tax rates by street address for one or more locations in the same state.
Endpoint
Send a JSON body with the state and query items. Include a house number and street in address for address-level matching.
POST
https://{your_api_domain}/external/v2/tax-rate/queryAuthentication
Include your API key in the X-API-Key request header.
X-API-Key: <your_api_key>Request parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| state | Required | string | U.S. state for all items in the request. |
| items | Required | array | One item for a single lookup, or multiple items in the same state. |
| items[].itemId | Required | string | Unique item identifier within this request. |
| items[].address | Optional | string | House number and street. Include this field for address-level matching. |
| items[].zipCode | Optional | string | Five-digit ZIP code. |
| items[].zipPlus4 | Optional | string | ZIP+4 suffix, when available. |
| items[].city | Optional | string | City from the shipping address. |
| items[].county | Optional | string | County from the shipping address. |
Request example
Code
1curl 'https://{your_api_domain}/external/v2/tax-rate/query' \2 -H 'X-API-Key: <your_api_key>' \3 -H 'Content-Type: application/json' \4 --data '{5 "state": "WA",6 "items": [{7 "itemId": "order-001",8 "address": "123 Main St",9 "city": "Bellevue",10 "county": "King",11 "zipCode": "98005"12 }]13 }'Success response
HTTP 200 OK · Response format
This excerpt omits sourceSummary and each item’s detailItems. Check each item’s status and matchedLevel. ADDRESS indicates a street address match. Rates are returned as percentage strings, so "10.3" means 10.3%.
Code
1{2 "code": 200,3 "msg": "OK",4 "data": {5 "state": "WA",6 "totalCount": 1,7 "successCount": 1,8 "noMatchCount": 0,9 "invalidCount": 0,10 "failedCount": 0,11 "items": [{12 "itemId": "order-001",13 "status": "SUCCESS",14 "matchedLevel": "ADDRESS",15 "mainItem": {16 "taxRate": "10.3",17 "stateTaxRate": "6.5",18 "countyTaxRate": "2.4",19 "cityTaxRate": "0",20 "specialDistrictTaxRate": "1.4"21 }22 }]23 }24}