Skip to main content
POST
Get tax information for a given product and address
In this version, line item amount is the total for the line (not per-unit) in the currency’s smallest unit — quantity is record-keeping only and does not affect the taxable base. Per-unit pricing starts in 2026-01-01.
Caution about simply summing tax_rate values. Each tax_rate in tax_jurisdictions is the statutory rate for that jurisdiction, and in some jurisdictions a rate applies to only part of the line item amount. Tennessee’s single article rules are the common example: local rates apply only to the first $1,600 of an item, and the 2.75% state single article rate applies only to the portion between $1,600 and $3,200. For a $10,000 item the returned rates sum to 12.25%, but the tax due is $788, an effective rate of 7.88%.Always charge the returned tax_amount (or total_tax_amount). If you need an effective rate, compute tax_amount / amount_excluding_tax from the response rather than adding up tax_rate values. Jurisdictions whose rate applies to only part of the amount carry a note value other than RATE_FRAC, such as PROGRESSIVE_RATE.

cURL Header Example

Always set an API version — pass X-API-Version explicitly (recommended), or configure a default version on your account. Requests with neither fall back to 2024-09-01:

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Version
enum<string>
default:2024-09-01
required

The API version for this request. Always set a version: pass this header explicitly (recommended), or configure a default API version on your account and omit the header. Accounts with no configured version fall back to 2024-09-01, but an account default set to a newer version takes precedence over that fallback.

Available options:
2024-09-01

Body

application/json
customer
object
required

Customer details. Address is required. Optionally accepts a customer ID for order tracking and exemptions.

order_details
object
required
origin_address
object

Optional, but relevant for tax collection in certain jurisdictions. The address that a product is shipped from.

metadata
object

You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).

Response

Calculate response

id
string

The ID of the calculation. You will use this to create a transaction.

Example:

"calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c"

object
string

The type of object: tax.calculation.

Example:

"tax.calculation"

customer_currency_code
string

The ISO-4217 currency code of the transaction.

Example:

"USD"

line_items
object[]
tax_included_in_amount
boolean
Example:

false

total_tax_amount
integer

Total tax to charge on this calculation, in the currency's smallest unit (rounded to an integer).

Example:

140

total_amount_excluding_tax
integer

Total sale charge excluding tax, in the currency's smallest unit (rounded to an integer).

Example:

2000

total_amount_including_tax
integer

Total sale charge plus tax, in the currency's smallest unit (rounded to an integer). What you should charge your customer.

Example:

2140

expires_at
integer

Unix timestamp in seconds at which the quoted tax rates expire — 24 hours after the calculation is created.

Example:

1714787673

testmode
boolean

True if using a production API key. False if using a test API key.

Example:

false

metadata
object

You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).