> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Calculations
> Get tax information for a given product and address
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:
```bash theme={null}
curl --request POST \
--url https://api.numeralhq.com/tax/calculations \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--header 'X-API-Version: 2025-05-12' \
--data '{ ... }'
```
## OpenAPI
````yaml api-reference/v2025-05-12/openapi.json POST /tax/calculations
openapi: 3.0.1
info:
title: Numeral API
description: API for sales tax calculations - Version 2025-05-12
license:
name: MIT
version: '2025-05-12'
servers:
- url: https://api.numeralhq.com/
security:
- bearerAuth: []
paths:
/tax/calculations:
post:
description: Get tax information for a given product and address
parameters:
- name: X-API-Version
in: header
required: true
schema:
type: string
enum:
- '2025-05-12'
default: '2025-05-12'
description: >-
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.
example: '2025-05-12'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CalculationRequest'
examples:
consumer:
summary: Consumer calculation
value:
customer:
type: CONSUMER
address:
address_line_1: 4 Privet Drive
address_city: Little Whinging
address_province: CA
address_postal_code: '90210'
address_country: US
address_type: shipping
origin_address:
address_line_1: 3990 N County Rd 300 E
address_city: Danville
address_province: IN
address_postal_code: '46122'
address_country: US
order_details:
customer_currency_code: USD
tax_included_in_amount: false
automatic_tax: auto
line_items:
- reference_product_id: wand_elder_12
amount: 10000
quantity: 1
business:
summary: Business customer with tax IDs
value:
customer:
type: BUSINESS
tax_ids:
- type: VAT
value: GB123456789
address:
address_line_1: 123 Business St
address_city: London
address_province: England
address_postal_code: EC1A 1BB
address_country: GB
address_type: billing
origin_address:
address_line_1: Tech Park 1
address_city: Dublin
address_province: L
address_postal_code: D02 XY45
address_country: IE
order_details:
customer_currency_code: EUR
tax_included_in_amount: false
automatic_tax: auto
line_items:
- reference_product_id: business_software_license
amount: 50000
quantity: 5
with_fallback_product_category:
summary: Calculation with fallback_product_category
value:
customer:
type: CONSUMER
address:
address_line_1: 4 Privet Drive
address_city: Little Whinging
address_province: CA
address_postal_code: '90210'
address_country: US
address_type: shipping
origin_address:
address_line_1: 3990 N County Rd 300 E
address_city: Danville
address_province: IN
address_postal_code: '46122'
address_country: US
order_details:
customer_currency_code: USD
tax_included_in_amount: false
automatic_tax: auto
line_items:
- reference_product_id: product_not_yet_in_numeral
fallback_product_category: GENERAL_MERCHANDISE
amount: 10000
quantity: 1
required: true
responses:
'200':
description: Calculate response
content:
application/json:
schema:
$ref: '#/components/schemas/CalculationResponse'
examples:
consumer:
summary: Consumer calculation response
value:
testmode: true
id: calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f571
object: tax.calculation
customer_currency_code: USD
line_items:
- line_item_id: li_1783369568468ae179a21-411f-4a7f-a192-66a23331dc24
product:
reference_line_item_id: ''
reference_product_id: wand_elder_12
reference_product_name: Elder Wand
product_tax_code: GENERAL_MERCHANDISE
tax_jurisdictions:
- tax_rate: 0.0725
rate_type: general state sales tax
jurisdiction_name: California
fee_amount: 0
note: RATE_FRAC
- tax_rate: 0.025
rate_type: general county local sales tax
jurisdiction_name: Los Angeles
fee_amount: 0
note: RATE_FRAC
tax_amount: 975
amount_excluding_tax: 10000
amount_including_tax: 10975
quantity: 1
total_tax_amount: 975
tax_included_in_amount: false
total_amount_excluding_tax: 10000
total_amount_including_tax: 10975
expires_at: 1783455968
customer:
type: CONSUMER
automatic_tax: auto
address_resolution_status: EXACT
address_used:
address_line_1: 4 Privet Drive
address_city: Little Whinging
address_province: CA
address_postal_code: '90210'
address_country: US
business:
summary: Business customer response with tax IDs
value:
testmode: true
id: calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f572
object: tax.calculation
customer_currency_code: EUR
line_items:
- line_item_id: li_1783369568468ae179a21-411f-4a7f-a192-66a23331dc25
product:
reference_line_item_id: ''
reference_product_id: business_software_license
reference_product_name: Business Software License
product_tax_code: SAAS_GENERAL
tax_jurisdictions:
- tax_rate: 0.2
rate_type: standard
jurisdiction_name: GB
fee_amount: 0
note: RATE_FRAC
tax_amount: 10000
amount_excluding_tax: 50000
amount_including_tax: 60000
quantity: 5
total_tax_amount: 10000
tax_included_in_amount: false
total_amount_excluding_tax: 50000
total_amount_including_tax: 60000
expires_at: 1783455968
customer:
type: BUSINESS
tax_ids:
- type: VAT
value: GB123456789
automatic_tax: auto
address_resolution_status: POSTAL_ONLY
address_used:
address_line_1: 123 Business St
address_city: London
address_province: England
address_postal_code: EC1A 1BB
address_country: GB
with_fallback_product_category:
summary: Response when the fallback product category was used
value:
testmode: true
id: calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f573
object: tax.calculation
customer_currency_code: USD
line_items:
- line_item_id: li_1783369568468ae179a21-411f-4a7f-a192-66a23331dc26
product:
reference_line_item_id: ''
reference_product_id: default-general-merchandise
reference_product_name: Default GENERAL_MERCHANDISE Product
product_tax_code: GENERAL_MERCHANDISE
tax_jurisdictions:
- tax_rate: 0.0725
rate_type: general state sales tax
jurisdiction_name: California
fee_amount: 0
note: RATE_FRAC
- tax_rate: 0.025
rate_type: general county local sales tax
jurisdiction_name: Los Angeles
fee_amount: 0
note: RATE_FRAC
tax_amount: 975
amount_excluding_tax: 10000
amount_including_tax: 10975
quantity: 1
total_tax_amount: 975
tax_included_in_amount: false
total_amount_excluding_tax: 10000
total_amount_including_tax: 10975
expires_at: 1783455968
customer:
type: CONSUMER
automatic_tax: auto
address_resolution_status: EXACT
address_used:
address_line_1: 4 Privet Drive
address_city: Little Whinging
address_province: CA
address_postal_code: '90210'
address_country: US
'400':
description: Validation error
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/MissingOriginAddressError'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProductNotFoundError'
components:
schemas:
CalculationRequest:
type: object
properties:
customer:
$ref: '#/components/schemas/CustomerDetails'
description: >-
Customer details. Address is required. Optionally accepts a customer
ID for order tracking and exemptions.
origin_address:
$ref: '#/components/schemas/Address'
description: >-
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.
order_details:
$ref: '#/components/schemas/OrderDetails'
metadata:
$ref: '#/components/schemas/Metadata'
required:
- customer
- order_details
CalculationResponse:
type: object
properties:
id:
type: string
description: >-
The ID of the `calculation`. You will use this to create a
`transaction`.
example: calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f571
object:
type: string
description: 'The type of object: `tax.calculation`.'
example: tax.calculation
customer_currency_code:
type: string
description: The ISO-4217 currency code of the transaction.
example: USD
customer:
type: object
description: Customer information returned in the response.
properties:
type:
type: string
enum:
- CONSUMER
- BUSINESS
description: >-
The type of customer. `CONSUMER` are private individuals.
`BUSINESS` are companies or legal entities registered for
VAT/GST.
example: CONSUMER
tax_ids:
type: array
description: Echo of the `tax_ids` provided in the request, when present.
items:
type: object
properties:
type:
type: string
enum:
- VAT
- GST
- EIN
example: VAT
value:
type: string
automatic_tax:
type: string
enum:
- auto
- disabled
description: The automatic tax setting for this calculation.
example: auto
line_items:
type: array
items:
$ref: '#/components/schemas/TransactionLineItem'
tax_included_in_amount:
type: boolean
example: false
total_tax_amount:
type: integer
description: >-
Total tax to charge on this `calculation`, in the currency's
smallest unit (rounded to an integer).
example: 140
total_amount_excluding_tax:
type: integer
description: >-
Total sale charge excluding tax, in the currency's smallest unit
(rounded to an integer).
example: 2000
total_amount_including_tax:
type: integer
description: >-
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:
type: integer
description: >-
Unix timestamp in **seconds** at which the quoted tax rates expire —
24 hours after the calculation is created.
example: 1714787673
testmode:
type: boolean
description: >-
`True` if using a production API key. `False` if using a test API
key.
example: false
address_resolution_status:
type: string
enum:
- EXACT
- POSTAL_FALLBACK_1
- POSTAL_ONLY
description: >-
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.
example: EXACT
address_used:
$ref: '#/components/schemas/Address'
description: The actual address used for tax calculation after resolution.
metadata:
$ref: '#/components/schemas/Metadata'
Error:
type: object
description: >-
Legacy error format used by API versions before 2026-01-01. The request
ID is returned in the `X-Request-Id` response header, not in the body.
properties:
error:
type: object
properties:
error_code:
type: string
description: >-
Machine-readable error code (e.g., `missing_field`,
`incorrect_type`, `malformed_address`, `invalid_currency_code`,
`unrecognized_field`).
example: missing_field
error_message:
type: string
description: Human-readable error message.
example: Field is required
error_meta:
type: object
description: >-
Optional details about the error, such as the offending `field`
and the `expected`/`received` types.
MissingOriginAddressError:
type: object
properties:
error:
type: object
properties:
error_code:
type: string
error_message:
type: string
ProductNotFoundError:
type: object
properties:
error:
type: object
properties:
error_code:
type: string
error_message:
type: string
CustomerDetails:
type: object
properties:
id:
type: string
description: >-
The ID of the customer that you created in our system. Can be used
to log customer information or indicate that a purchaser is tax
exempt.
example: cus_123456789
type:
type: string
enum:
- CONSUMER
- BUSINESS
default: CONSUMER
description: >-
`CONSUMER` are private individuals who are not registered for
VAT/GST. `BUSINESS` are companies, sole-proprietors, or other legal
entities registered for VAT/GST. Defaults to `CONSUMER` when
omitted.
example: CONSUMER
tax_ids:
type: array
description: >-
Array of tax identification numbers. Required when `type` is
`BUSINESS` and the address is outside the US. Must not be present
when `type` is `CONSUMER`.
items:
type: object
properties:
type:
type: string
enum:
- VAT
- GST
- EIN
description: >-
The tax ID type. API version 2025-05-12 accepts only `VAT`,
`GST`, or `EIN`. (Country-specific Stripe-style types like
`us_ein` start in 2026-01-01.)
example: VAT
value:
type: string
description: The tax ID value
required:
- type
- value
skip_tax_id_validation:
type: boolean
default: false
description: >-
When `true`, skips validation of the provided `tax_ids` (format and
registry checks). Defaults to `false`.
example: false
address:
description: >-
The customer (destination) address. API version 2025-05-12 supports
82 destination countries: the 2024-09-01 set (US, CA, EU member
states) plus CY, CH, NO, GB, AU, NZ, SG, ID, VN, PH, TH, KR, JP, IN,
TR, SA, AE, AR, CL, EG, HK, MO, IL, AL, TW, MY, BD, ZA, KE, UG, MA,
BH, OM, CI, CM, GH, NG, BJ, NE, CV, IS, RS, GE, MD, MK, ME, CO, PE,
UY, BB, BS, LA, LI, KZ, TZ. For US and CA, `address_province` must
be a valid uppercase USPS state code / Canadian province code and
`address_postal_code` is required.
allOf:
- $ref: '#/components/schemas/Address'
- type: object
properties:
address_type:
type: string
enum:
- shipping
- billing
description: >-
The type of address. For physical goods, `shipping` should
be used. For software and digital goods, `billing` is more
appropriate. Only valid on `customer.address` — including it
on `origin_address` returns a 400 with `error_code:
"unrecognized_field"`.
example: shipping
required:
- address_type
required:
- address
Address:
type: object
properties:
address_line_1:
type: string
example: 3990 N County Rd 300 E
address_line_2:
type: string
example: Unit 2
address_city:
type: string
example: Danville
address_province:
type: string
description: >-
The state, province, or region of the transaction. Must be a valid 2
digit ISO 3166-2 subdivision code.
example: IN
address_postal_code:
type: string
example: '46122'
address_country:
type: string
description: >-
The country code of the transaction. Must be a valid ISO 3166-1
alpha-2 country code.
example: US
required:
- address_line_1
- address_city
- address_province
- address_postal_code
- address_country
OrderDetails:
type: object
properties:
customer_currency_code:
type: string
description: >-
The ISO-4217 currency code of the transaction. API version
2025-05-12 supports 126 currencies (the full Stripe-supported list):
AED, ALL, AMD, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BIF,
BMD, BND, BOB, BRL, BSD, BWP, BZD, CAD, CDF, CHF, CLP, CNY, COP,
CRC, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP,
GEL, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HTG, HUF, IDR, ILS, INR,
ISK, JMD, JPY, KES, KGS, KHR, KMF, KRW, KYD, KZT, LAK, LKR, LRD,
LSL, MAD, MDL, MGA, MKD, MNT, MOP, MUR, MVR, MWK, MXN, MYR, MZN,
NAD, NGN, NIO, NOK, NPR, NZD, PAB, PEN, PGK, PHP, PKR, PLN, PYG,
QAR, RON, RSD, RWF, SAR, SBD, SCR, SEK, SGD, SOS, SRD, SZL, THB,
TJS, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VND, VUV,
WST, XAF, XCD, XCG, XOF, XPF, YER, ZAR, ZMW.
example: USD
tax_included_in_amount:
type: boolean
description: >-
For the line items in this transaction, does the amount include tax?
This should typically be `false` for most North American sales, but
may vary by jurisdiction and business model.
example: false
automatic_tax:
type: string
enum:
- auto
- disabled
description: >-
Controls automatic tax behavior. `auto`: return real rates if client
is registered/enabled in that jurisdiction. `disabled`: always
return 0 tax rates regardless of registration status. Required
starting with API version 2025-05-12, and must be `auto` when the
customer address is in the US.
example: auto
line_items:
type: array
description: >-
Each line item should represent one type of product. For compliance,
we require either a `reference_product_id` or a `product_category`.
items:
$ref: '#/components/schemas/LineItem'
required:
- customer_currency_code
- tax_included_in_amount
- automatic_tax
- line_items
Metadata:
type: object
description: >-
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).
properties:
example_key:
type: string
description: >-
Storing things like an order number may be useful for reporting and
reconciliation.
example: example_value
TransactionLineItem:
type: object
properties:
line_item_id:
type: string
description: Numeral-generated ID for this line item.
example: li_1783369568468ae179a21-411f-4a7f-a192-66a23331dc24
product:
type: object
description: Product information for this line item.
properties:
reference_product_name:
type: string
description: The name of the product.
example: Red Shoes
reference_line_item_id:
type: string
description: The ID of the line item from your system.
example: line_123456789
reference_product_id:
type: string
description: The product ID in your system.
example: p-1233543
product_tax_code:
type: string
description: The tax code applied to this product.
example: GENERAL_MERCHANDISE
tax_jurisdictions:
type: array
description: Array of tax jurisdictions that apply to this line item.
items:
type: object
properties:
tax_rate:
type: number
description: >-
The tax rate for this jurisdiction. This is the statutory rate
for the jurisdiction and may apply to only part of the line
item amount (for example, Tennessee single article rules). Do
not sum rates across jurisdictions to derive an effective
rate; use `tax_amount / amount_excluding_tax` instead.
example: 0.07
rate_type:
type: string
description: >-
The type of tax rate: `sales_tax` for US SST states, `general
state sales tax` / `general county local sales tax` for other
US states, `standard` for VAT countries. Zero-rate placeholder
rows (e.g., when `automatic_tax` is `disabled`) use `VAT`.
example: sales_tax
jurisdiction_name:
type: string
description: >-
The name of the tax jurisdiction. A state/county name for US,
the ISO country code for VAT countries (e.g., `DE`).
example: Indiana
fee_amount:
type: number
description: Any fixed fee amount for this jurisdiction.
example: 0
note:
type: string
description: >-
Calculation-method note for this jurisdiction, e.g.
`RATE_FRAC`, or a reason string on zero-rate placeholder rows
(e.g., `automatic_tax_disabled`).
example: RATE_FRAC
quantity:
type: number
description: The quantity of this product.
example: 2
tax_amount:
type: number
description: The tax amount for this line item.
example: 14
amount_excluding_tax:
type: number
description: The line item amount excluding tax.
example: 200
amount_including_tax:
type: number
description: The line item amount including tax.
example: 214
LineItem:
type: object
properties:
reference_line_item_id:
type: string
description: >-
The ID of the line item from your system. This field is optional and
will be primarily used for record keeping.
example: line_123456789
reference_product_id:
type: string
description: >-
The product ID is used to uniquely reference this product in your
system as well as in Numeral. Required if no `product_category`.
example: p-1233543
product_category:
type: string
description: >-
A tax category from our category taxonomy. Required if no
`reference_product_id`.
example: GENERAL_MERCHANDISE
fallback_product_category:
type: string
description: >-
Optional fallback product category used when `reference_product_id`
is provided but no matching product exists in Numeral. Lets
integration partners always pass a product ID without first ensuring
the product has been created. Must be a valid product category from
the Numeral taxonomy — an invalid value returns a 400. If a matching
product is found, its stored category takes precedence.
example: GENERAL_MERCHANDISE
amount:
type: integer
minimum: 0
maximum: 9999999999999
description: >-
The **total price of this line item** (not per-unit) in the
currency's smallest unit (e.g., if USD then 2000 = $20.00, if JPY
then 2000 = ¥2000). Tax is calculated against this value as-is;
`quantity` does not multiply it. Per-unit semantics start in API
version 2026-01-01.
example: 2000
quantity:
type: integer
minimum: 1
maximum: 999999999
description: >-
The quantity of this product being sold. In this API version it is
used for record keeping only — it does not affect the taxable base.
example: 2
required:
- quantity
- amount
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````