> ## 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 or IP
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:
```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: 2026-03-01' \
--data '{ ... }'
```
**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`).
## 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:
```json theme={null}
{
"customer": {
"type": "CONSUMER",
"ip": {
"value": "217.217.113.167",
"resolution": "strict"
}
}
}
```
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
| Mode | Behavior |
| ------------------ | ------------------------------------------------------------------- |
| `strict` (default) | Error if IP cannot resolve to sufficient detail for tax calculation |
| `zero` | Return zero-rate response if resolution is insufficient |
| `approximate` | Attempts to resolve the IP to an address using heuristics |
| `best_effort` | Try approximate first, fall back to zero rates |
Numeral strongly recommends using `strict` mode to stay as compliant as possible.
### New Response Fields
| Field | Description |
| ---------------------- | --------------------------------------------------------------------------- |
| `location_source` | `"address"` or `"ip"` -- which input was used |
| `resolution_precision` | `STREET`, `POSTAL_PLUS`, `POSTAL`, `PROVINCE`, `COUNTRY`, or `APPROXIMATED` |
| `address_used` | The resolved address used for tax calculation |
### IP Resolution Errors
| Error Type | HTTP Code | Description |
| ------------------------------- | --------- | ---------------------------------------------------------------- |
| `INVALID_IP_FORMAT` | 400 | `ip.value` is not a valid IPv4 or IPv6 address |
| `IP_RESOLUTION_FAILED` | 422 | IP could not be resolved to any country |
| `IP_RESOLUTION_INSUFFICIENT_US` | 422 | IP resolved to a US state but no postal code could be determined |
| `IP_RESOLUTION_INSUFFICIENT_CA` | 422 | IP resolved to Canada but no province could be determined |
See the complete list of error types and their meanings.
## OpenAPI
````yaml api-reference/v2026-03-01/openapi.json POST /tax/calculations
openapi: 3.0.1
info:
title: Numeral API
description: >-
API for sales tax calculations - Version 2026-03-01. This version adds
IP-based tax resolution for calculations and platform calculations, in
addition to Merchant management and Platform Calculations.
license:
name: MIT
version: '2026-03-01'
servers:
- url: https://api.numeralhq.com/
security:
- bearerAuth: []
paths:
/tax/calculations:
post:
description: Get tax information for a given product and address or IP
parameters:
- name: X-API-Version
in: header
required: true
schema:
type: string
enum:
- '2026-03-01'
default: '2026-03-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`, NOT this version.
example: '2026-03-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CalculationRequest'
examples:
address_based:
summary: Address-based tax calculation
value:
customer:
address:
address_city: Nashville
address_country: US
address_line_1: 123 Broadway
address_postal_code: '37203'
address_province: TN
address_type: billing
metadata:
payment_id: 68407cb7-e1fa-47fa-8244-bd9411d53c61
order_details:
automatic_tax: auto
customer_currency_code: USD
line_items:
- amount: 10000
product_category: BEVERAGES
quantity: 1
- amount: 10000
product_category: GENERAL_MERCHANDISE
quantity: 1
tax_included_in_amount: false
origin_address:
address_city: Nashville
address_country: US
address_line_1: 500 Church St
address_line_2: ''
address_postal_code: '37219'
address_province: TN
ip_based:
summary: IP-based tax calculation
value:
customer:
type: CONSUMER
ip:
value: 217.217.113.167
resolution: strict
order_details:
customer_currency_code: USD
tax_included_in_amount: false
automatic_tax: auto
line_items:
- product_category: SAAS_GENERAL
reference_line_item_id: ip-test-001
amount: 10000
quantity: 5
with_partner_fallbacks:
summary: >-
Calculation with default_customer_type and
fallback_product_category
description: >-
Integration-partner pattern: always send customer_id and
reference_product_id, and let Numeral fall back gracefully
when either has not been created yet.
value:
customer:
id: cus_not_yet_in_numeral
address:
address_city: Nashville
address_country: US
address_line_1: 123 Broadway
address_postal_code: '37203'
address_province: TN
address_type: billing
default_customer_type: CONSUMER
order_details:
automatic_tax: auto
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
origin_address:
address_city: Nashville
address_country: US
address_line_1: 500 Church St
address_postal_code: '37219'
address_province: TN
required: true
responses:
'200':
description: Calculate response
content:
application/json:
schema:
$ref: '#/components/schemas/CalculationResponse'
examples:
address_based:
summary: Address-based calculation response
value:
testmode: true
id: calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3
object: tax.calculation
customer_currency_code: USD
line_items:
- line_item_id: li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f7f
product:
reference_line_item_id: ''
reference_product_id: default-beverages
reference_product_name: Default BEVERAGES Product
product_tax_code: BEVERAGES
tax_jurisdictions:
- tax_rate: 0.07
tax_due_decimal: 700
fee_amount: 0
rate_type: GENERAL STATE SALES TAX
tax_authority_name: Tennessee
tax_authority_type: ''
tax_type: SALES
- tax_rate: 0.0225
tax_due_decimal: 225
fee_amount: 0
rate_type: GENERAL COUNTY LOCAL SALES TAX
tax_authority_name: DAVIDSON
tax_authority_type: ''
tax_type: SALES
tax_amount: 925
amount_excluding_tax: 10000
amount_including_tax: 10925
quantity: 1
- line_item_id: li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f80
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.07
tax_due_decimal: 700
fee_amount: 0
rate_type: GENERAL STATE SALES TAX
tax_authority_name: Tennessee
tax_authority_type: ''
tax_type: SALES
- tax_rate: 0.0225
tax_due_decimal: 225
fee_amount: 0
rate_type: GENERAL COUNTY LOCAL SALES TAX
tax_authority_name: DAVIDSON
tax_authority_type: ''
tax_type: SALES
tax_amount: 925
amount_excluding_tax: 10000
amount_including_tax: 10925
quantity: 1
total_tax_amount: 1850
tax_included_in_amount: false
total_amount_excluding_tax: 20000
total_amount_including_tax: 21850
expires_at: 1783456061
metadata:
payment_id: 68407cb7-e1fa-47fa-8244-bd9411d53c61
customer:
type: CONSUMER
automatic_tax: auto
address_resolution_status: EXACT
address_used:
address_line_1: 123 Broadway
address_city: Nashville
address_province: TN
address_postal_code: '37203'
address_country: US
location_source: address
resolution_precision: STREET
ip_based:
summary: IP-based calculation response
value:
testmode: true
id: calc_17725714816806a81b828-0757-4ec2-9307-3c1001733f73
object: tax.calculation
customer_currency_code: USD
line_items:
- line_item_id: li_1772571481680b3f8d264-9a15-4e72-bc48-05d6f2a81c93
product:
reference_line_item_id: ip-test-001
reference_product_id: default-saas-general
reference_product_name: Default SAAS_GENERAL Product
product_tax_code: SAAS_GENERAL
tax_jurisdictions:
- tax_rate: 0.06
tax_due_decimal: 3000
fee_amount: 0
rate_type: GENERAL STATE SALES TAX
tax_authority_name: Pennsylvania
tax_authority_type: ''
tax_type: SALES
- tax_rate: 0.01
tax_due_decimal: 500
fee_amount: 0
rate_type: GENERAL COUNTY LOCAL SALES TAX
tax_authority_name: ALLEGHENY
tax_authority_type: ''
tax_type: SALES
tax_amount: 3500
amount_excluding_tax: 50000
amount_including_tax: 53500
quantity: 5
total_tax_amount: 3500
tax_included_in_amount: false
total_amount_excluding_tax: 50000
total_amount_including_tax: 53500
expires_at: 1772657881
customer:
type: CONSUMER
automatic_tax: auto
address_resolution_status: POSTAL_ONLY
address_used:
address_line_1: ''
address_line_2: ''
address_city: ''
address_province: PA
address_postal_code: '15212'
address_country: US
location_source: ip
resolution_precision: POSTAL
with_partner_fallbacks:
summary: >-
Response when default_customer_type and
fallback_product_category were used
value:
testmode: true
id: calc_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d4
object: tax.calculation
customer_currency_code: USD
line_items:
- line_item_id: li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f81
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.07
tax_due_decimal: 700
fee_amount: 0
rate_type: GENERAL STATE SALES TAX
tax_authority_name: Tennessee
tax_authority_type: ''
tax_type: SALES
- tax_rate: 0.0225
tax_due_decimal: 225
fee_amount: 0
rate_type: GENERAL COUNTY LOCAL SALES TAX
tax_authority_name: DAVIDSON
tax_authority_type: ''
tax_type: SALES
tax_amount: 925
amount_excluding_tax: 10000
amount_including_tax: 10925
quantity: 1
total_tax_amount: 925
tax_included_in_amount: false
total_amount_excluding_tax: 10000
total_amount_including_tax: 10925
expires_at: 1783456061
customer:
type: CONSUMER
automatic_tax: auto
address_resolution_status: EXACT
address_used:
address_line_1: 123 Broadway
address_city: Nashville
address_province: TN
address_postal_code: '37203'
address_country: US
location_source: address
resolution_precision: STREET
'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'
'422':
description: >-
IP resolution error - the IP address could not be resolved to
sufficient detail
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/IpResolutionFailedError'
- $ref: '#/components/schemas/IpResolutionInsufficientUsError'
- $ref: '#/components/schemas/IpResolutionInsufficientCaError'
components:
schemas:
CalculationRequest:
type: object
properties:
customer:
$ref: '#/components/schemas/CustomerDetails'
description: >-
Customer details. At least one of `customer.address` or
`customer.ip` must be provided. 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. 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'
transacted_at:
type: integer
description: >-
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:
type: string
enum:
- CONSUMER
- BUSINESS
description: >-
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.
example: CONSUMER
invalid_tax_id_customer_fallback_type:
type: string
enum:
- CONSUMER
description: >-
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.
example: CONSUMER
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_178336966110780ac0407-1c52-4322-972c-9fef2eb1b1d3
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. `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).
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:
$ref: '#/components/schemas/TaxId'
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'
location_source:
type: string
enum:
- address
- ip
description: Which input was used for tax determination.
example: address
resolution_precision:
type: string
enum:
- STREET
- POSTAL_PLUS
- POSTAL
- PROVINCE
- COUNTRY
- APPROXIMATED
description: The precision level of the resolved location.
example: POSTAL
Error:
type: object
description: Standard error response format for API version 2026-01-01
properties:
code:
type: integer
description: HTTP status code
example: 400
type:
type: string
description: Machine-readable error type
example: MISSING_FIELD
message:
type: string
description: Human-readable error message
example: Required field 'address_country' is missing
required:
- code
- type
- message
ProductNotFoundError:
type: object
properties:
code:
type: integer
example: 404
type:
type: string
example: PRODUCT_NOT_FOUND
message:
type: string
example: Product not found
IpResolutionFailedError:
type: object
properties:
code:
type: integer
example: 422
type:
type: string
example: IP_RESOLUTION_FAILED
message:
type: string
example: >-
Unable to resolve IP address to a country. Please provide a full
address in customer.address.
IpResolutionInsufficientUsError:
type: object
properties:
code:
type: integer
example: 422
type:
type: string
example: IP_RESOLUTION_INSUFFICIENT_US
message:
type: string
example: >-
IP address resolved to a US state but could not determine a postal
code. Please provide customer.address with address_postal_code and
address_province.
IpResolutionInsufficientCaError:
type: object
properties:
code:
type: integer
example: 422
type:
type: string
example: IP_RESOLUTION_INSUFFICIENT_CA
message:
type: string
example: >-
IP address resolved to CA but could not determine a province. Please
provide customer.address with address_province.
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. Pair with the top-level `default_customer_type` to avoid a
400 when the ID has not yet been created in Numeral.
example: cust_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 (not enforced for
IP-only requests).
items:
$ref: '#/components/schemas/TaxId'
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. Optional when `ip` is provided —
with an IP present, address-quality problems fall back to IP
resolution instead of returning a 400. Supports 82 destination
countries: 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_postal_code` is required and `address_province` is
required — a valid uppercase USPS state code for US, province code
for CA. Fallback only: if `address_province` 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`.
Do not rely on this — always send the state.
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 `UNRECOGNIZED_FIELD`
error.
example: shipping
required:
- address_type
ip:
type: object
description: >-
IP address for geo-based tax resolution. Either address or ip (or
both) must be provided. If both are given, the address is used first
and the IP acts as a fallback for address-quality errors. An invalid
IP format returns a 400 `INVALID_IP_FORMAT`.
properties:
value:
type: string
description: >-
A valid IPv4 or IPv6 address. Only required when an `ip` object
is provided — omit `ip` entirely for address-only calculations.
example: 217.217.113.167
resolution:
type: string
enum:
- strict
- zero
- approximate
- best_effort
description: >-
How to handle insufficient IP resolution. strict (default):
error if insufficient. zero: return zero-rate. approximate:
attempt to resolve using heuristics. best_effort: try
approximate, fall back to zero.
default: strict
required:
- value
description: Customer details. At least one of address or ip must be provided.
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. 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, 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
TaxId:
type: object
properties:
type:
type: string
description: >-
Country-specific Stripe-style tax ID type (e.g., `us_ein`, `eu_vat`,
`gb_vat`, `au_abn`, `ca_gst_hst`). See [Tax
IDs](/essentials/tax-ids) for the full list of supported types.
example: us_ein
value:
type: string
minLength: 1
maxLength: 100
description: The tax ID value (1-100 characters).
example: 12-3456789
required:
- type
- value
TransactionLineItem:
type: object
properties:
line_item_id:
type: string
description: Numeral-generated ID for this line item.
example: li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f7f
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, rounded to 6 decimal
places.
example: 0.07
tax_due_decimal:
type: number
description: >-
The unrounded tax due for this jurisdiction, in the currency's
smallest unit. May be fractional (it is not rounded to an
integer). `0` for flat-fee jurisdictions — see `fee_amount`
instead.
example: 724.9275
fee_amount:
type: number
description: Any fixed fee amount for this jurisdiction.
example: 0
rate_type:
type: string
description: Descriptive rate classification for this jurisdiction.
example: GENERAL STATE SALES TAX
tax_authority_name:
type: string
description: Name of the tax authority.
example: Tennessee
tax_authority_type:
type: string
description: Type of tax authority (e.g., STATE, COUNTY, CITY, DISTRICT).
example: ''
tax_type:
type: string
description: 'Type of tax: SALES, USE, VAT, or GST.'
example: SALES
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 **per-unit price** in the currency's smallest unit. The taxable
base is calculated as `amount x quantity`. (e.g., if USD then 2000 =
$20.00 per unit; with `quantity: 3` the taxable base is $60.00.)
Before 2026-01-01, `amount` was the total for the line.
example: 2000
quantity:
type: integer
minimum: 1
maximum: 999999999
description: >-
The quantity of this product being sold. The taxable base is `amount
x quantity`.
example: 1
required:
- quantity
- amount
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````