> ## 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
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.
## 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:
```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: 2024-09-01' \
--data '{ ... }'
```
## OpenAPI
````yaml api-reference/v2024-09-01/openapi.json POST /tax/calculations
openapi: 3.0.1
info:
title: Numeral API
description: API for sales tax calculations - Version 2024-09-01
license:
name: MIT
version: '2024-09-01'
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:
- '2024-09-01'
default: '2024-09-01'
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`, but an account default set to a
newer version takes precedence over that fallback.
example: '2024-09-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CalculationRequest'
examples:
basic:
summary: Basic calculation
value:
customer:
address:
address_line_1: 4 Privet Drive
address_city: Little Whinging
address_province: CA
address_postal_code: '90210'
address_country: US
address_type: shipping
order_details:
customer_currency_code: USD
tax_included_in_amount: false
line_items:
- reference_product_id: wand_elder_12
amount: 10000
quantity: 1
with_fallback_product_category:
summary: Calculation with fallback_product_category
value:
customer:
address:
address_line_1: 4 Privet Drive
address_city: Little Whinging
address_province: CA
address_postal_code: '90210'
address_country: US
address_type: shipping
order_details:
customer_currency_code: USD
tax_included_in_amount: false
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:
basic:
summary: Basic calculation response
value:
testmode: true
id: calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c
object: tax.calculation
customer_currency_code: USD
line_items:
- line_item_id: li_1783369478353396a9168-1972-4798-80cb-536d96c0cc5a
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: 1783455878
with_fallback_product_category:
summary: Response when the fallback product category was used
value:
testmode: true
id: calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49d
object: tax.calculation
customer_currency_code: USD
line_items:
- line_item_id: li_1783369478353396a9168-1972-4798-80cb-536d96c0cc5b
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: 1783455878
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'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: >-
Optional, but relevant for tax collection in certain jurisdictions.
The address that a product is shipped from.
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_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c
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
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
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.
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
address:
description: >-
The customer (destination) address. In API version 2024-09-01,
`address_country` must be one of: US, CA, or an EU member state (AT,
BE, BG, HR, CZ, DE, DK, EE, FI, FR, GR, HU, IE, IT, LV, LT, LU, MT,
NL, PL, PT, RO, SK, SI, ES, SE). 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
enum:
- EUR
- RON
- PLN
- DKK
- HUF
- CZK
- BGN
- SEK
- USD
- CAD
description: >-
The ISO-4217 currency code of the transaction. API version
2024-09-01 supports exactly these 10 currencies: EUR, RON, PLN, DKK,
HUF, CZK, BGN, SEK, USD, CAD.
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
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
- 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_1783369478353396a9168-1972-4798-80cb-536d96c0cc5a
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.
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). 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
````