Skip to main content
POST
Get tax information for a given product and address
New requirements in 2025-05-12:
  • order_details.automatic_tax is required ("auto" or "disabled"), and must be "auto" for US addresses.
  • origin_address is required at calculation time unless a default origin address is configured for the destination jurisdiction on your account.
Also new in 2025-05-12: customer.type (CONSUMER/BUSINESS, default CONSUMER), customer.tax_ids (types VAT/GST/EIN; required for BUSINESS with a non-US address, rejected for CONSUMER), customer.skip_tax_id_validation, expanded currency support (126 codes) and destination countries (82). Responses add customer, automatic_tax, address_resolution_status, and address_used. Line item amount is still the total for the line — 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

Use X-API-Version explicitly in requests:

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:2025-05-12
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, NOT this version.

Available options:
2025-05-12

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

The address that a product is shipped from. Starting with API version 2025-05-12 this is required at calculation time unless a default origin address is configured for the destination jurisdiction on your account — omitting it with no default configured returns a 400.

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_1783369568468633ea55e-084a-419e-9d47-9f07aa27f571"

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"

customer
object

Customer information returned in the response.

automatic_tax
enum<string>

The automatic tax setting for this calculation.

Available options:
auto,
disabled
Example:

"auto"

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

address_resolution_status
enum<string>

Status of address resolution for the customer address. EXACT: exact address match found, POSTAL_FALLBACK_1: used postal code fallback, POSTAL_ONLY: only postal code was used for tax calculation.

Available options:
EXACT,
POSTAL_FALLBACK_1,
POSTAL_ONLY
Example:

"EXACT"

address_used
object

The actual address used for tax calculation after resolution.

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).