Skip to main content
POST
Tax

Overview

Two read-only tools on a tax system you connected with a key (Connections). Connected system: TaxJar. Nothing is written at the system: a calculation is a quote, and no transaction is created. Nothing fetched is kept by OneShot.
  • POST /v1/tools/tax/rates: the rate for a location.
  • POST /v1/tools/tax/calculate: the tax on an order.
Both take connection_id. An agent can have several connections to the same system: list your connections first (GET /v1/connections) and pick by system and account_label.

Authentication

Requires x402 payment in the payment-signature header. A refused request (an unknown or inactive connection, a connection on another kind of system, an unavailable system, an invalid body) is answered before payment and is not charged.

Tax rates

POST /v1/tools/tax/rates
string
required
The connection to read.
string
required
Postal code of the location.
string
default:"US"
Two-letter country code.
string
State or province code, for a more precise rate.
string
City, for a more precise rate.
string
Street address, for a rooftop-precise rate where the system offers one.

Response (200)

number
The whole rate at the location, as a fraction (0.1025 is 10.25%).
array
The rate by jurisdiction: jurisdiction (country, state, county, city or special_district) and rate.
object
system (the connected system) and id (the location reference, country:zip).

Tax calculation

POST /v1/tools/tax/calculate
string
required
The connection to read.
object
required
Where the order ships from: country, zip, state (required for US and CA), city, street.
object
required
Where the order ships to: the same fields.
array
required
The goods on the order, 1 to 100 lines: unit_price (required), quantity (default 1), discount, product_tax_code (the system’s product tax category, when the goods are not taxed at the general rate) and id (your reference, returned in the breakdown).
number
default:0
Shipping charged on the order, before tax.

Response (200)

number
The tax to collect on the order.
number
The whole rate applied, as a fraction.
number
The part of the order that is taxed.
object
jurisdictions (per jurisdiction: taxable_amount, tax_collectable, rate), line_items (per line, with your id) and shipping (or null when shipping is not taxed).
object
system and id (the destination reference, country:zip).

Errors