Create Calculations
Get tax information for a given product and address
order_details.automatic_taxis required ("auto"or"disabled"), and must be"auto"for US addresses.origin_addressis required at calculation time unless a default origin address is configured for the destination jurisdiction on your account.
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.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
UseX-API-Version explicitly in requests:
curl --request POST \
--url https://api.numeralhq.com/tax/calculations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-API-Version: 2025-05-12' \
--data '{ ... }'
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
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.
2025-05-12 Body
Customer details. Address is required. Optionally accepts a customer ID for order tracking and exemptions.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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).
Show child attributes
Show child attributes
Response
Calculate response
The ID of the calculation. You will use this to create a transaction.
"calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f571"
The type of object: tax.calculation.
"tax.calculation"
The ISO-4217 currency code of the transaction.
"USD"
Customer information returned in the response.
Show child attributes
Show child attributes
The automatic tax setting for this calculation.
auto, disabled "auto"
Show child attributes
Show child attributes
false
Total tax to charge on this calculation, in the currency's smallest unit (rounded to an integer).
140
Total sale charge excluding tax, in the currency's smallest unit (rounded to an integer).
2000
Total sale charge plus tax, in the currency's smallest unit (rounded to an integer). What you should charge your customer.
2140
Unix timestamp in seconds at which the quoted tax rates expire — 24 hours after the calculation is created.
1714787673
True if using a production API key. False if using a test API key.
false
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.
EXACT, POSTAL_FALLBACK_1, POSTAL_ONLY "EXACT"
The actual address used for tax calculation after resolution.
Show child attributes
Show child attributes
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).
Show child attributes
Show child attributes