> ## 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. ## 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-01-01' \ --data '{ ... }' ``` **New in 2026-01-01:** * The `amount` field on line items is now **per-unit price** (taxable base = `amount x quantity`). * `customer.tax_ids` use country-specific Stripe-style types (`us_ein`, `eu_vat`, `gb_vat`, ...) instead of `VAT`/`GST`/`EIN`. * New optional top-level `invalid_tax_id_customer_fallback_type` (`"CONSUMER"`): fall back to CONSUMER treatment instead of a 400 when business tax ID validation fails. * Response `tax_jurisdictions` use the enhanced format below; errors use a new flat format. (`address_resolution_status`, `address_used`, and the `metadata` echo already existed in 2025-05-12.) ## Per-Unit Pricing Starting with version 2026-01-01, the `amount` field on line items represents the **per-unit price** rather than the total line item value: ```json theme={null} { "amount": 2500, // $25.00 per unit "quantity": 3 // taxable base = $75.00 } ``` If you are migrating from 2025-05-12 or earlier, you must update your integration to send per-unit prices instead of total line item values. ## Enhanced Tax Jurisdictions Tax jurisdiction objects now include richer detail: | Field | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `tax_due_decimal` | Unrounded tax due for this jurisdiction, in the currency's smallest unit (may be fractional; `0` for flat-fee rows — see `fee_amount`) | | `tax_authority_name` | Name of the tax authority (e.g., "Tennessee", "ALLEGHENY") | | `tax_authority_type` | Type of authority (e.g., "STATE", "COUNTY", "CITY", "DISTRICT") | | `tax_type` | Type of tax: `SALES`, `USE`, `VAT`, or `GST` | | `rate_type` | Descriptive rate classification (e.g., "GENERAL STATE SALES TAX") | The `jurisdiction_name` and `note` fields from prior versions are no longer included. **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. ## Error Format Error responses now use a flat format: `{ "code": number, "type": "ERROR_TYPE", "message": "..." }`. See the complete list of error types and their meanings. ## OpenAPI ````yaml api-reference/v2026-01-01/openapi.json POST /tax/calculations openapi: 3.0.1 info: title: Numeral API description: >- API for sales tax calculations - Version 2026-01-01. This version introduces Merchant management and Platform Calculations for marketplace and payment processor scenarios. license: name: MIT version: '2026-01-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: - '2026-01-01' default: '2026-01-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-01-01' requestBody: content: application/json: schema: $ref: '#/components/schemas/CalculationRequest' examples: consumer: summary: Consumer calculation with origin address 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 business: summary: Business customer with tax IDs value: customer: type: BUSINESS tax_ids: - type: eu_vat value: DE123456789 address: address_line_1: 10 Downing Street address_city: London address_province: Greater London address_postal_code: SW1A 2AA address_country: GB address_type: shipping origin_address: address_line_1: 500 Church St address_city: Nashville address_province: TN address_postal_code: '37219' address_country: US order_details: customer_currency_code: GBP tax_included_in_amount: false automatic_tax: auto line_items: - reference_line_item_id: line_123456789 product_category: SAAS_GENERAL amount: 10000 quantity: 2 with_fallback_product_category: summary: Calculation with fallback_product_category value: customer: address: address_city: Nashville address_country: US address_line_1: 123 Broadway address_postal_code: '37203' address_province: TN address_type: billing 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: consumer: summary: Consumer calculation response (raw tax jurisdictions) value: testmode: true id: calc_1783369695581b8ca8647-a864-40f4-bf8a-10ff46f50856 object: tax.calculation customer_currency_code: USD line_items: - line_item_id: li_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd7 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_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd8 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: 1783456095 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 business: summary: Business customer response with tax IDs value: testmode: true id: calc_1783369695581b8ca8647-a864-40f4-bf8a-10ff46f50857 object: tax.calculation customer_currency_code: GBP line_items: - line_item_id: li_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd9 product: reference_line_item_id: line_123456789 reference_product_id: default-saas-general reference_product_name: Default SAAS_GENERAL Product product_tax_code: SAAS_GENERAL tax_jurisdictions: - tax_rate: 0.2 tax_due_decimal: 4000 fee_amount: 0 rate_type: STANDARD COUNTRY LOCAL VAT TAX tax_authority_name: GB tax_authority_type: '' tax_type: VAT tax_amount: 4000 amount_excluding_tax: 20000 amount_including_tax: 24000 quantity: 2 total_tax_amount: 4000 tax_included_in_amount: false total_amount_excluding_tax: 20000 total_amount_including_tax: 24000 expires_at: 1783456095 customer: type: BUSINESS tax_ids: - type: eu_vat value: DE123456789 automatic_tax: auto address_resolution_status: POSTAL_ONLY address_used: address_line_1: 10 Downing Street address_city: London address_province: Greater London address_postal_code: SW1A 2AA address_country: GB with_fallback_product_category: summary: Response when the fallback product category was used value: testmode: true id: calc_1783369695581b8ca8647-a864-40f4-bf8a-10ff46f50858 object: tax.calculation customer_currency_code: USD line_items: - line_item_id: li_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19ce0 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: 1783456095 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 '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: >- 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' 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_1783369695581b8ca8647-a864-40f4-bf8a-10ff46f50856 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 `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' 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 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. 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. 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_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 `UNRECOGNIZED_FIELD` error. 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. 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_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd7 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. 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 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 ````