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.

POSThttps://{your_api_domain}/external/v2/tax-rate/query
Authentication

Include your API key in the X-API-Key request header.

X-API-Key: <your_api_key>

Request parameters

Request parameters
ParameterRequiredTypeDescription
stateRequiredstringU.S. state for all items in the request.
itemsRequiredarrayOne item for a single lookup, or multiple items in the same state.
items[].itemIdRequiredstringUnique item identifier within this request.
items[].addressOptionalstringHouse number and street. Include this field for address-level matching.
items[].zipCodeOptionalstringFive-digit ZIP code.
items[].zipPlus4OptionalstringZIP+4 suffix, when available.
items[].cityOptionalstringCity from the shipping address.
items[].countyOptionalstringCounty 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}