Skip to main content
POST
Get tax information for a given product and address or IP.
Required from 2025-05-12+:
  • The origin_address field is required for all calculations starting from API version 2025-05-12, unless a default origin address is configured for the destination jurisdiction on your account.
  • The automatic_tax field in order_details is required starting from API version 2025-05-12 (and must be "auto" for US addresses). Use "auto" to enable automatic tax calculation or "disabled" to return zero tax rates.
Note: The address_type field is only valid on customer.address — including it on origin_address returns a 400 UNRECOGNIZED_FIELD error.

cURL Header Example

Use X-API-Version explicitly in requests:
New in 2026-03-01:
  • You can now provide customer.ip instead of (or in addition to) customer.address for IP-based tax resolution.
  • Optional transacted_at (Unix timestamp in seconds): evaluate time-dependent inputs (e.g., out-of-state-seller status, rates) as of the sale time instead of now.
  • Optional default_customer_type: fallback customer type when customer.id doesn’t exist in Numeral yet.
  • US ZIP-to-state fallback: address_province is still required and should always be sent, but if it is missing or empty on a US address, Thomas attempts to infer the state from a valid 5-digit ZIP (an unrecognized ZIP returns a 400 MALFORMED_ADDRESS).
Inherited from 2026-01-01: The amount field on line items is per-unit price (taxable base = amount x quantity). Responses include address_resolution_status, address_used, and enhanced tax_jurisdictions fields (tax_authority_name, tax_authority_type, tax_type, tax_due_decimal).
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. The per-jurisdiction tax_due_decimal field shows how much each jurisdiction actually contributed.

IP-Based Resolution

Instead of providing a full customer address, you can pass an IP address and we’ll resolve it to a taxable location:
At least one of customer.address or customer.ip must be provided. If both are given, the address is used first with IP as a fallback.

Resolution Modes

Numeral strongly recommends using strict mode to stay as compliant as possible.

New Response Fields

IP Resolution Errors

Error Codes Reference

See the complete list of error types and their meanings.

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:2026-03-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, NOT this version.

Available options:
2026-03-01

Body

application/json
customer
object
required

Customer details. At least one of customer.address or customer.ip must be provided. 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. 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).

transacted_at
integer

Optional. The time the transaction occurred, as a Unix timestamp in seconds (not milliseconds). Used to determine which tax rates and rules apply at the time of the transaction (for example, during sales tax holidays), as well as other time-dependent inputs such as out-of-state-seller status. If omitted, the calculation uses the current time. Available in API version 2026-03-01 and later.

Example:

1772323200

default_customer_type
enum<string>

Optional fallback customer type used when customer.id is provided but no matching customer exists in Numeral. Lets integration partners always pass a customer ID without first ensuring the customer has been created. When the lookup misses, this value drives tax-exemption logic and business tax-ID validation as if it were customer.type. If a matching customer is found, the stored customer.type takes precedence. Available in API version 2026-03-01 and later.

Available options:
CONSUMER,
BUSINESS
Example:

"CONSUMER"

invalid_tax_id_customer_fallback_type
enum<string>

Optional. When business tax ID validation fails, fall back to treating the customer as this type instead of returning a 400. CONSUMER is the only accepted value. Available in API version 2026-01-01 and later.

Available options:
CONSUMER
Example:

"CONSUMER"

Response

Calculate response

id
string

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

Example:

"calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3"

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. type reflects the effective customer type used for the calculation (e.g., after default_customer_type or invalid_tax_id_customer_fallback_type is applied).

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

location_source
enum<string>

Which input was used for tax determination.

Available options:
address,
ip
Example:

"address"

resolution_precision
enum<string>

The precision level of the resolved location.

Available options:
STREET,
POSTAL_PLUS,
POSTAL,
PROVINCE,
COUNTRY,
APPROXIMATED
Example:

"POSTAL"